Update documentation for v0.3

Auto-generated from v0.3.0-2-g398fdf5 by 'update-gh-pages.sh'

releases/releases.js

@@ -6,5 +6,6 @@ function getReleaseListItems() {
     { name: 'v0.2.2', url: 'v0.2.2' },
     { name: 'v0.2.3', url: 'v0.2.3' },
     { name: 'v0.3.0', url: 'v0.3.0' },
+    { name: 'v0.3.1', url: 'v0.3.1' },
   ];
 }

releases/v0.3.1/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: f7b27a05dc592576e0d90818d7dbd683
+tags: 645f666f9bcd5a90fca523b33c5a78b7

releases/v0.3.1/_sources/deployment/operator/README.md.txt

@@ -0,0 +1,69 @@
+# NRI-Plugins-Operator 
+
+## Introduction
+
+The nri-plugins-operator is an Ansible-based operator created with operator-sdk to manage the life cycle of the
+nri-plugins. The operator deploys community maintained [nri-plugins](https://github.com/containers/nri-plugins) in
+Kubernetes cluster. When operator is installed, it doesn't do anything apart from watching for custom resources called
+NriPluginDeployment. When NriPluginDeployment object is created, reconciliation loops kicks off and installs the
+nri-plugin specified in the NriPluginDeployment. 
+
+## Installation
+
+Build the operator image and push it to some registry
+```shell
+make -C deployment/operator docker-build docker-push IMG="my-registry.com/nri-plugins-operator:unstable"
+```
+
+Deploy the operator in your cluster
+```shell
+make -C deployment/operator deploy
+```
+
+Uninstall the operator
+```shell
+make -C deployment/operator undeploy
+```
+
+## Operator CRD
+
+```YAML
+apiVersion: config.nri/v1alpha1
+kind: NriPluginDeployment
+metadata:
+  name: nriplugindeployment-sample
+  namespace: kube-system
+spec:
+  pluginName: topology-aware
+  pluginVersion: "v0.2.3"
+  state: present
+  values:
+    nri:
+      patchRuntimeConfig: true
+    tolerations:
+      - key: "node-role.kubernetes.io/control-plane"
+        operator: "Exists"
+        effect: "NoSchedule"
+    affinity:
+      nodeAffinity:
+        requiredDuringSchedulingIgnoredDuringExecution:
+          nodeSelectorTerms:
+            - matchExpressions:
+                - key: topology.kubernetes.io/disk
+                  operator: In
+                  values:
+                    - ssd
+```
+
+- `metadata.namespace`: the same namespace is used to install the nri-plugin Helm chart.
+- `spec.pluginName`: This field specifies the desired plugin to be installed, with currently accepted values including 
+  topology-aware, balloons, memtierd, memory-qos, or sgx-epc.  The list of allowed nri-plugins is expected to grow as
+  new plugins are introduced. The field is immutable and to deploy a different plugin you need to re-create the object
+  or create a new one with different name and namespace.
+- `spec.pluginVersion`: specifies the version of the plugin. If not indicated, it defaults to the latest version. The
+  plugin version is mutable, and updating it will uninstall the current version before installing the updated one.
+- `spec.state`: Determines whether to install (`present`) or uninstall (`absent`) the plugin.
+- `spec.values`: Allows users to provide custom values for manipulating Helm chart values. This field is immutable, 
+  requiring users to recreate the object to pass new values.
+- `spec.status`: Tracks the basic state of the resource and includes basic messages in case the operator encounters 
+  issues while reconciling the object.

releases/v0.3.1/_sources/docs/contributing.md.txt

@@ -0,0 +1,10 @@
+# Contributing
+
+Please use the GitHub\* infrastructure for contributing to NRI Plugins.
+Use [pull requests](https://github.com/containers/nri-plugins/pulls)
+to contribute code, bug fixes, or if you want to discuss your ideas in terms of
+code. Open [issues](https://github.com/containers/nri-plugins/issues) to
+report bugs, request new features, or if you want to discuss any other topics
+related to NRI plugins.
+
+For the actual NRI (Node Resource Interface) API, please see [NRI repository](https://github.com/containerd/nri)

releases/v0.3.1/_sources/docs/deployment/helm/balloons.md.txt

@@ -0,0 +1,2 @@
+```{include} ../../../deployment/helm/balloons/README.md
+```

releases/v0.3.1/_sources/docs/deployment/helm/index.md.txt

@@ -0,0 +1,33 @@
+# Helm
+
+All the available charts can be found in [artifacthub.io](https://artifacthub.io/packages/search?ts_query_web=nri&verified_publisher=true&official=true&sort=relevance&page=1).
+
+**NOTE:** NRI-plugins Helm installation has been successfully verified in both local clusters and major Cloud Providers' managed clusters, including:
+
+   -  AWS EKS
+        - kubernetes version: 1.28.x
+        - containerd version: 1.7
+        - node image: Amazon Linux 2, Ubuntu 20.04, 
+   - Google GKE
+        - kubernetes version: 1.28.x
+        - containerd version: 1.7
+        - node image: Container-Optimized OS from Google (COS), Ubuntu 22.04 
+   -  Azure AKS
+        - kubernetes version: 1.28.x
+        - containerd version: 1.7
+        - node image: Azure Linux Container Host, Ubuntu 20.04
+
+While Ubuntu 20.04/22.04 was used across all three CSP environments, it's worth noting that node images are not limited to Ubuntu 20.04/22.04 only. The majority of widely recognized Linux distributions should be suitable for use.
+
+```{toctree}
+---
+maxdepth: 2
+caption: Contents
+---
+balloons.md
+topology-aware.md
+template.md
+memory-qos.md
+memtierd.md
+sgx-epc.md
+```

releases/v0.3.1/_sources/docs/deployment/helm/memory-qos.md.txt

@@ -0,0 +1,2 @@
+```{include} ../../../deployment/helm/memory-qos/README.md
+```

releases/v0.3.1/_sources/docs/deployment/helm/memtierd.md.txt

@@ -0,0 +1,2 @@
+```{include} ../../../deployment/helm/memtierd/README.md
+```

releases/v0.3.1/_sources/docs/deployment/helm/sgx-epc.md.txt

@@ -0,0 +1,2 @@
+```{include} ../../../deployment/helm/sgx-epc/README.md
+```

releases/v0.3.1/_sources/docs/deployment/helm/template.md.txt

@@ -0,0 +1,2 @@
+```{include} ../../../deployment/helm/template/README.md
+```

releases/v0.3.1/_sources/docs/deployment/helm/topology-aware.md.txt

@@ -0,0 +1,2 @@
+```{include} ../../../deployment/helm/topology-aware/README.md
+```

releases/v0.3.1/_sources/docs/deployment/index.md.txt

@@ -0,0 +1,12 @@
+# Deployment
+
+Currently supported installation methods of the NRI plugins are Helm and Operator.
+
+```{toctree}
+---
+maxdepth: 2
+caption: Contents
+---
+helm/index.md
+operator/index.md
+```

releases/v0.3.1/_sources/docs/deployment/operator/index.md.txt

@@ -0,0 +1,9 @@
+# Operator
+
+```{toctree}
+---
+maxdepth: 2
+caption: Contents
+---
+operator.md
+```

releases/v0.3.1/_sources/docs/deployment/operator/operator.md.txt

@@ -0,0 +1,2 @@
+```{include} ../../../deployment/operator/README.md
+```

releases/v0.3.1/_sources/docs/index.md.txt

@@ -0,0 +1,14 @@
+# Welcome to NRI Plugins documentation
+
+```{toctree}
+---
+maxdepth: 2
+caption: Contents
+---
+introduction.md
+resource-policy/index.rst
+memory/index.md
+deployment/index.md
+contributing.md
+Project GitHub repository <https://github.com/containers/nri-plugins>
+```

releases/v0.3.1/_sources/docs/introduction.md.txt

@@ -0,0 +1,7 @@
+# Introduction
+
+The NRI plugins is a collection of NRI (Node Resource Interface) based plugins
+to manage various aspects of pod and container life cycle. For example the
+[resource policy plugins](resource-policy/policy/index.md) can be used to
+modify the container resource allocation depending on available system
+resources.

releases/v0.3.1/_sources/docs/memory/index.md.txt

@@ -0,0 +1,11 @@
+# Memory plugins
+
+```{toctree}
+---
+maxdepth: 2
+caption: Contents
+---
+memory-qos.md
+memtierd.md
+sgx-epc.md
+```

releases/v0.3.1/_sources/docs/memory/memory-qos.md.txt

@@ -0,0 +1,158 @@
+# Memory QoS NRI plugin
+
+This NRI plugin adds two methods for controlling cgroups v2 `memory.*`
+parameters: memory QoS classes and direct memory annotations.
+
+## Workload configuration
+
+There are two configuration methods:
+
+1. Memory QoS classes: memory parameters are calculated in the same
+   way for all workloads that belong to the same class.
+2. Direct workload-specific memory parameters.
+
+Memory QoS class of a pod or a container is defined using annotations
+in pod yaml:
+
+```yaml
+  annotations:
+    # Set the default memory QoS class for all containers in this pod.
+    class.memory-qos.nri.io: silver
+
+    # Override the default class for the c0 container.
+    class.memory-qos.nri.io/c0: bronze
+
+    # Remove the default class from the c1 container.
+    class.memory-qos.nri.io/c1: ""
+```
+
+Cgroups v2 memory parameters are given pod annotations. Following
+example affects `memory.swap.max`, `memory.high` and
+`memory.oom.group`:
+
+```yaml
+  annotations:
+    # Never swap memory of the noswap container in this pod.
+    memory.swap.max.memory-qos.nri.io/noswap: "0"
+    memory.high.memory-qos.nri.io/noswap: max
+
+    # For all containers: if a process gets OOM killed,
+    # do not group-kill the whole cgroup.
+    memory.oom.group.memory-qos.nri.io: "0"
+```
+
+## Plugin configuration
+
+### Classes
+
+Plugin configuration lists memory QoS classes and their parameters
+that affect calculating actual memory parameters.
+
+`classes:` is followed by list of maps with following keys and values:
+
+- `name` (string): name of the memory QoS class, matches
+  `class.memory-qos.nri.io` annotation values.
+- `swaplimitratio` (from 0.0 to 1.0): minimum ratio of container's
+  memory on swap and resources.limits.memory when container's memory
+  consumption reaches the limit. Adjusts `memory.high` watermark to
+  `resources.limits.memory * (1.0 - swaplimitratio)`.
+
+### Unified annotations
+
+`unifiedannotations:` (list of strings): OCI Linux unified fields
+(cgroups v2 file names) whose values are allowed to be set using
+direct annotations. If annotations define these values, they override
+values implied by container's memory QoS class.
+
+### Example
+
+```yaml
+classes:
+- name: bronze
+  swaplimitratio: 0.5
+- name: silver
+  swaplimitratio: 0.2
+unifiedannotations:
+- memory.swap.max
+- memory.high
+```
+
+This configuration defines the following.
+
+- If a container belogs to the memory QoS class `bronze` has allocated
+  half of the memory of its `resources.limits.memory`, next
+  allocations will cause kernel to swap out corresponding amount of
+  container's memory. In other words, when container's memory usage is
+  close to the limit, at most half of its data is stored in RAM.
+- Containers in `silver` class are allowed to keep up to 80 % of their
+  data in RAM when reaching memory limit.
+- Memory annotations are allowed to modify `memory.swap.max` and
+  `memory.high` values directly but, for instance, modifying
+  `memory.oom.group` is not enabled by this configuration.
+
+## Developer's guide
+
+### Prerequisites
+
+- Containerd v1.7+
+- Enable NRI in /etc/containerd/config.toml:
+
+  ```toml
+  [plugins."io.containerd.nri.v1.nri"]
+    disable = false
+    disable_connections = false
+    plugin_config_path = "/etc/nri/conf.d"
+    plugin_path = "/opt/nri/plugins"
+    plugin_registration_timeout = "5s"
+    plugin_request_timeout = "2s"
+    socket_path = "/var/run/nri/nri.sock"
+  ```
+
+### Build
+
+```bash
+cd cmd/plugins/memory-qos && go build .
+```
+
+### Run
+
+```bash
+cmd/plugins/memory-qos/memory-qos -config sample-configs/nri-memory-qos.yaml -idx 40 -vv
+```
+
+### Manual test
+
+```bash
+kubectl create -f test/e2e/files/nri-memory-qos-test-pod.yaml
+```
+
+See swap status of dd processes, each allocating the same amount of
+memory:
+
+```bash
+for pid in $(pidof dd); do
+    grep VmSwap /proc/$pid/status
+done
+```
+
+### Debug
+
+```bash
+go install github.com/go-delve/delve/cmd/dlv@latest
+dlv exec cmd/plugins/memory-qos/memory-qos -- -config sample-configs/nri-memory-qos.yaml -idx 40
+(dlv) break plugin.CreateContainer
+(dlv) continue
+```
+
+### Deploy
+
+Build an image, import it on the node, and deploy the plugin by
+running the following in `nri-plugins`:
+
+```bash
+rm -rf build
+make clean
+make PLUGINS=nri-memory-qos IMAGE_VERSION=devel images
+ctr -n k8s.io images import build/images/nri-memory-qos-image-*.tar
+kubectl create -f build/images/nri-memory-qos-deployment.yaml
+```