docs: add NRI-related documentation.
Co-authored-by: Mike Brown <brownwm@us.ibm.com> Signed-off-by: Krisztian Litkey <krisztian.litkey@intel.com>
This commit is contained in:
Krisztian Litkey
parent
02f0a8b50e
commit
a0daf1c288
141
docs/NRI.md
Normal file
141
docs/NRI.md
Normal file
@ -0,0 +1,141 @@
|
|||||||
|
# NRI Support In Containerd
|
||||||
|
|
||||||
|
## Node Resource Interface
|
||||||
|
|
||||||
|
NRI, the Node Resource Interface, is a common framework for plugging
|
||||||
|
extensions into OCI-compatible container runtimes. It provides basic
|
||||||
|
mechanisms for plugins to track the state of containers and to make
|
||||||
|
limited changes to their configuration.
|
||||||
|
|
||||||
|
NRI itself is agnostic to the internal implementation details of any
|
||||||
|
container runtime. It provides an adaptation library which runtimes
|
||||||
|
use to integrate to and interact with NRI and plugins. In principle
|
||||||
|
any NRI plugin should be able to work with NRI-enabled runtimes.
|
||||||
|
|
||||||
|
For a detailed description of NRI and its capabilities please take a
|
||||||
|
look at the [NRI respository](https://github.com/containerd/nri).
|
||||||
|
|
||||||
|
## Containerd NRI Integration
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary>see the containerd/NRI integration diagram</summary>
|
||||||
|
<img src="./containerd-nri-integration.png" title="Containerd/NRI Integration">
|
||||||
|
</details>
|
||||||
|
|
||||||
|
NRI support in containerd is split into two parts both logically and
|
||||||
|
physically. These parts are a common plugin (/nri/*) to integrate to
|
||||||
|
NRI and CRI-specific bits (/pkg/cri/server/nri-api) which convert
|
||||||
|
data between the runtime-agnostic NRI representation and the internal
|
||||||
|
representation of the CRI plugin.
|
||||||
|
|
||||||
|
### Containerd NRI Plugin
|
||||||
|
|
||||||
|
The containerd common NRI plugin implements the core logic of integrating
|
||||||
|
to and interacting with NRI. However, it does this without any knowledge
|
||||||
|
about the internal representation of containers or pods within containerd.
|
||||||
|
It defines an additional interface, Domain, which is used whenever the
|
||||||
|
internal representation of a container or pod needs to be translated to
|
||||||
|
the runtime agnostic NRI one, or when a configuration change requested by
|
||||||
|
an external NRI plugin needs to be applied to a container within containerd. `Domain` can be considered as a short-cut name for Domain-Namespace as Domain implements the functions the generic NRI interface needs to deal with pods and containers from a particular containerd namespace. As a reminder, containerd namespaces isolate state between clients of containerd. E.g. "k8s.io" for the kubernetes CRI clients, "moby" for docker clients, ... and "containerd" as the default for containerd/ctr.
|
||||||
|
|
||||||
|
### NRI Support for CRI Containers
|
||||||
|
|
||||||
|
The containerd CRI plugin registers itself as an above mentioned NRI
|
||||||
|
Domain for the "k8s.io" namespace, to allow container configuration to be customized by external
|
||||||
|
NRI plugins. Currently this Domain interface is only implemented for
|
||||||
|
the original CRI `pkg/cri/server` implementation. Implementing it for
|
||||||
|
the more recent experimental `pkg/cri/sbserver` implementation is on
|
||||||
|
the TODO list.
|
||||||
|
|
||||||
|
### NRI Support for Other Container 'Domains'
|
||||||
|
|
||||||
|
The main reason for this split of functionality is to allow
|
||||||
|
NRI plugins for other types of sandboxes and for other container clients other than just for CRI containers in the "k8s.io" namespace.
|
||||||
|
|
||||||
|
## Enabling NRI Support in Containerd
|
||||||
|
|
||||||
|
Enabling and disabling NRI support in containerd happens by enabling or
|
||||||
|
disabling the common containerd NRI plugin. The plugin, and consequently
|
||||||
|
NRI functionality, is disabled by default. It can be enabled by editing
|
||||||
|
the `[plugins."io.containerd.nri.v1.nri"]` section in the containerd
|
||||||
|
configuration file, which by default is `/etc/containerd/config.toml`,
|
||||||
|
and changing `disable = true` to `disable = false`. Once enabled, the
|
||||||
|
NRI section should look something like this:
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[plugins."io.containerd.nri.v1.nri"]
|
||||||
|
config_file = "/etc/nri/nri.conf"
|
||||||
|
disable = false
|
||||||
|
plugin_path = "/opt/nri/plugins"
|
||||||
|
socket_path = "/var/run/nri.sock"
|
||||||
|
```
|
||||||
|
|
||||||
|
In addition to this, you need to put a runtime agnostic NRI configuration
|
||||||
|
file in place, to let NRI itself know that it is enabled. You can do this
|
||||||
|
by creating `/etc/nri/nri.conf` with the following content:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
disableConnections: false
|
||||||
|
```
|
||||||
|
|
||||||
|
This enables externally launched NRI plugins to connect and register
|
||||||
|
themselves.
|
||||||
|
|
||||||
|
There are two ways how an NRI plugin can be started. Plugins can be
|
||||||
|
pre-registered in which case they are automatically started when the NRI
|
||||||
|
adaptation is instantiated (or in our case when containerd is started).
|
||||||
|
Plugins can also be started by external means, for instance by systemd.
|
||||||
|
|
||||||
|
Pre-registering a plugin happens by placing a symbolic link to the plugin
|
||||||
|
executable into a well-known NRI-specific directory, `/opt/nri/plugins`
|
||||||
|
by default. A pre-registered plugin is started with a socket pre-connected
|
||||||
|
to NRI. Externally launched plugins connect to a well-known NRI-specific
|
||||||
|
socket, `/var/run/nri.sock` by default, to register themselves. The only
|
||||||
|
difference between pre-registered and externally launched plugins is how
|
||||||
|
they get started and connected to NRI. Once a connection is established
|
||||||
|
all plugins are identical.
|
||||||
|
|
||||||
|
NRI can be configured to disable connections from externally launched
|
||||||
|
plugins, in which case the well-known socket is not created at all. The
|
||||||
|
configuration fragment shown above ensures that external connections are
|
||||||
|
enabled regardless of the built-in NRI defaults. This is convenient for
|
||||||
|
testing as it allows one to connect, disconnect and reconnect plugins at
|
||||||
|
any time.
|
||||||
|
|
||||||
|
For more details about pre-registered and externally launched plugins
|
||||||
|
|
||||||
|
## Testing NRI Support in Containerd
|
||||||
|
|
||||||
|
You can verify that NRI integration is properly enabled and functional by
|
||||||
|
configuring containerd and NRI as described above, taking the NRI
|
||||||
|
logger plugin either from the NRI repository or
|
||||||
|
[this fork](https://github.com/klihub/nri/tree/pr/proto/draft/plugins/logger)
|
||||||
|
on github, compiling it and starting it up.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/klihub/nri
|
||||||
|
cd nri
|
||||||
|
git checkout pr/proto/draft
|
||||||
|
make
|
||||||
|
./build/bin/logger -idx 00
|
||||||
|
```
|
||||||
|
|
||||||
|
You should see the logger plugin receiving receiving a list of existing pods
|
||||||
|
and containers. If you then create or remove further pods and containers
|
||||||
|
using crictl or kubectl you should see detailed logs of the corresponding NRI
|
||||||
|
events printed by the logger.
|
||||||
|
|
||||||
|
## NRI Compatibility With v0.1.0 Plugins
|
||||||
|
|
||||||
|
You can enable backward compatibility with NRI v0.1.0 plugins using the
|
||||||
|
[v010-adapter plugin](https://github.com/klihub/nri/tree/pr/proto/draft/plugins/v010-adapter).
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/klihub/nri
|
||||||
|
cd nri
|
||||||
|
git checkout pr/proto/draft
|
||||||
|
make
|
||||||
|
sudo cp build/bin/v010-adapter /usr/local/bin
|
||||||
|
sudo mkdir -p /opt/nri/plugins
|
||||||
|
sudo ln -s /usr/local/bin/v010-adapter /opt/nri/plugins/00-v010-adapter
|
||||||
|
```
|
||||||
BIN
docs/containerd-nri-integration.png
Normal file
BIN
docs/containerd-nri-integration.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 130 KiB |
Loading…
Reference in New Issue
Block a user