Containerd NRI 插件

Github：https://github.com/containerd/nri.git

Slide：https://static.sched.com/hosted_files/kccncna2022/cc/KubeCon-NA-2022-NRI-presentation.pdf

基本介绍

NRI（Node Resource Interface），即节点资源接口，对标 CNI（容器网络接口），是管理容器相关资源的接口框架，独立于具体的容器运行时。NRI 支持将特定逻辑插入兼容 OCI 的运行时，例如，在容器生命周期时间点执行 OCI 规定范围之外的操作，分配和管理容器的设备和其它资源。目前为止，NRI 已经演进到 2.0 版本，该版本在 1.0 版本上进行了重构，增强了接口的能力。

工作原理

“your cluster, your plugin, your rules”，NRI 提供不同生命周期事件的接口，用户在不修改容器运行时源代码的情况下添加自定义逻辑。

以下是 NRI 的工作流程：

NRI 和 CRI 一起工作，在 CRI runtime 源代码中增加了 NRI adaptation 的逻辑。NRI adaptation 的功能包括插件发现、启动和配置，将 NRI 插件与运行时 Pod 和容器的生命周期事件关联，可以理解为 NRI 插件的 client，将 Container 和 Pod 的信息（OCI Spec 的子集）传递给 NRI 插件，同时，接收 NRI 插件返回的执行结果，在 2.0 版本，NRI adaptaion 支持根据 NRI 插件的返回信息更新容器的信息（OCI Spec）。

1.0 版本

NRI 可以追溯到 2020 年 7 月 20 日发布在 containerd 社区的提案：Add Node Resource Interface design doc[1]，大意是，现有的容器网络接口（CNI）在处理不同容器网络栈实现的时候做得很优雅，与传统 Hook 方式介入容器生命周期的方式不同，CNI 提供了安全的 API 注入 Container 生命周期。因此，该提案希望基于类似的思想提出一个用于管理节点资源的接口，处理逻辑位于 Create Container 和 Start Container 之间。

题外话：根据容器网络接口的命名，按理说，应该用容器资源接口（Container Resource Interface），简写 CRI，可能由于 CRI 已经被容器运行时接口（Container Runtime Interface）用了，所以才叫 NRI。（我猜的）

1.0[2] 版本 NRI 功能非常有限，仅用于管理节点的资源。实现方式类似于 OCI Hook，为每个 NRI 事件运行单独的插件实例，容器运行时通过标准输入和标准输出以 JSON 格式数据与插件交互。

Demo 体验

以 containerd 1.6.8 版本为例，体验 1.0 版本的 NRI。

git clone https://github.com/containerd/containerd.git cd containerd git checkout v1.6.8 make && sudo make install  CONTAINERD_DIR=$(cat /lib/systemd/system/containerd.service | grep "ExecStart=" | awk -F= '{gsub("/containerd","",$2); print $2}') sudo cp bin/containerd* ${CONTAINERD_DIR}   

NRI 仓库 1.0 版本分支中没有示例插件，README.md 的示例代码无法成功编译，因此可以使用 v2.0 中的示例代码：https://github.com/containerd/nri/tree/v0.2.0

git clone https://github.com/containerd/nri.git cd nri git checkout v0.2.0 cd examples/clearcfs sed -i '/result := r.NewResult(c.Type())/a \tlogrus.Infof("Invoke clearcfs ok!!")' main.go sed -i '/result := r.NewResult(c.Type())/a \tr.Spec.Annotations["qos.class"]="ls"' main.go sed -i 's/Debugf/Infof/g' main.go go build   

1.0 版本启用 NRI[3]，只需要在 containerd 配置文件中设置 NRI 插件二进制文件所在目录和各插件的配置文件即可，默认目录：

