容器服务原生节点自定义 containerd 参数配置

概述
TKE 原生节点以 containerd 为默认容器运行时。在节点交付时，您可以通过以下方式对 containerd 进行个性化参数配置：
通过控制台或 MachineSet runtimeRootDir 字段设置 containerd 数据根目录（对应 containerd root 配置项）。
通过控制台或 MachineSet runtimeStateDir 字段设置 containerd state 目录（对应 containerd state 配置项）。
通过控制台或 MachineSet registry 字段配置镜像仓库镜像站点（加速站点）与免证书验证仓库。
通过 PostInit 生命周期脚本，在节点注册完成后修改 containerd 配置（如多仓库证书路径 config_path）。
配置 containerd 数据根目录（runtimeRootDir）
功能说明
runtimeRootDir 对应 /etc/containerd/config.toml 中的 root 字段，用于设置 containerd 存储镜像、容器快照等数据的根目录。默认值为 /var/lib/containerd。
常见使用场景：
将容器数据迁移至独立数据盘（如 /data/docker/runtime/containerd/root），避免系统盘空间耗尽。
遵循业务规范，将所有运行时数据统一放置于指定路径。
注意：
runtimeRootDir 只能在节点池创建时设置，不支持对已有节点原地修改。如需变更存储目录，须将节点移出节点池后重新加入。
通过控制台配置
1. 登录 容器服务控制台，参考 新建原生节点 进入节点池创建流程。
2. 在高级设置中，找到容器目录配置项，填写所需路径（如 /data/docker/runtime/containerd/root）。
3. 单击创建节点池完成配置。
说明：
若已在节点池下挂载数据盘并将挂载路径设置为同一目录（如 /data），containerd 数据将自动写入该数据盘，无需手动额外配置磁盘挂载。
通过 YAML 配置
在 MachineSet 的 spec.template.spec 下设置 runtimeRootDir 字段：
apiVersion: node.tke.cloud.tencent.com/v1beta1
kind: MachineSet
metadata:
  name: np-example
spec:
  template:
    spec:
      runtimeRootDir: /data/docker/runtime/containerd/root
      providerSpec:
        type: Native
        value:
          # ... 其他配置
配置 containerd state 目录（runtimeStateDir）
功能说明
runtimeStateDir 对应 /etc/containerd/config.toml 中的 state 字段，用于设置 containerd 存放运行时状态数据（如容器/任务的运行时元数据、套接字文件）的目录。默认值为 /run/containerd。
与 runtimeRootDir（持久化数据根目录）不同，state 目录中的内容通常随节点重启而重建，多用于满足业务对运行时目录规划的统一规范，或规避默认目录所在文件系统的空间限制。
通过控制台配置
1. 登录 容器服务控制台，参考 新建原生节点 进入节点池创建流程。
2. 在高级设置中，勾选设置 containerd state 目录，填写所需路径（默认值为 /run/containerd）。
3. 单击创建节点池完成配置。
通过 YAML 配置
在 MachineSet 的 spec.template.spec 下设置 runtimeStateDir 字段：
apiVersion: node.tke.cloud.tencent.com/v1beta1
kind: MachineSet
metadata:
  name: np-example
spec:
  template:
    spec:
      runtimeRootDir: /data/docker/runtime/containerd/root
      runtimeStateDir: /run/containerd
      providerSpec:
        type: Native
        value:
          # ... 其他配置
注意：
runtimeStateDir 仅在容器运行时为 containerd 时生效，且只能在节点池创建时设置，不支持对已有节点原地修改。
配置 containerd 镜像仓库（registry）
功能说明
TKE 原生节点支持在节点池创建或编辑时，直接对 containerd 的镜像仓库进行个性化配置，无需再通过 PostInit 脚本手工修改，包含以下两类配置：
容器镜像仓库镜像站点配置：为指定的镜像仓库（如 docker.io）配置一个或多个加速镜像站点（mirror endpoint），并可选择是否开启 override_path。
免证书验证仓库：为指定的仓库地址跳过 TLS 证书校验，适用于使用自签名证书或无证书的私有仓库场景。
 该能力依赖 containerd 1.6 及以上版本的 config_path 机制：配置生效后，TKE 会在节点上自动生成 /etc/containerd/certs.d/<仓库地址>/hosts.toml 文件，无需手动编写。
通过控制台配置
1. 登录 容器服务控制台，参考 新建原生节点 进入节点池创建流程。
2. 在高级设置中，勾选配置镜像仓库。
3. 在容器镜像仓库镜像站点配置中，单击添加，填写以下参数：
参数
说明
容器镜像仓库
需要加速的源镜像仓库地址，如 docker.io。
镜像站点
加速站点地址，如 https://example.com。支持添加多个加速站点，按填写顺序作为优先级。
override_path
是否在拼接镜像地址时保留完整路径。默认为 false。
4. （可选）在免证书验证仓库中，单击添加，填写仓库地址（如 registry.example.com:5000），为该仓库跳过证书校验。
5. 单击创建节点池完成配置。
注意：
免证书验证仓库会跳过 TLS 证书校验，存在被中间人劫持镜像拉取流量的风险，仅建议在可信内网环境中使用。
通过 YAML 配置
在 MachineSet 的 spec.template.spec.providerSpec.value 下设置 registry 字段：
apiVersion: node.tke.cloud.tencent.com/v1beta1
kind: MachineSet
metadata:
  name: np-example
