docs: Update and fix the resource policy documentation

- Updated the old documentation. - Replaced "NRI Plugins Collection" by "NRI Plugins" as that is the proper name. Signed-off-by: Jukka Rissanen <[email protected]>
containers · May 24, 2023 · 69b33cc · 69b33cc
1 parent ede2a58
commit 69b33cc
Show file tree

Hide file tree

Showing 14 changed files with 69 additions and 280 deletions.
diff --git a/CODE-OF-CONDUCT.md b/CODE-OF-CONDUCT.md
@@ -1,3 +1,3 @@
-# The NRI Plugin Collection Project Community Code of Conduct
+# The NRI Plugins Project Community Code of Conduct
 
-The NRI Plugin Collection Project follows the [Containers Community Code of Conduct](https://github.com/containers/common/blob/main/CODE-OF-CONDUCT.md).
+The NRI Plugins Project follows the [Containers Community Code of Conduct](https://github.com/containers/common/blob/main/CODE-OF-CONDUCT.md).
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# NRI Plugin Collection
+# NRI Plugins
 
 This repository contains a collection of community maintained NRI plugins.
 

diff --git a/SECURITY.md b/SECURITY.md
@@ -1,12 +1,12 @@
-# Security and Disclosure Information Policy for the NRI Plugin Collection Project
+# Security and Disclosure Information Policy for the NRI Plugins Project
 
  * [Reporting a Vulnerability](#Reporting-a-Vulnerability)
  * [Security Announcements](#Security-Announcements)
  * [Security Vulnerability Response](#Security-Vulnerability-Response)
 
 ## Reporting a Vulnerability
 
-If you think you've identified a security issue in a NRI Plugin Collection project,
+If you think you've identified a security issue in a NRI Plugins project,
 please DO NOT report the issue publicly via the Github issue tracker,
 mailing list, or IRC. Instead, send an email with as many details as 
 possible to [[email protected]](mailto:[email protected]?subject=Security%20Vunerablity%20Report) or [[email protected]](mailto:[email protected]?subject=Security%20Vunerablity%20Report).

diff --git a/docs/conf.py b/docs/conf.py
@@ -21,7 +21,7 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'NRI Plugin Collection'
+project = 'NRI Plugins'
 copyright = '2023, various'
 author = 'various'
 

diff --git a/docs/contributing.md b/docs/contributing.md
@@ -1,9 +1,10 @@
 # Contributing
 
-Please use the GitHub\* infrastructure for contributing to
-NRI Plugin Collection.
+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 https://github.com/containerd/nri
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,7 +1,7 @@
-.. NRI Plugin Collection documentation master file
+.. NRI Plugins documentation master file
 
-Welcome to NRI Plugin Collection documentation
-==============================================
+Welcome to NRI Plugins documentation
+====================================
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/resource-policy/developers-guide/architecture.md b/docs/resource-policy/developers-guide/architecture.md
@@ -2,7 +2,7 @@
 
 ## Overview
 
-NRI Resource Policy (NRI-RP) plugin is a pluggable add-on for controlling how
+NRI Resource Policy (later NRI-RP) plugin is a pluggable add-on for controlling how
 much and which resources are assigned to containers in a Kubernetes\* cluster.
 It's an add-on because you install it in addition to the normal selection of
 your components. It's pluggable since you inject it on the signaling path
@@ -38,7 +38,7 @@ a cluster is to use Kubernetes CRDs and ConfigMaps.
 
 ## Components
 
-### [Node Agent](/pkg/agent/)
+### [Node Agent](/pkg/resmgr/agent/)
 
 The node agent is a component internal to NRI-RP itself. All interactions
 by NRI-RP with the Kubernetes Control Plane go through the node agent with
@@ -56,7 +56,7 @@ The agent interface implements the following:
 The config interface is defined and has its gRPC server running in
 NRI-RP. The agent acts as a gRPC client for this interface. The low-level
 cluster interface is defined and has its gRPC server running in the agent,
-with the [convenience layer](/pkg/agent) defined in NRI-RP.
+with the [convenience layer](/pkg/resmgr/agent) defined in NRI-RP.
 NRI-RP acts as a gRPC client for the low-level plumbing interface.
 
 Additionally, the stock node agent that comes with NRI-RP implements schemes
@@ -132,7 +132,7 @@ following, based on the event type:
    4. Release the pipeline lock.
 
 
-### [Cache](/pkg/cache/)
+### [Cache](/pkg/resmgr/cache/)
 
 The cache is a shared internal storage location within NRI-RP. It tracks the
 runtime state of pods and containers known to NRI-RP, as well as the state
@@ -166,14 +166,14 @@ the policy's event handler with the injected event as an argument and with
 the cache properly locked.
 
 
-### [Generic Policy Layer](/pkg/policy/policy.go)
+### [Generic Policy Layer](/pkg/resmgr/policy/policy.go)
 
 The generic policy layer defines the abstract interface the rest of NRI-RP
 uses to interact with policy implementations and takes care of the details
 of activating and dispatching calls through to the configured active policy.
 
 
-### [Generic Resource Controller Layer](/pkg/control/control.go)
+### [Generic Resource Controller Layer](/pkg/resmgr/control/control.go)
 
 The generic resource controller layer defines the abstract interface the rest
 of NRI-RP uses to interact with resource controller implementations and takes
@@ -201,3 +201,10 @@ typically a DRAM/PMEM combination configured in 2-layer memory mode.
 
 A balloons policy allows user to define fine grained control how the
 computer resources are distributed to workloads.
+
+#### [Template](/cmd/template/)
+
+The template policy can be used as a base for developing new policies.
+It provides hooks that the policy developer can fill to define fine grained
+control how the computer resources are distributed to workloads.
+Do not edit the template policy directly but copy it to new name and edit that.
diff --git a/docs/resource-policy/installation.md b/docs/resource-policy/installation.md
@@ -1,98 +1,30 @@
 # Installation
 
-## Installing from packages
+## Installing from DaemonSet deployment file
 
-You can install CRI Resource Manager from `deb` or `rpm` packages
-for supported distros.
+You can install NRI Resource Policy from DaemonSet deployment file.
 
-  - [download](https://github.com/intel/cri-resource-manager/releases/latest)
-  packages
-  - install them:
-    - for rpm packages: `sudo rpm -Uvh <packages>`
-    - for deb packages: `sudo dpkg -i <packages>`
+TBD
 
 ## Installing from sources
 
-Although not recommended, you can install CRI Resource Manager from sources:
+Although not recommended, you can install NRI Resource Policy from sources:
 
-  - get the sources: `git clone https://github.com/intel/cri-resource-manager`
-  - build and install: `cd cri-resource-manager; make build && sudo make install`
+  - get the sources: `git clone https://github.com/containers/nri-plugins`
+  - build and install: `make && make images`
 
 You will need at least `git`, {{ '`golang '+ '{}'.format(golang_version) + '`' }} or newer,
 `GNU make`, `bash`, `find`, `sed`, `head`, `date`, and `install` to be able to build and install
 from sources.
 
-## Building packages for the distro of your host
+After the images are created, you can copy the tar images from `build/images` to
+the target device and deploy the relevant DaemonSet deployment file found also
+in images directory.
 
-You can build packages for the `$distro` of your host by executing the
-following command:
+For example, you can deploy topology-aware resource policy like this:
 
-```
-make packages
-```
-
-If the `$version` of your `$distro` is supported, this will leave the
-resulting packages in `packages/$distro-$version`. Building packages
-this way requires `docker`, but it does not require you to install
-the full set of build dependencies of CRI Resource Manager to your host.
-
-If you want to build packages without docker, you can use either
-`make rpm` or `make deb`, depending on which supported distro you are
-running. Building this way requires all the build dependencies to be
-installed on your host.
-
-You can check which `$distro`'s and `$version`'s are supported by running
-
-```
-ls dockerfiles/cross-build
-```
-
-If you see a `Dockerfile.$distro-$version` matching your host then your
-distro is supported.
-
-## Building packages for another distro
-
-You can cross-build packages of the native `$type` for a particular
-`$version` of a `$distro` by running the following command:
-
-```
-make cross-$type.$distro-$version
-```
-
-Similarly to `make packages`, this will build packages using a `Docker\*`
-container. However, instead of building for your host, it will build them
-for the specified distro. For instance `make cross-deb.ubuntu-18.04` will
-build `deb` packages for `Ubuntu\* 18.04` and `make cross-rpm.centos-8` will
-build `rpm` packages for `CentOS\* 8`
-
-## Post-install configuration
-
-The provided packages install `systemd` service files and a sample
-configuration. The easiest way to get up and running is to rename the sample
-configuration and start CRI Resource Manager using systemd. You can do this
-using the following commands:
-
-```
-mv /etc/cri-resmgr/fallback.cfg.sample /etc/cri-resmgr/fallback.cfg
-systemctl start cri-resource-manager
-```
-
-If you want, you can set CRI Resource Manager to automatically start
-when your system boots with this command:
-
-```
-systemctl enable cri-resource-manager
-```
-
-The provided packages also install a file for managing the default options
-passed to CRI Resource Manager upon startup. You can change these by editing
-this file and then restarting CRI Resource Manager, like this:
-
-```
-# On Debian\*-based systems edit the defaults like this:
-${EDITOR:-vi} /etc/default/cri-resource-manager
-# On rpm-based systems edit the defaults like this:
-${EDITOR:-vi} /etc/sysconfig/cri-resource-manager
-# Restart the service.
-systemctl restart cri-resource-manager
+```console
+cd build/images
+ctr -n k8s.io image import nri-resource-policy-topology-aware-image-321ca3aad95e.tar
+kubectl apply -f nri-resource-policy-topology-aware-deployment.yaml
 ```
diff --git a/docs/resource-policy/node-agent.md b/docs/resource-policy/node-agent.md
@@ -1,8 +1,7 @@
 # Node Agent
 
-CRI Resource Manager can be configured dynamically using the CRI Resource
-Manager Node Agent and Kubernetes\* ConfigMaps. The agent is built in the
-NRI resource plugin.
+NRI Resource Policy plugin can be configured dynamically using the Node Agent
+and Kubernetes\* ConfigMaps. The agent is builtin the NRI resource plugin.
 
 The agent monitors two ConfigMaps for the node, a primary node-specific one
 and a secondary group-specific or default one, depending on whether the node

diff --git a/docs/resource-policy/policy/container-affinity.md b/docs/resource-policy/policy/container-affinity.md
@@ -27,16 +27,16 @@ Policies try to place a container
 
 ## Affinity Annotation Syntax
 
-*Affinities* are defined as the `cri-resource-manager.intel.com/affinity` annotation.
-*Anti-affinities* are defined as the `cri-resource-manager.intel.com/anti-affinity`
+*Affinities* are defined as the `resource-policy.nri.io/affinity` annotation.
+*Anti-affinities* are defined as the `resource-manager.nri.io/anti-affinity`
 annotation. They are specified in the `metadata` section of the `Pod YAML`, under
 `annotations` as a dictionary, with each dictionary key being the name of the
 *container* within the Pod to which the annotation belongs to.
 
 ```yaml
 metadata:
   anotations:
-    cri-resource-manager.intel.com/affinity: |
+    resource-manager.nri.io/affinity: |
       container1:
         - scope:
             key: key-ref
@@ -55,13 +55,13 @@ metadata:
           weight: w
 ```
 
-An anti-affinity is defined similarly but using `cri-resource-manager.intel.com/anti-affinity`
+An anti-affinity is defined similarly but using `resource-manager.nri.io/anti-affinity`
 as the annotation key.
 
 ```yaml
 metadata:
   anotations:
-    cri-resource-manager.intel.com/anti-affinity: |
+    resource-manager.nri.io/anti-affinity: |
       container1:
         - scope:
             key: key-ref
@@ -197,15 +197,15 @@ container `wolf`.
 ```yaml
 metadata:
   annotations:
-    cri-resource-manager.intel.com/affinity: |
+    resource-manager.nri.io/affinity: |
       peter:
       - match:
           key: name
           operator: Equals
           values:
           - sheep
         weight: 5
-    cri-resource-manager.intel.com/anti-affinity: |
+    resource-manager.nri.io/anti-affinity: |
       peter:
       - match:
           key: name
@@ -223,9 +223,9 @@ one needs to give just the names of the containers, like in the example below.
 
 ```yaml
   annotations:
-    cri-resource-manager.intel.com/affinity: |
+    resource-manager.nri.io/affinity: |
       container3: [ container1 ]
-    cri-resource-manager.intel.com/anti-affinity: |
+    resource-manager.nri.io/anti-affinity: |
       container3: [ container2 ]
       container4: [ container2, container3 ]
 ```
@@ -243,14 +243,14 @@ The equivalent annotation in full syntax would be
 ```yaml
 metadata:
   annotations:
-    cri-resource-manager.intel.com/affinity: |+
+    resource-manager.nri.io/affinity: |+
       container3:
       - match:
           key: labels/io.kubernetes.container.name
           operator: In
           values:
           - container1
-    cri-resource-manager.intel.com/anti-affinity: |+
+    resource-manager.nri.io/anti-affinity: |+
       container3:
       - match:
           key: labels/io.kubernetes.container.name

diff --git a/docs/resource-policy/policy/cpu-allocator.md b/docs/resource-policy/policy/cpu-allocator.md
@@ -1,6 +1,6 @@
 # CPU Allocator
 
-CRI Resource Manager has a separate CPU allocator component that helps policies
+NRI Resource Policy has a separate CPU allocator component that helps policies
 make educated allocation of CPU cores for workloads.  Currently all policies
 utilize the built-in CPU allocator. See policy specific documentation for more
 details.
@@ -14,7 +14,7 @@ request "near" each other in order to minimize memory latencies between CPUs.
 ## CPU Prioritization
 
 The CPU allocator also does automatic CPU prioritization by detecting CPU
-features and their configuration parameters. Currently, CRI Resource Manager
+features and their configuration parameters. Currently, NRI Resource Policy
 supports CPU priority detection based on the `intel_pstate` scaling
 driver in the Linux CPUFreq subsystem, and, Intel Speed Select Technology
 (SST).

diff --git a/docs/resource-policy/policy/topology-aware.md b/docs/resource-policy/policy/topology-aware.md
@@ -134,8 +134,7 @@ The policy has a number of configuration options which affect its default behavi
 These options can be supplied as part of the
 [dynamic configuration](../setup.md#using-nri-resource-policy-agent-and-a-configmap)
 received via the [`node agent`](../node-agent.md), or in a fallback or forced
-[configuration file](../setup.md#using-a-local-configuration-from-a-file). These
-configuration options are
+configuration file. These configuration options are
 
   - `PinCPU`
     * whether to pin workloads to assigned pool CPU sets

diff --git a/docs/resource-policy/quick-start.md b/docs/resource-policy/quick-start.md
@@ -5,7 +5,8 @@ Resource Policy plugin.
 
 ## Pre-requisites
 
-- containerd or cri-o container runtime installed and running
+- containerd or cri-o container runtime installed and running, and also
+  NRI feature enabled.
 - kubelet installed on your nodes
 
 ## Setup NRI Resource Policy Plugin
@@ -35,17 +36,8 @@ ls build/images
 Copy the nri-resource-policy-topology-aware-deployment.yaml and the
 latest tar file, that was generated by the `make images` command.
 
-NRI needs to be setup in the cluster node:
-
-```
-mkdir -p /etc/nri
-echo "disableConnections: false" > /etc/nri/nri.conf
-mkdir -p /opt/nri/plugins
-```
-
 Note that containerd must have NRI support enabled and NRI is currently only
-available in 1.7beta or later containerd release. This is why you must do
-some extra steps in order to enable NRI plugin support in containerd.
+available in 1.7beta or later containerd release.
 
 This will create a fresh config file and backup the old one if it existed: