diff --git a/deployment/helm/balloons/README.md b/deployment/helm/balloons/README.md index 15e70f7ac..2a395be34 100644 --- a/deployment/helm/balloons/README.md +++ b/deployment/helm/balloons/README.md @@ -3,23 +3,79 @@ This chart deploys balloons Node Resource Interface (NRI) plugin. The balloons NRI resource policy plugin implements workload placement into “balloons” that are disjoint CPU pools. +## Prerequisites + +- Kubernetes 1.24+ +- Helm 3.0.0+ +- Container runtime: + - containerD: + - At least [containerd 1.7.0](https://github.com/containerd/containerd/releases/tag/v1.7.0) + release version to use the NRI feature. + + - Enable NRI feature by following [these](https://github.com/containerd/containerd/blob/main/docs/NRI.md#enabling-nri-support-in-containerd) + detailed instructions. You can optionally enable the NRI in containerd using the Helm chart + during the chart installation simply by setting the `nri.patchRuntimeConfig` parameter. + For instance, + + ```sh + helm install my-balloons nri-plugins/nri-resource-policy-balloons --set nri.patchRuntimeConfig=true --namespace kube-system + ``` + + Enabling `nri.patchRuntimeConfig` creates an init container to turn on + NRI feature in containerd and only after that proceed the plugin installation. + + - CRI-O + - At least [v1.26.0](https://github.com/cri-o/cri-o/releases/tag/v1.26.0) release version to + use the NRI feature + - Enable NRI feature by following [these](https://github.com/cri-o/cri-o/blob/main/docs/crio.conf.5.md#crionri-table) detailed instructions. + You can optionally enable the NRI in CRI-O using the Helm chart + during the chart installation simply by setting the `nri.patchRuntimeConfig` parameter. + For instance, + + ```sh + helm install my-balloons nri-plugins/nri-resource-policy-balloons --namespace kube-system --set nri.patchRuntimeConfig=true + ``` + ## Installing the Chart Path to the chart: `nri-resource-policy-balloons` -``` +```sh helm repo add nri-plugins https://containers.github.io/nri-plugins helm install my-balloons nri-plugins/nri-resource-policy-balloons --namespace kube-system ``` - + The command above deploys balloons NRI plugin on the Kubernetes cluster within the -`kube-system` namespace with default configuration. +`kube-system` namespace with default configuration. To customize the available parameters +as described in the [Configuration options]( #configuration-options) below, you have two +options: you can use the `--set` flag or create a custom values.yaml file and provide it +using the `-f` flag. For example: + +```sh +# Install the balloons plugin with custom values provided using the --set option +helm install my-balloons nri-plugins/nri-resource-policy-balloons --namespace kube-system --set nri.patchRuntimeConfig=true +``` + +```sh +# Install the balloons plugin with custom values specified in a custom values.yaml file +cat < myPath/values.yaml +nri: + patchRuntimeConfig: true + +tolerations: +- key: "node-role.kubernetes.io/control-plane" + operator: "Exists" + effect: "NoSchedule" +EOF + +helm install my-balloons nri-plugins/nri-resource-policy-balloons --namespace kube-system -f myPath/values.yaml +``` ## Uninstalling the Chart To uninstall the balloons plugin run the following command: -``` +```sh helm delete my-balloons --namespace kube-system ``` diff --git a/deployment/helm/memory-qos/README.md b/deployment/helm/memory-qos/README.md index 849ed69b2..d864aba16 100644 --- a/deployment/helm/memory-qos/README.md +++ b/deployment/helm/memory-qos/README.md @@ -4,23 +4,79 @@ This chart deploys memory-qos Node Resource Interface (NRI) plugin. The memory-q adds two methods for controlling cgroups v2 memory.* parameters: QoS class and direct memory annotations. +## Prerequisites + +- Kubernetes 1.24+ +- Helm 3.0.0+ +- Container runtime: + - containerD: + - At least [containerd 1.7.0](https://github.com/containerd/containerd/releases/tag/v1.7.0) + release version to use the NRI feature. + + - Enable NRI feature by following [these](https://github.com/containerd/containerd/blob/main/docs/NRI.md#enabling-nri-support-in-containerd) + detailed instructions. You can optionally enable the NRI in containerd using the Helm chart + during the chart installation simply by setting the `nri.patchRuntimeConfig` parameter. + For instance, + + ```sh + helm install my-memory-qos nri-plugins/nri-memory-qos --set nri.patchRuntimeConfig=true --namespace kube-system + ``` + + Enabling `nri.patchRuntimeConfig` creates an init container to turn on + NRI feature in containerd and only after that proceed the plugin installation. + + - CRI-O + - At least [v1.26.0](https://github.com/cri-o/cri-o/releases/tag/v1.26.0) release version to + use the NRI feature + - Enable NRI feature by following [these](https://github.com/cri-o/cri-o/blob/main/docs/crio.conf.5.md#crionri-table) detailed instructions. + You can optionally enable the NRI in CRI-O using the Helm chart + during the chart installation simply by setting the `nri.patchRuntimeConfig` parameter. + For instance, + + ```sh + helm install my-memory-qos nri-plugins/nri-memory-qos --namespace kube-system --set nri.patchRuntimeConfig=true + ``` + ## Installing the Chart Path to the chart: `nri-memory-qos`. -``` +```sh helm repo add nri-plugins https://containers.github.io/nri-plugins helm install my-memory-qos nri-plugins/nri-memory-qos --namespace kube-system ``` -The command above deploys memtierd NRI plugin on the Kubernetes cluster within the -`kube-system` namespace with default configuration. +The command above deploys memory-qos NRI plugin on the Kubernetes cluster within the +`kube-system` namespace with default configuration. To customize the available parameters +as described in the [Configuration options]( #configuration-options) below, you have two +options: you can use the `--set` flag or create a custom values.yaml file and provide it +using the `-f` flag. For example: + +```sh +# Install the memory-qos plugin with custom values provided using the --set option +helm install my-memory-qos nri-plugins/nri-memory-qos --namespace kube-system --set nri.patchRuntimeConfig=true +``` + +```sh +# Install the memory-qos plugin with custom values specified in a custom values.yaml file +cat < myPath/values.yaml +nri: + patchRuntimeConfig: true + +tolerations: +- key: "node-role.kubernetes.io/control-plane" + operator: "Exists" + effect: "NoSchedule" +EOF + +helm install my-memory-qos nri-plugins/nri-memory-qos --namespace kube-system -f myPath/values.yaml +``` ## Uninstalling the Chart To uninstall the memory-qos plugin run the following command: -``` +```sh helm delete my-memory-qos --namespace kube-system ``` diff --git a/deployment/helm/memtierd/README.md b/deployment/helm/memtierd/README.md index c9fa37ec5..8bc56b43a 100644 --- a/deployment/helm/memtierd/README.md +++ b/deployment/helm/memtierd/README.md @@ -3,23 +3,79 @@ This chart deploys memtierd Node Resource Interface (NRI) plugin. The memtierd NRI plugin enables managing workloads with Memtierd in Kubernetes. +## Prerequisites + +- Kubernetes 1.24+ +- Helm 3.0.0+ +- Container runtime: + - containerD: + - At least [containerd 1.7.0](https://github.com/containerd/containerd/releases/tag/v1.7.0) + release version to use the NRI feature. + + - Enable NRI feature by following [these](https://github.com/containerd/containerd/blob/main/docs/NRI.md#enabling-nri-support-in-containerd) + detailed instructions. You can optionally enable the NRI in containerd using the Helm chart + during the chart installation simply by setting the `nri.patchRuntimeConfig` parameter. + For instance, + + ```sh + helm install my-memtierd nri-plugins/nri-memtierd --set nri.patchRuntimeConfig=true --namespace kube-system + ``` + + Enabling `nri.patchRuntimeConfig` creates an init container to turn on + NRI feature in containerd and only after that proceed the plugin installation. + + - CRI-O + - At least [v1.26.0](https://github.com/cri-o/cri-o/releases/tag/v1.26.0) release version to + use the NRI feature + - Enable NRI feature by following [these](https://github.com/cri-o/cri-o/blob/main/docs/crio.conf.5.md#crionri-table) detailed instructions. + You can optionally enable the NRI in CRI-O using the Helm chart + during the chart installation simply by setting the `nri.patchRuntimeConfig` parameter. + For instance, + + ```sh + helm install my-memtierd nri-plugins/nri-memtierd --namespace kube-system --set nri.patchRuntimeConfig=true + ``` + ## Installing the Chart Path to the chart: `nri-memtierd`. -``` +```sh helm repo add nri-plugins https://containers.github.io/nri-plugins helm install my-memtierd nri-plugins/nri-memtierd --namespace kube-system ``` The command above deploys memtierd NRI plugin on the Kubernetes cluster within the -`kube-system` namespace with default configuration. +`kube-system` namespace with default configuration. To customize the available parameters +as described in the [Configuration options]( #configuration-options) below, you have two +options: you can use the `--set` flag or create a custom values.yaml file and provide it +using the `-f` flag. For example: + +```sh +# Install the memtierd plugin with custom values provided using the --set option +helm install my-memtierd nri-plugins/nri-memtierd --namespace kube-system --set nri.patchRuntimeConfig=true +``` + +```sh +# Install the nri-memtierd plugin with custom values specified in a custom values.yaml file +cat < myPath/values.yaml +nri: + patchRuntimeConfig: true + +tolerations: +- key: "node-role.kubernetes.io/control-plane" + operator: "Exists" + effect: "NoSchedule" +EOF + +helm install my-memtierd nri-plugins/nri-memtierd --namespace kube-system -f myPath/values.yaml +``` ## Uninstalling the Chart To uninstall the memtierd plugin run the following command: -``` +```sh helm delete my-memtierd --namespace kube-system ``` diff --git a/deployment/helm/topology-aware/README.md b/deployment/helm/topology-aware/README.md index b18f03c1c..116895fb7 100644 --- a/deployment/helm/topology-aware/README.md +++ b/deployment/helm/topology-aware/README.md @@ -4,23 +4,79 @@ This chart deploys topology-aware Node Resource Interface (NRI) plugin. Topology resource policy plugin is a NRI plugin that will apply hardware-aware resource allocation policies to the containers running in the system. +## Prerequisites + +- Kubernetes 1.24+ +- Helm 3.0.0+ +- Container runtime: + - containerD: + - At least [containerd 1.7.0](https://github.com/containerd/containerd/releases/tag/v1.7.0) + release version to use the NRI feature. + + - Enable NRI feature by following [these](https://github.com/containerd/containerd/blob/main/docs/NRI.md#enabling-nri-support-in-containerd) + detailed instructions. You can optionally enable the NRI in containerd using the Helm chart + during the chart installation simply by setting the `nri.patchRuntimeConfig` parameter. + For instance, + + ```sh + helm install my-topology-aware nri-plugins/nri-resource-policy-topology-aware --set nri.patchRuntimeConfig=true --namespace kube-system + ``` + + Enabling `nri.patchRuntimeConfig` creates an init container to turn on + NRI feature in containerd and only after that proceed the plugin installation. + + - CRI-O + - At least [v1.26.0](https://github.com/cri-o/cri-o/releases/tag/v1.26.0) release version to + use the NRI feature + - Enable NRI feature by following [these](https://github.com/cri-o/cri-o/blob/main/docs/crio.conf.5.md#crionri-table) detailed instructions. + You can optionally enable the NRI in CRI-O using the Helm chart + during the chart installation simply by setting the `nri.patchRuntimeConfig` parameter. + For instance, + + ```sh + helm install my-topology-aware nri-plugins/nri-resource-policy-topology-aware --namespace kube-system --set nri.patchRuntimeConfig=true + ``` + ## Installing the Chart Path to the chart: `nri-resource-policy-topology-aware`. -``` +```sh helm repo add nri-plugins https://containers.github.io/nri-plugins helm install my-topology-aware nri-plugins/nri-resource-policy-topology-aware --namespace kube-system ``` The command above deploys topology-aware NRI plugin on the Kubernetes cluster within the -`kube-system` namespace with default configuration. +`kube-system` namespace with default configuration. To customize the available parameters +as described in the [Configuration options]( #configuration-options) below, you have two +options: you can use the `--set` flag or create a custom values.yaml file and provide it +using the `-f` flag. For example: + +```sh +# Install the topology-aware plugin with custom values provided using the --set option +helm install my-topology-aware nri-plugins/nri-resource-policy-topology-aware --namespace kube-system --set nri.patchRuntimeConfig=true +``` + +```sh +# Install the topology-aware plugin with custom values specified in a custom values.yaml file +cat < myPath/values.yaml +nri: + patchRuntimeConfig: true + +tolerations: +- key: "node-role.kubernetes.io/control-plane" + operator: "Exists" + effect: "NoSchedule" +EOF + +helm install my-topology-aware nri-plugins/nri-resource-policy-topology-aware --namespace kube-system -f myPath/values.yaml +``` ## Uninstalling the Chart To uninstall the topology-aware plugin run the following command: -``` +```sh helm delete my-topology-aware --namespace kube-system ``` diff --git a/docs/conf.py b/docs/conf.py index 90e631737..b3377a93b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -127,7 +127,7 @@ def gomod_versions(modules): # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ['_build', '.github', '_work', 'generate', 'README.md', 'TODO.md', 'SECURITY.md', 'CODE-OF-CONDUCT.md', 'docs/releases', 'test/self-hosted-runner/README.md', 'test/e2e/README.md', 'docs/resource-policy/releases', 'docs/resource-policy/README.md','test/statistics-analysis/README.md'] +exclude_patterns = ['_build', '.github', '_work', 'generate', 'README.md', 'TODO.md', 'SECURITY.md', 'CODE-OF-CONDUCT.md', 'docs/releases', 'test/self-hosted-runner/README.md', 'test/e2e/README.md', 'docs/resource-policy/releases', 'docs/resource-policy/README.md','test/statistics-analysis/README.md', 'deployment/helm/*/*.md'] # -- Options for HTML output ------------------------------------------------- diff --git a/docs/deployment/balloons.md b/docs/deployment/balloons.md new file mode 100644 index 000000000..f180666e5 --- /dev/null +++ b/docs/deployment/balloons.md @@ -0,0 +1,2 @@ +```{include} ../../deployment/helm/balloons/README.md +``` diff --git a/docs/deployment/index.md b/docs/deployment/index.md new file mode 100644 index 000000000..2f91c1c27 --- /dev/null +++ b/docs/deployment/index.md @@ -0,0 +1,13 @@ +# Deployment + +The only supported installation method of the NRI plugins at the moment is through Helm. +```{toctree} +--- +maxdepth: 2 +caption: Contents +--- +balloons.md +topology-aware.md +memory-qos.md +memtierd.md +``` diff --git a/docs/deployment/memory-qos.md b/docs/deployment/memory-qos.md new file mode 100644 index 000000000..4ed196196 --- /dev/null +++ b/docs/deployment/memory-qos.md @@ -0,0 +1,2 @@ +```{include} ../../deployment/helm/memory-qos/README.md +``` diff --git a/docs/deployment/memtierd.md b/docs/deployment/memtierd.md new file mode 100644 index 000000000..40612361c --- /dev/null +++ b/docs/deployment/memtierd.md @@ -0,0 +1,2 @@ +```{include} ../../deployment/helm/memtierd/README.md +``` diff --git a/docs/deployment/topology-aware.md b/docs/deployment/topology-aware.md new file mode 100644 index 000000000..3ad6dc67d --- /dev/null +++ b/docs/deployment/topology-aware.md @@ -0,0 +1,2 @@ +```{include} ../../deployment/helm/topology-aware/README.md +``` diff --git a/docs/index.md b/docs/index.md index 1aa33fb9a..d6e4a7a36 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,6 +8,7 @@ caption: Contents introduction.md resource-policy/index.rst memory/index.md +deployment/index.md contributing.md Project GitHub repository ``` diff --git a/docs/resource-policy/index.md b/docs/resource-policy/index.md index cff336824..bf8d5f4ea 100644 --- a/docs/resource-policy/index.md +++ b/docs/resource-policy/index.md @@ -6,7 +6,6 @@ maxdepth: 2 caption: Contents --- introduction.md -installation.md setup.md configuration.md policy/index.md diff --git a/docs/resource-policy/installation.md b/docs/resource-policy/installation.md deleted file mode 100644 index 82b5790c9..000000000 --- a/docs/resource-policy/installation.md +++ /dev/null @@ -1,176 +0,0 @@ -# Installation - -This repository hosts a collection of plugins of various types, one of which is the resource -policy plugins. In this example, we will demonstrate the installation process for the topology-aware -plugin, which falls under the resource policy type. The installation methods outlined -here can be applied to any other plugin hosted in this repository, regardless of its type. - -Currently, there are two installation methods available. - -1. [Helm](#installing-the-helm-chart) -2. [Manual](#manual-installation) - -Regardless of the chosen installation method, the NRI plugin installation includes the -following components: DaemonSet, ConfigMap, CustomResourceDefinition, and RBAC-related objects. - -## Prerequisites - -- Container runtime: - - containerD: - - At least [containerd 1.7.0](https://github.com/containerd/containerd/releases/tag/v1.7.0) - release version to use the NRI feature. - - - Enable NRI feature by following [these](https://github.com/containerd/containerd/blob/main/docs/NRI.md#enabling-nri-support-in-containerd) - detailed instructions. You can optionally enable the NRI in containerd using the Helm chart - during the chart installation simply by setting the `nri.patchRuntimeConfig` parameter. - For instance, - - ```sh - helm install topology-aware nri-plugins/nri-resource-policy-topology-aware --namespace kube-system --set nri.patchRuntimeConfig=true - ``` - - Enabling `nri.patchRuntimeConfig` creates an init container to turn on - NRI feature in containerd and only after that proceed the plugin installation. - - - CRI-O - - At least [v1.26.0](https://github.com/cri-o/cri-o/releases/tag/v1.26.0) release version to - use the NRI feature - - Enable NRI feature by following [these](https://github.com/cri-o/cri-o/blob/main/docs/crio.conf.5.md#crionri-table) detailed instructions. - You can optionally enable the NRI in CRI-O using the Helm chart - during the chart installation simply by setting the `nri.patchRuntimeConfig` parameter. - For instance, - - ```sh - helm install topology-aware nri-plugins/nri-resource-policy-topology-aware --namespace kube-system --set nri.patchRuntimeConfig=true - ``` - -- Kubernetes 1.24+ -- Helm 3.0.0+ - -## Installing the Helm Chart - -1. Add the nri-plugins charts repository so that Helm install can find the actual charts. - - ```sh - helm repo add nri-plugins https://containers.github.io/nri-plugins - ``` - -1. List chart repositories to ensure that nri-plugins repo is added. - - ```sh - helm repo list - ``` - -1. Install the plugin. Replace release version with the desired version. If you wish to - provide custom values to the Helm chart, refer to the [table](#available-parameters) below, - which describes the available parameters that can be modified before installation. - Parameters can be specified either using the --set option or through the -f flag along - with the custom values.yaml file. It's important to note that specifying the namespace - (using `--namespace` or `-n`) is crucial when installing the Helm chart. If no namespace - is specified, the manifests will be installed in the default namespace. - - ```sh - # Install the topology-aware plugin with default values - helm install topology-aware nri-plugins/nri-resource-policy-topology-aware --namespace kube-system - - # Install the topology-aware plugin with custom values provided using the --set option - helm install topology-aware nri-plugins/nri-resource-policy-topology-aware --namespace kube-system --set nri.patchRuntimeConfig=true - - # Install the topology-aware plugin with custom values specified in a custom values.yaml file - cat < myPath/values.yaml - nri: - patchRuntimeConfig: true - - tolerations: - - key: "node-role.kubernetes.io/control-plane" - operator: "Exists" - effect: "NoSchedule" - EOF - - helm install topology-aware nri-plugins/nri-resource-policy-topology-aware --namespace kube-system -f myPath/values.yaml - ``` - - The helm repository is named `nri-plugins`, and in step 1, you have the - flexibility to choose any name when adding it. However, it's important to - note that `nri-resource-policy-topology-aware`, which serves as the path - to the chart, must accurately reflect the actual name of the chart. You - can find the path to each chart in the [helm parameters table](#available-parameters). - - -1. Verify the status of the daemonset to ensure that the plugin is running successfully - - ```bash - kubectl get daemonset -n kube-system nri-resource-policy-topology-aware - - NAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR AGE - nri-resource-policy-topology-aware 1 1 0 1 0 kubernetes.io/os=linux 4m33s - ``` - -That's it! You have now installed the topology-aware NRI resource policy plugin using Helm. - -## Uninstalling the Chart - -To uninstall plugin chart just deleting it with the release name is enough: - -```bash -helm uninstall topology-aware --namespace kube-system -``` - -Note: this removes DaemonSet, ConfigMap, CustomResourceDefinition, and RBAC-related objects associated with the chart. - -## Available parameters - -To know what are the available Helm configuration options for currently available Helm charts, you can check: -- [balloons parameters](../../deployment/helm/balloons/README.md) -- [memory-qos parameters](../../deployment/helm/memory-qos/README.md) -- [memtierd parameters](../../deployment/helm/memtierd/README.md) -- [topology-aware parameters](../../deployment/helm/topology-aware/README.md) - -## Manual installation - -For the manual installation we will be using templating tool to generate Kubernetes YAML manifests. -1. Clone the project to your local machine - - ```sh - git clone https://github.com/containers/nri-plugins.git - ``` - -1. Navigate to the project directory - - ```sh - cd nri-plugins - ``` - -1. If there are any specific configuration values you need to modify, navigate to the plugins - [directory](https://github.com/containers/nri-plugins/tree/main/deployment/overlays) containing - the Kustomization file and update the desired configuration - values according to your environment in the Kustomization file. - -1. Use kustomize to generate the Kubernetes manifests for the desired plugin and apply the generated - manifests to your Kubernetes cluster using kubectl. - - ```sh - kustomize build deployment/overlays/topology-aware/ | kubectl apply -f - - ``` - -1. Verify the status of the DaemonSet to ensure that the plugin is running successfully - - ```bash - kubectl get daemonset -n kube-system nri-resource-policy - - NAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR AGE - nri-resource-policy 1 1 0 1 0 kubernetes.io/os=linux 4m33s - ``` - -That's it! You have now installed the topology-aware NRI resource policy plugin using kutomize. - -## Manual uninstallation - -To uninstall plugin manifests you can run the following command: - -```sh -kustomize build deployment/overlays/topology-aware/ | kubectl delete -f - -``` - -Note: this removes DaemonSet, ConfigMap, CustomResourceDefinition, and RBAC-related objects associated -with the chart. diff --git a/docs/resource-policy/policy/balloons.md b/docs/resource-policy/policy/balloons.md index d87f5bd33..edb9670a0 100644 --- a/docs/resource-policy/policy/balloons.md +++ b/docs/resource-policy/policy/balloons.md @@ -48,7 +48,7 @@ min and max frequencies on CPU cores and uncore. ## Deployment Deploy nri-resource-policy-balloons on each node as you would for any -other policy. See [installation](../installation.md) for more details. +other policy. See [deployment](../../deployment/index.md) for more details. ## Configuration diff --git a/docs/resource-policy/setup.md b/docs/resource-policy/setup.md index 88a2004eb..81c4e49a2 100644 --- a/docs/resource-policy/setup.md +++ b/docs/resource-policy/setup.md @@ -4,7 +4,7 @@ When you want to try NRI Resource Policy, here is the list of things you need to do, assuming you already have a Kubernetes\* cluster up and running, using either `containerd` or `cri-o` as the runtime. - * [Install](installation.md) NRI Resource Policy DaemonSet deployment file. + * [Deploy](../deployment/index.md) NRI Resource Policy DaemonSet deployment file. * Runtime (containerd / cri-o) configuration For NRI Resource Policy, you need to provide a configuration file. The default