const (     // DefaultBinaryPath for nri plugins     DefaultBinaryPath = "/opt/nri/bin"     // DefaultConfPath for the global nri configuration     DefaultConfPath = "/etc/nri/conf.json"     // Version of NRI     Version = "0.1" )   

因此，只需要将编译好的 NRI 插件二进制文件拷贝到/opt/nri/bin目录，同时在/etc/nri/conf.json添加插件的配置文件：

sudo mkdir /opt/nri/bin sudo mkdir -p /etc/nri  sudo cp clearcfs /opt/nri/bin sudo tee /etc/nri/conf.json <<- EOF {   "version": "0.1",   "plugins": [     {       "type": "clearcfs"     }   ] } EOF   

通过 crictl 启动容器：

tee container-config.yaml <<- EOF metadata:   name: busybox image:   image: busybox command:   - busybox   - sh   - -c   - echo busybox $(sleep inf) log_path: busybox.0.log linux: {} EOF  tee pod-config.yaml <<- EOF metadata:   name: nginx-sandbox   namespace: default   attempt: 1   uid: hdishd83djaidwnduwk28bcsb log_directory: /tmp linux: {} EOF  sudo systemctl start containerd crictl pull registry.cn-hangzhou.aliyuncs.com/google_containers/pause:3.6 ctr -n k8s.io i tag registry.cn-hangzhou.aliyuncs.com/google_containers/pause:3.6 registry.k8s.io/pause:3.6 sudo crictl run container-config.yaml pod-config.yaml   

结果验证：

sudo journalctl -xe -u containerd | grep -e "Invoke clearcfs ok" -e "clearing cfs"   

查看 cpu quota 的值：

源码分析

在 NRI 插件中，实现了 Invoke 方法：

func (c *clearCFS) Invoke(ctx context.Context, r *types.Request) (*types.Result, error) {     result := r.NewResult(c.Type())     r.Spec.Annotations["qos.class"] = "ls"     logrus.Infof("Invoke clearcfs ok!!")     if r.State != types.Create {         return result, nil     }      switch r.Spec.Annotations["qos.class"] {     case"ls":         logrus.Infof("clearing cfs for %s", r.ID)         control, err := cgroups.Load(cgroups.V1, cgroups.StaticPath(r.Spec.CgroupsPath))         if err != nil {             returnnil, err         }          quota := int64(-1)         return result, control.Update(&specs.LinuxResources{             CPU: &specs.LinuxCPU{                 Quota: &quota,             },         })     }     return result, nil }   

通过 Request 携带的 Spec 信息得到容器的 CgroupsPath，读取容器的 Cgroups 文件，然后通过control.Update方法修改 LinuxCPU.Quota 的值为-1。

1.0 版本中，NRI adaptation 能够传递给 NRI 插件的信息包括：

• NRI 插件的配置信息

• 容器当前生命周期的状态（create，delete，update，pause，resume）

• 容器 ID

• SandboxID

• 容器进程 Pid

• Labels

• 精简版的容器运行时信息，主要内容包括

• 容器使用的资源

• Namespaces

• CgroupsPath

• Annotations

type Spec struct {     // Resources struct from the OCI specification     //     // Can be WindowsResources or LinuxResources     Resources json.RawMessage `json:"resources"`     // Namespaces for the container     Namespaces map[string]string`json:"namespaces,omitempty"`     // CgroupsPath for the container     CgroupsPath string`json:"cgroupsPath,omitempty"`     // Annotations passed down to the OCI runtime specification     Annotations map[string]string`json:"annotations,omitempty"` }   

2.0 版本

2.0 版本 NRI 只需要运行一个插件实例用于处理所有 NRI 事件和请求，容器运行时通过 unix-domain socket 与插件通信，使用基于 protobuf 的协议数据，和 1.0 版本相比拥有更高的性能，能够实现有状态的 NRI 插件。

Demo 体验

最新发布的 Containerd 版本集成了 NRI 2.0， NRI 仓库的示例程序也更完善。

# 回到 containerd 本地代码仓库 cd containerd git checkout main make && sudo make install  CONTAINERD_DIR=$(cat /lib/systemd/system/containerd.service | grep "ExecStart=" | awk -F= '{gsub("/containerd","",$2); print $2}') sudo cp bin/containerd* ${CONTAINERD_DIR}   

2.0 版本的配置文件和 1.0 版本有些不同：

sudo tee -a /etc/containerd/config.toml <<- EOF [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" EOF  sudo tee /etc/nri/nri.conf <<- EOF disableConnections: false EOF   

NRI 插件二进制的默认目录更改为/opt/nri/plugins。

2.0 版本的示例程序源代码位于 nri/plugins[4] 目录下（以 logger 为例）：

cd nri cd plugins/logger  go build -o 01-logger sudo mkdir /opt/nri/plugins sudo cp 01-logger /opt/nri/plugins   

插件的配置文件路径为/etc/nri/conf.d，文件名可以是id-basename.conf和basename.conf：

此外，NRI 并没有规定插件配置文件的格式，用户可以通过Configure接口自定义实现。在 logger 示例，可以看到，解析的配置文件为 yaml 格式：

func (p *plugin) Configure(config, runtime, version string) (stub.EventMask, error) {     log.Infof("got configuration data: %q from runtime %s %s", config, runtime, version)     if config == "" {         return p.mask, nil     }      oldCfg := cfg     err := yaml.Unmarshal([]byte(config), &cfg)     if err != nil {         return0, fmt.Errorf("failed to parse provided configuration: %w", err)     }      p.mask, err = api.ParseEventMask(cfg.Events...)     if err != nil {         return0, fmt.Errorf("failed to parse events in configuration: %w", err)     }      if cfg.LogFile != oldCfg.LogFile {         f, err := os.OpenFile(cfg.LogFile, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)         if err != nil {             log.Errorf("failed to open log file %q: %v", cfg.LogFile, err)             return0, fmt.Errorf("failed to open log file %q: %w", cfg.LogFile, err)         }         log.SetOutput(f)     }      return p.mask, nil }   

Logger 的配置项包括：

type config struct {     LogFile       string`json:"logFile"`     Events        []string`json:"events"`     AddAnnotation string`json:"addAnnotation"`     SetAnnotation string`json:"setAnnotation"`     AddEnv        string`json:"addEnv"`     SetEnv        string`json:"setEnv"` }   

为 logger 插件配置 log 的存储路径：

sudo mkdir /etc/nri/conf.d sudo mkdir /var/run/containerd/nri sudo tee /etc/nri/conf.d/01-logger.conf <<- EOF logFile: /var/run/containerd/nri/logger.log EOF   

重启 containerd，运行容器：

sudo systemctl restart containerd  crictl pull registry.cn-hangzhou.aliyuncs.com/google_containers/pause:3.8 ctr -n k8s.io i tag registry.cn-hangzhou.aliyuncs.com/google_containers/pause:3.8 registry.k8s.io/pause:3.8 sudo crictl run container-config.yaml pod-config.yaml   

除了在 containerd 启动的同时加载 NRI 插件，也支持手动运行插件（需要修改/etc/nri/nri.conf的disableConnections为 true）：

/opt/nri/plugins/nri-logger -idx 01 -logFile /var/run/containerd/nri/logger.log   

查看 log 文件：

cat /var/run/containerd/nri/logger.log   

可以看到，logger 打印了不同接口函数从 NRI adaptation 得到的 Pod 和 Container 相关信息：

源码分析

对于 logger 插件，只需要实现 NRI 接口函数，例如，CreateContainer：

func (p *plugin) CreateContainer(pod *api.PodSandbox, container *api.Container) (*api.ContainerAdjustment, []*api.ContainerUpdate, error) {     dump("CreateContainer", "pod", pod, "container", container)      adjust := &api.ContainerAdjustment{}      if cfg.AddAnnotation != "" {         adjust.AddAnnotation(cfg.AddAnnotation, fmt.Sprintf("logger-pid-%d", os.Getpid()))     }     if cfg.SetAnnotation != "" {         adjust.RemoveAnnotation(cfg.SetAnnotation)         adjust.AddAnnotation(cfg.SetAnnotation, fmt.Sprintf("logger-pid-%d", os.Getpid()))     }     if cfg.AddEnv != "" {         adjust.AddEnv(cfg.AddEnv, fmt.Sprintf("logger-pid-%d", os.Getpid()))     }     if cfg.SetEnv != "" {         adjust.RemoveEnv(cfg.SetEnv)         adjust.AddEnv(cfg.SetEnv, fmt.Sprintf("logger-pid-%d", os.Getpid()))     }      return adjust, nil, nil }   

2.0 版本的 NRI 插件可以通过CreateContainer接口修改容器的 OCI Spec 内容，能被修改的范围定义在api.ContainerAdjustment：

type ContainerAdjustment struct {     state         protoimpl.MessageState     sizeCache     protoimpl.SizeCache     unknownFields protoimpl.UnknownFields      Annotations map[string]string`protobuf:"bytes,2,rep,name=annotations,proto3" json:"annotations,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`     Mounts      []*Mount                  `protobuf:"bytes,3,rep,name=mounts,proto3" json:"mounts,omitempty"`     Env         []*KeyValue               `protobuf:"bytes,4,rep,name=env,proto3" json:"env,omitempty"`     Hooks       *Hooks                    `protobuf:"bytes,5,opt,name=hooks,proto3" json:"hooks,omitempty"`     Linux       *LinuxContainerAdjustment `protobuf:"bytes,6,opt,name=linux,proto3" json:"linux,omitempty"` }   

• 容器的 Annotations

• 容器的 Mounts

• 容器的环境变量

• 容器的 OCI Hooks

• 容器使用的资源，定义在 api.LinuxContainerAdjustment

• Devices

• 容器使用的 Linux 资源

• Cgroups 路径

type LinuxContainerAdjustment struct {     state         protoimpl.MessageState     sizeCache     protoimpl.SizeCache     unknownFields protoimpl.UnknownFields      Devices     []*LinuxDevice  `protobuf:"bytes,1,rep,name=devices,proto3" json:"devices,omitempty"`     Resources   *LinuxResources `protobuf:"bytes,2,opt,name=resources,proto3" json:"resources,omitempty"`     CgroupsPath string`protobuf:"bytes,3,opt,name=cgroups_path,json=cgroupsPath,proto3" json:"cgroups_path,omitempty"` }   

接口列表

除了Configure和CreateContainer，NRI 插件能实现的接口函数还包括：

func (p *plugin) Synchronize(pods []*api.PodSandbox, containers []*api.Container) ([]*api.ContainerUpdate, error) {     dump("Synchronize", "pods", pods, "containers", containers)     returnnil, nil }  func (p *plugin) Shutdown() {     dump("Shutdown") }  func (p *plugin) RunPodSandbox(pod *api.PodSandbox) error {     dump("RunPodSandbox", "pod", pod)     returnnil }  func (p *plugin) StopPodSandbox(pod *api.PodSandbox) error {     dump("StopPodSandbox", "pod", pod)     returnnil }  func (p *plugin) RemovePodSandbox(pod *api.PodSandbox) error {     dump("RemovePodSandbox", "pod", pod)     returnnil }  func (p *plugin) PostCreateContainer(pod *api.PodSandbox, container *api.Container) error {     dump("PostCreateContainer", "pod", pod, "container", container)     returnnil }  func (p *plugin) StartContainer(pod *api.PodSandbox, container *api.Container) error {     dump("StartContainer", "pod", pod, "container", container)     returnnil }  func (p *plugin) PostStartContainer(pod *api.PodSandbox, container *api.Container) error {     dump("PostStartContainer", "pod", pod, "container", container)     returnnil }  func (p *plugin) UpdateContainer(pod *api.PodSandbox, container *api.Container) ([]*api.ContainerUpdate, error) {     dump("UpdateContainer", "pod", pod, "container", container)     returnnil, nil }  func (p *plugin) PostUpdateContainer(pod *api.PodSandbox, container *api.Container) error {     dump("PostUpdateContainer", "pod", pod, "container", container)     returnnil }  func (p *plugin) StopContainer(pod *api.PodSandbox, container *api.Container) ([]*api.ContainerUpdate, error) {     dump("StopContainer", "pod", pod, "container", container)     returnnil, nil }  func (p *plugin) RemoveContainer(pod *api.PodSandbox, container *api.Container) error {     dump("RemoveContainer", "pod", pod, "container", container)     returnnil }  func (p *plugin) onClose() {     os.Exit(0) }   

可以看到，NRI 插件可以在 Pod 和 Container 的生命周期加入自定义逻辑。

Pod 生命周期

• 创建 Pod

• 停止 Pod

• 删除 Pod

NRI 插件可使用的信息

• ID

• name

• UID

• namespace

• labels

• annotations

• cgroup parent directory

• runtime handler name

type PodSandbox struct {     state         protoimpl.MessageState     sizeCache     protoimpl.SizeCache     unknownFields protoimpl.UnknownFields      Id             string`protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`     Name           string`protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`     Uid            string`protobuf:"bytes,3,opt,name=uid,proto3" json:"uid,omitempty"`     Namespace      string`protobuf:"bytes,4,opt,name=namespace,proto3" json:"namespace,omitempty"`     Labels         map[string]string`protobuf:"bytes,5,rep,name=labels,proto3" json:"labels,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`     Annotations    map[string]string`protobuf:"bytes,6,rep,name=annotations,proto3" json:"annotations,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`     RuntimeHandler string`protobuf:"bytes,7,opt,name=runtime_handler,json=runtimeHandler,proto3" json:"runtime_handler,omitempty"`     Linux          *LinuxPodSandbox  `protobuf:"bytes,8,opt,name=linux,proto3" json:"linux,omitempty"`     Pid            uint32`protobuf:"varint,9,opt,name=pid,proto3" json:"pid,omitempty"`// for NRI v1 emulation }   

Container 生命周期

• 创建容器 (*)

• 创建容器完成

• 启动容器

• 启动容器完成

• 更新容器 (*)

• 更新容器完成

• 停止容器 (*)

• 删除容器

NRI 插件可使用的信息

• ID

• pod ID

• name

• state

• labels

• annotations

• command line arguments

• environment variables

• mounts

• OCI hooks

• linux

• memory

• CPU

• Block I/O class

• RDT class

• limit

• reservation

• swap limit

• kernel limit

• kernel TCP limit

• swappiness

• OOM disabled flag

• hierarchical accounting flag

• hugepage limits

• shares

• quota

• period

• realtime runtime

• realtime period

• cpuset CPUs

• cpuset memory

• namespace IDs

• devices

• resources

type Container struct {     state         protoimpl.MessageState     sizeCache     protoimpl.SizeCache     unknownFields protoimpl.UnknownFields      Id           string`protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`     PodSandboxId string`protobuf:"bytes,2,opt,name=pod_sandbox_id,json=podSandboxId,proto3" json:"pod_sandbox_id,omitempty"`     Name         string`protobuf:"bytes,3,opt,name=name,proto3" json:"name,omitempty"`     State        ContainerState    `protobuf:"varint,4,opt,name=state,proto3,enum=nri.pkg.api.v1alpha1.ContainerState" json:"state,omitempty"`     Labels       map[string]string`protobuf:"bytes,5,rep,name=labels,proto3" json:"labels,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`     Annotations  map[string]string`protobuf:"bytes,6,rep,name=annotations,proto3" json:"annotations,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`     Args         []string`protobuf:"bytes,7,rep,name=args,proto3" json:"args,omitempty"`     Env          []string`protobuf:"bytes,8,rep,name=env,proto3" json:"env,omitempty"`     Mounts       []*Mount          `protobuf:"bytes,9,rep,name=mounts,proto3" json:"mounts,omitempty"`     Hooks        *Hooks            `protobuf:"bytes,10,opt,name=hooks,proto3" json:"hooks,omitempty"`     Linux        *LinuxContainer   `protobuf:"bytes,11,opt,name=linux,proto3" json:"linux,omitempty"`     Pid          uint32`protobuf:"varint,12,opt,name=pid,proto3" json:"pid,omitempty"`// for NRI v1 emulation }   

创建容器时可修改的信息

• annotations

• mounts

• environment variables

• OCI hooks

• linux

• memory

• CPU

• Block I/O class

• RDT class

• limit

• reservation

• swap limit

• kernel limit

• kernel TCP limit

• swappiness

• OOM disabled flag

• hierarchical accounting flag

• hugepage limits

• shares

• quota

• period

• realtime runtime

• realtime period

• cpuset CPUs

• cpuset memory

• devices

• resources

type ContainerAdjustment struct {     state         protoimpl.MessageState     sizeCache     protoimpl.SizeCache     unknownFields protoimpl.UnknownFields      Annotations map[string]string`protobuf:"bytes,2,rep,name=annotations,proto3" json:"annotations,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`     Mounts      []*Mount                  `protobuf:"bytes,3,rep,name=mounts,proto3" json:"mounts,omitempty"`     Env         []*KeyValue               `protobuf:"bytes,4,rep,name=env,proto3" json:"env,omitempty"`     Hooks       *Hooks                    `protobuf:"bytes,5,opt,name=hooks,proto3" json:"hooks,omitempty"`     Linux       *LinuxContainerAdjustment `protobuf:"bytes,6,opt,name=linux,proto3" json:"linux,omitempty"` }   

更新容器时可修改的信息

容器被创建成功后，插件可以在以下时间请求更新容器的信息：

1. 响应其他容器创建的请求时

2. 响应任意更新容器的请求时

3. 相应任意停止容器的请求时

4. 单独发起更新请求

更新容器信息时，可以修改的信息包括：

• resources

• shares

• quota

• period

• realtime runtime

• realtime period

• cpuset CPUs

• cpuset memory

• limit

• reservation

• swap limit

• kernel limit

• kernel TCP limit

• swappiness

• OOM disabled flag

• hierarchical accounting flag

• hugepage limits

• memory

• CPU

• Block I/O class

• RDT class

type ContainerUpdate struct {     state         protoimpl.MessageState     sizeCache     protoimpl.SizeCache     unknownFields protoimpl.UnknownFields      ContainerId   string`protobuf:"bytes,1,opt,name=container_id,json=containerId,proto3" json:"container_id,omitempty"`     Linux         *LinuxContainerUpdate `protobuf:"bytes,2,opt,name=linux,proto3" json:"linux,omitempty"`     IgnoreFailure bool`protobuf:"varint,3,opt,name=ignore_failure,json=ignoreFailure,proto3" json:"ignore_failure,omitempty"` }   

参考资料

[1] Add Node Resource Interface design doc: https://github.com/containerd/containerd/pull/4411

[2] 1.0: https://github.com/containerd/nri/blob/main/README-v0.1.0.md

[3] 1.0 版本启用 NRI: https://github.com/containerd/containerd/blob/v1.6.8/vendor/github.com/containerd/nri/README.md

[4] nri/plugins: https://github.com/containerd/nri/tree/main/plugins