From 6785ffdfad8bb81b4560eabf4a8928b8d5409643 Mon Sep 17 00:00:00 2001 From: Github Date: Fri, 29 Sep 2023 14:48:10 +0000 Subject: [PATCH] Update documentation for devel Auto-generated from v0.1.0-38-g246e1f7 by 'update-gh-pages.sh' --- devel/.buildinfo | 2 +- devel/_sources/docs/index.md.txt | 1 + devel/_sources/docs/memory/index.md.txt | 9 + devel/_sources/docs/memory/memory-qos.md.txt | 155 +++++++++ devel/_static/documentation_options.js | 2 +- devel/docs/contributing.html | 7 +- devel/docs/index.html | 7 +- devel/docs/introduction.html | 3 +- devel/docs/memory/index.html | 163 +++++++++ devel/docs/memory/memory-qos.html | 325 ++++++++++++++++++ devel/docs/resource-policy/configuration.html | 3 +- .../developers-guide/architecture.html | 25 +- .../developers-guide/cpu-allocator.html | 7 +- .../developers-guide/e2e-test.html | 3 +- .../developers-guide/index.html | 3 +- .../developers-guide/testing.html | 3 +- .../developers-guide/unit-test.html | 3 +- devel/docs/resource-policy/index.html | 3 +- devel/docs/resource-policy/installation.html | 3 +- devel/docs/resource-policy/introduction.html | 3 +- .../docs/resource-policy/policy/balloons.html | 3 +- devel/docs/resource-policy/policy/index.html | 3 +- .../policy/topology-aware.html | 3 +- devel/docs/resource-policy/setup.html | 3 +- devel/genindex.html | 3 +- devel/objects.inv | Bin 573 -> 611 bytes devel/search.html | 3 +- devel/searchindex.js | 2 +- releases/.doctrees/environment.pickle | Bin 12834 -> 12834 bytes 29 files changed, 713 insertions(+), 37 deletions(-) create mode 100644 devel/_sources/docs/memory/index.md.txt create mode 100644 devel/_sources/docs/memory/memory-qos.md.txt create mode 100644 devel/docs/memory/index.html create mode 100644 devel/docs/memory/memory-qos.html diff --git a/devel/.buildinfo b/devel/.buildinfo index ff76dca11..dfa6e8ccf 100644 --- a/devel/.buildinfo +++ b/devel/.buildinfo @@ -1,4 +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: 096e5cb6a6b51a425ab1cbc90a0b8e52 +config: 075dee4d7e63f1e6bbb9b28fa166bb14 tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/devel/_sources/docs/index.md.txt b/devel/_sources/docs/index.md.txt index 628226361..1aa33fb9a 100644 --- a/devel/_sources/docs/index.md.txt +++ b/devel/_sources/docs/index.md.txt @@ -7,6 +7,7 @@ caption: Contents --- introduction.md resource-policy/index.rst +memory/index.md contributing.md Project GitHub repository ``` diff --git a/devel/_sources/docs/memory/index.md.txt b/devel/_sources/docs/memory/index.md.txt new file mode 100644 index 000000000..5f1d68b37 --- /dev/null +++ b/devel/_sources/docs/memory/index.md.txt @@ -0,0 +1,9 @@ +# Memory plugins + +```{toctree} +--- +maxdepth: 2 +caption: Contents +--- +memory-qos.md +``` diff --git a/devel/_sources/docs/memory/memory-qos.md.txt b/devel/_sources/docs/memory/memory-qos.md.txt new file mode 100644 index 000000000..da13faf6e --- /dev/null +++ b/devel/_sources/docs/memory/memory-qos.md.txt @@ -0,0 +1,155 @@ +# 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: + ``` + [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 +``` diff --git a/devel/_static/documentation_options.js b/devel/_static/documentation_options.js index d8d097107..67c015c7d 100644 --- a/devel/_static/documentation_options.js +++ b/devel/_static/documentation_options.js @@ -1,6 +1,6 @@ var DOCUMENTATION_OPTIONS = { URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'), - VERSION: '0.1.0-37-g90dc2e5', + VERSION: '0.1.0-38-g246e1f7', LANGUAGE: 'en', COLLAPSE_INDEX: false, BUILDER: 'html', diff --git a/devel/docs/contributing.html b/devel/docs/contributing.html index 6bf6688ce..196f13901 100644 --- a/devel/docs/contributing.html +++ b/devel/docs/contributing.html @@ -4,7 +4,7 @@ - Contributing — NRI Plugins 0.1.0-37-g90dc2e5 documentation + Contributing — NRI Plugins 0.1.0-38-g246e1f7 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Memory plugins

+
+

Contents

+ +
+
+ + +
+
+ +
+
+
+
+ + +
+ + GitHub Pages + devel + + +
+
+
Versions
+
+
+
+ all releases +
+
+
+
+ + + + + + + \ No newline at end of file diff --git a/devel/docs/memory/memory-qos.html b/devel/docs/memory/memory-qos.html new file mode 100644 index 000000000..3fee8075d --- /dev/null +++ b/devel/docs/memory/memory-qos.html @@ -0,0 +1,325 @@ + + + + + + + Memory QoS NRI plugin — NRI Plugins 0.1.0-38-g246e1f7 documentation + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

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. +

  2. Direct workload-specific memory parameters.

    3. +
+

Memory QoS class of a pod or a container is defined using annotations +in pod 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:

+
  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

+
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:

    +
    [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

+
cd cmd/plugins/memory-qos && go build .
+
+
+
+
+

Run

+
cmd/plugins/memory-qos/memory-qos -config sample-configs/nri-memory-qos.yaml -idx 40 -vv
+
+
+
+
+

Manual test

+
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:

+
for pid in $(pidof dd); do
+    grep VmSwap /proc/$pid/status
+done
+
+
+
+
+

Debug

+
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:

+
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
+
+
+
+
+
+ + +
+
+ +
+
+
+
+ + +
+ + GitHub Pages + devel + + +
+
+
Versions
+
+
+
+ all releases +
+
+
+
+ + + + + + + \ No newline at end of file diff --git a/devel/docs/resource-policy/configuration.html b/devel/docs/resource-policy/configuration.html index c3f4584e1..3ad9cbb5a 100644 --- a/devel/docs/resource-policy/configuration.html +++ b/devel/docs/resource-policy/configuration.html @@ -4,7 +4,7 @@ - Dynamic Configuration — NRI Plugins 0.1.0-37-g90dc2e5 documentation + Dynamic Configuration — NRI Plugins 0.1.0-38-g246e1f7 documentation