spec:
  template:
    spec:
      runtimeRootDir: /data/docker/runtime/containerd/root
      providerSpec:
        type: Native
        value:
          registry:
            mirrors:
              - registry: docker.io
                endpoints:
                  - https://example.com
                overridePath: false
            insecureRegistries:
              - registry.example.com:5000
字段说明：
字段
说明
registry.mirrors[].registry
源镜像仓库地址，如 docker.io、registry.k8s.io。
registry.mirrors[].endpoints
镜像加速站点地址列表，按顺序写入配置，作为优先级。
registry.mirrors[].overridePath
是否保留镜像地址的完整路径，默认为 false。
registry.insecureRegistries
需跳过证书校验的仓库地址列表。
通过 PostInit 脚本配置多仓库证书路径（config_path）
功能说明
containerd 1.6 及以上版本支持通过 config_path 字段，为不同镜像仓库单独配置 TLS 证书和加速镜像站点。该目录下每个子目录对应一个 Registry 域名，并包含 hosts.toml 配置文件。
典型场景：企业自建镜像仓库需要额外的 TLS 证书，或需要为内网镜像仓库配置私有证书认证。
说明：
若您的需求仅是配置镜像加速站点或跳过证书校验，建议直接使用上文的镜像仓库（registry）配置能力，无需再编写 PostInit 脚本。仅当需要放置自定义 CA 证书等 registry 字段未覆盖的场景时，才需要使用 PostInit 脚本。
配置示例
以下示例通过 PostInit 脚本将 config_path 设置为 /etc/containerd/certs.d，并重启 containerd 使配置生效。
apiVersion: node.tke.cloud.tencent.com/v1beta1
kind: MachineSet
metadata:
  name: np-example
spec:
  template:
    spec:
      runtimeRootDir: /data/docker/runtime/containerd/root
      lifecycle:
        postInit:
          script: |﻿
            #!/bin/bash
            set -e
﻿
            CERTS_DIR="/etc/containerd/certs.d"
            CONFIG_FILE="/etc/containerd/config.toml"
﻿
            # 创建多仓库证书目录
            mkdir -p "${CERTS_DIR}"
﻿
            # 写入 config_path 配置
            if grep -q 'config_path' "${CONFIG_FILE}"; then
              sed -i "s|config_path = .*|config_path = \\"${CERTS_DIR}\\"|" "${CONFIG_FILE}"
            else
              sed -i '/\\[plugins\\."io\\.containerd\\.grpc\\.v1\\.cri"\\.registry\\]/a\\  config_path = "'"${CERTS_DIR}"'"' "${CONFIG_FILE}"
            fi
﻿
            # 重启 containerd 使配置生效
            systemctl restart containerd
            echo "containerd config_path set to: ${CERTS_DIR}"
说明：
PostInit 脚本在 TKE 组件安装完成、节点注册到集群后执行。此时 containerd 已在运行，重启 containerd 不会导致节点退出集群，但会短暂中断容器启动请求（通常数秒内恢复）。
脚本执行失败将导致节点 PostInit 阶段异常，建议充分测试脚本逻辑后再应用到生产节点池。
若需在证书目录中放置自定义 CA 证书，可在 PostInit 脚本中一并完成证书文件的写入。
注意事项
runtimeRootDir、runtimeStateDir、registry 均只能在节点池创建时设置，不支持对已有节点原地修改。如需变更，须将节点移出节点池后重新加入。
runtimeRootDir 与数据盘挂载路径建议保持一致，避免数据盘未挂载时 containerd 数据写入系统盘。
若在同一节点池内使用多个数据盘，建议明确指定各数据盘挂载路径与 runtimeRootDir 的对应关系。
registry 字段仅在容器运行时为 containerd 且版本 ≥ 1.6 时生效，低版本 containerd 或 Docker 运行时携带该字段会被忽略。
相关文档
新建原生节点
﻿原生节点生命周期﻿
﻿Management 参数介绍﻿

参数	说明
容器镜像仓库	需要加速的源镜像仓库地址，如 `docker.io`。
镜像站点	加速站点地址，如 `https://example.com`。支持添加多个加速站点，按填写顺序作为优先级。
override_path	是否在拼接镜像地址时保留完整路径。默认为 `false`。

字段	说明
`registry.mirrors[].registry`	源镜像仓库地址，如 `docker.io`、`registry.k8s.io`。
`registry.mirrors[].endpoints`	镜像加速站点地址列表，按顺序写入配置，作为优先级。
`registry.mirrors[].overridePath`	是否保留镜像地址的完整路径，默认为 `false`。
`registry.insecureRegistries`	需跳过证书校验的仓库地址列表。

原生节点自定义 containerd 参数配置

本页目录：

概述

配置 containerd 数据根目录（runtimeRootDir）

功能说明

通过控制台配置

通过 YAML 配置

配置 containerd state 目录（runtimeStateDir）

功能说明

通过控制台配置

通过 YAML 配置

配置 containerd 镜像仓库（registry）

功能说明

通过控制台配置

通过 YAML 配置

通过 PostInit 脚本配置多仓库证书路径（config_path）

功能说明

配置示例

注意事项

相关文档