containerd config 命令详解与 config.toml 配置指南从默认配置生成到版本迁移【免费下载链接】containerdAn open and reliable container runtime项目地址: https://gitcode.com/GitHub_Trending/co/containerdcontainerd 守护进程的启动行为完全由 TOML 格式的config.toml配置文件决定而containerd config命令是获取、检视和迁移这套配置的核心工具。本文将基于 containerd 仓库中的官方手册containerd-config.8 与 containerd-config.toml.5结合 config.go、server/config/config.go 等源码实现完整讲解containerd config的三个子命令、config.toml 的全部配置项与默认值、版本 4 配置格式以及配置文件的加载、导入与自动迁移机制。读完本文你将能够从零生成一份可用的 containerd 配置、按需定制多运行时如 runc 与其他 OCI 运行时配置并理解旧版配置如何平滑升级到最新格式。containerd config 命令总览根据手册 containerd-config.8.mdcontainerd config命令的用法为containerd config [command]它的职责是提供 containerd 配置的相关信息。在源码层面该命令定义于 cmd/containerd/command/config.go由 urfave/cli 注册到 containerd 主命令之下见 cmd/containerd/command/main.go。手册只描述了default一个子命令但当前仓库源码实际注册了三个子命令均以标准输出stdout打印 TOML 格式配置子命令作用源码位置containerd config default输出当前版本 containerd 守护进程的默认配置config.gocontainerd config dump输出最终生效的主配置即读取磁盘上的主配置并把所有imports引入的子配置文件合并后的结果config.gocontainerd config migrate将当前配置文件迁移到最新版本并输出不迁移子配置文件config.go三个子命令最终都经由outputConfigconfig.go输出它先加载全部插件注册信息将插件默认配置解码进[plugins]段补齐超时timeouts配置然后把version字段设置为当前配置版本常量最后用 go-toml/v2 编码器以缩进表格式打印到 stdout。生成默认配置containerd config default手册指出containerd config default会把本版本守护进程的默认配置输出到标准输出通常的使用方式有两种管道重定向为标准配置将输出写入/etc/containerd/config.toml默认配置文件路径守护进程启动时自动加载配合--config选项配置文件可以放在任意文件系统位置通过containerd --config /path/to/config.toml显式指定。例如# 方式一写入默认位置 containerd config default /etc/containerd/config.toml # 方式二放到自定义路径启动时指定 containerd config default /data/containerd/my-config.toml containerd --config /data/containerd/my-config.toml默认配置里到底有什么从platformAgnosticDefaultConfigconfig.go可以看出containerd config default生成的配置至少包含以下内容version设置为version.ConfigVersion当前最新版本为 4rootdefaults.DefaultRootDir在 Unix 上为/var/lib/containerddefaults_unix.gostatedefaults.DefaultStateDir在 Linux 上为/run/containerddefaults_linux.goimportsdefaults.DefaultConfigIncludePattern在 Unix 上为/etc/containerd/conf.d/*.tomldefaults_unix.go即默认会引入 conf.d 目录下的所有 drop-in 配置[plugins.io.containerd.server.v1.grpc]address为/run/containerd/containerd.sockmax_recv_message_size与max_send_message_size均为 16 MiB16 20见 defaults.gostream_processors默认注册两个 ocicrypt 解密流处理器io.containerd.ocicrypt.decoder.v1.tar.gzip与io.containerd.ocicrypt.decoder.v1.tar调用ctd-decoder二进制并指向/etc/containerd/ocicrypt/keys密钥目录config.go。值得注意的是默认配置的Imports已包含/etc/containerd/conf.d/*.toml这一 glob 模式说明从 v2 起 drop-in 配置已成为默认行为无需手动在imports中声明。config.toml 文件格式与全部配置项containerd config default输出的 TOML 文件即 containerd-config.toml.5.md 所描述的config.toml。文件必须位于/etc/containerd/config.toml或通过containerd --config指定若两处都不存在containerd 直接使用内置默认配置即containerd config default的输出。整个文件由一组全局设置、若干面向特定领域的节section以及一个供各插件存放专属配置的[plugins]段组成。下面按手册顺序逐一说明。全局字段version: 指定配置版本。未填写时按版本 1 解析版本 4 是当前最新版本旧版配置会在启动时自动迁移详见下文配置迁移机制。root: containerd 元数据的根目录存储持久化数据。默认/var/lib/containerd。state: containerd 的状态目录存储临时数据。默认/run/containerd。plugin_dir: 存放动态插件的目录。disabled_plugins: 需要禁用的插件 ID需使用完整限定插件 URI如io.containerd.x.vx。被禁用的插件不会被初始化与启动。required_plugins: 必需插件 ID 列表。任一必需插件不存在、初始化失败或启动失败都会导致 containerd 退出。oom_score: 应用到 containerd 守护进程的 OOM 分数。默认 0。timeouts: 以时长字符串duration形式指定的超时配置例如[timeouts] io.containerd.timeout.shim.cleanup 5s io.containerd.timeout.shim.load 5s io.containerd.timeout.shim.shutdown 3s io.containerd.timeout.task.state 2s手册中以注释形式给出该示例实际生效时需取消注释。imports: 额外配置文件列表用于把主配置文件拆分管理例如供应商可以在独立文件中维护自定义运行时配置而不改动主config.toml。导入规则非空int/string简单字段会被覆盖array与map字段会追加/合并导入文件同样带版本号且其版本不能高于主配置文件。stream_processors: 内容流处理器配置各字段及默认值为accepts默认[]接受的媒体类型media-type列表returns默认输出/返回的媒体类型path默认处理二进制程序的路径或名称args默认[]传给二进制的参数。已弃用段版本 4 中迁移为服务器插件[grpc](版本 4 中已弃用): gRPC socket 监听器设置。版本 4 中请改用服务器插件io.containerd.server.v1.grpc与io.containerd.server.v1.grpc-tcp旧配置会自动迁移。包含属性address默认/run/containerd/containerd.socktcp_addresstcp_tls_certtcp_tls_keyuid默认 0gid默认 0max_recv_message_sizemax_send_message_size[ttrpc](版本 4 中已弃用): TTRPC 设置。版本 4 中请改用服务器插件io.containerd.server.v1.ttrpc。在旧版本中若未显式设置 TTRPC 地址会从 gRPC 地址派生grpcAddress .ttrpc并继承 gRPC 的 UID/GID在版本 4 中每个服务器插件独立配置省略 TTRPC 插件配置块时使用其自身默认值。包含属性address默认uid默认 0gid默认 0[debug](版本 4 中已弃用): 启用并配置 debug socket 监听器。版本 4 中请改用服务器插件io.containerd.server.v1.debug。包含属性address默认debug 端点默认不监听uid默认 0gid默认 0level默认info设置 debug 日志级别支持trace、debug、info、warn、error、fatal、panicformat默认text设置日志格式支持text与json[metrics](版本 4 中已弃用): 启用并配置 metrics 监听器。版本 4 中请改用服务器插件io.containerd.server.v1.metrics。包含属性address默认metrics 端点默认不监听grpc_histogram默认false开关 gRPC 直方图指标[cgroup] 段[cgroup]: Linux cgroup 专属设置段。path默认为创建的容器指定自定义 cgroup 路径。[proxy_plugins] 段[proxy_plugins]: 配置通过 gRPC 通信的代理插件。每个代理插件包含type默认address默认[plugins] 段默认启用插件的配置项[plugins]段存放已安装插件暴露的配置。以下是默认启用插件及其配置项数据来源手册 containerd-config.toml.5.md插件 ID配置项默认值io.containerd.server.v1.grpcaddress/run/containerd/containerd.sockuid当前有效 UIDgid当前有效 GIDmax_recv_message_size16777216max_send_message_size16777216io.containerd.server.v1.grpc-tcpaddress 为空则跳过addresstls_cert/tls_key/tls_ca/tls_common_name—max_recv_message_size16777216max_send_message_size16777216io.containerd.server.v1.ttrpcaddress/run/containerd/containerd.sock.ttrpcuid当前有效 UIDgid当前有效 GIDio.containerd.server.v1.debugaddress 为空则跳过addressuid0gid0io.containerd.server.v1.metricsaddress 为空则跳过addressio.containerd.monitor.v1.cgroupsno_prometheusfalseio.containerd.service.v1.diff-servicedefault[walking]io.containerd.gc.v1.schedulerpause_threshold0.02deletion_threshold0不触发mutation_threshold100schedule_delay0ms立即startup_delay100msio.containerd.runtime.v2.taskplatforms受支持平台列表sched_corefalseio.containerd.service.v1.tasks-serviceblockio_config_file仅 Linuxrdt_config_file仅 Linuxio.containerd.grpc.v1.cri.containerddefault_runtime_namerunc其中几个关键项说明如下GC 调度器io.containerd.gc.v1.scheduler的五个参数用于对垃圾回收调度器做高级调优pause_threshold是 GC 应被调度的最大暂停时间deletion_threshold保证删除 n 次后触发 GCmutation_threshold保证数据库发生 n 次变更后触发 GCschedule_delay定义触发事件后调度 GC 前的延迟startup_delay定义启动后调度首次 GC 前的延迟。任务运行时io.containerd.runtime.v2.task的sched_core启用核心调度Core Scheduling该特性只允许受信任的任务在共享计算资源如同一核心的超线程的 CPU 上并发运行。tasks-service的blockio_config_fileLinux 专用指定 blockio 类别定义文件路径控制 I/O 调度器优先级与带宽限流rdt_config_fileLinux 专用指定用于配置 RDT 的文件路径启用 Intel RDT缓存与内存带宽管理技术。CRI 插件io.containerd.grpc.v1.cri下的default_runtime_name指定默认运行时名称其子节点runtimes可注册一个或多个命名运行时。版本 4 配置示例以下是手册给出的版本 4 完整配置示例其中服务器设置gRPC、TTRPC、debug均以插件形式配置version 4 root /var/lib/containerd state /run/containerd oom_score 0 imports [/etc/containerd/runtime_*.toml, ./debug.toml] [plugins.io.containerd.server.v1.grpc] address /run/containerd/containerd.sock [plugins.io.containerd.server.v1.ttrpc] address /run/containerd/containerd.sock.ttrpc [plugins.io.containerd.server.v1.debug] address /run/containerd/debug.sock level info [cgroup] path [plugins] [plugins.io.containerd.monitor.v1.cgroups] no_prometheus false [plugins.io.containerd.service.v1.diff-service] default [walking] [plugins.io.containerd.gc.v1.scheduler] pause_threshold 0.02 deletion_threshold 0 mutation_threshold 100 schedule_delay 0 startup_delay 100ms [plugins.io.containerd.runtime.v2.task] platforms [linux/amd64] sched_core true [plugins.io.containerd.service.v1.tasks-service] blockio_config_file rdt_config_file 示例中imports同时使用了 glob 模式/etc/containerd/runtime_*.toml与相对路径./debug.toml。从 config.go 的resolveImports实现看含*的路径按 glob 匹配展开非绝对路径会相对于父配置文件所在目录解析绝对路径原样返回。多运行时Multiple Runtimes配置[plugins.io.containerd.grpc.v1.cri.containerd.runtimes]下可以注册多个命名运行时。以下是手册给出的双运行时示例[plugins] [plugins.io.containerd.grpc.v1.cri] [plugins.io.containerd.grpc.v1.cri.containerd] default_runtime_name runc [plugins.io.containerd.grpc.v1.cri.containerd.runtimes] [plugins.io.containerd.grpc.v1.cri.containerd.runtimes.runc] privileged_without_host_devices false runtime_type io.containerd.runc.v2 [plugins.io.containerd.grpc.v1.cri.containerd.runtimes.runc.options] BinaryName /usr/bin/runc [plugins.io.containerd.grpc.v1.cri.containerd.runtimes.other] privileged_without_host_devices false runtime_type io.containerd.runc.v2 [plugins.io.containerd.grpc.v1.cri.containerd.runtimes.other.options] BinaryName /usr/bin/path-to-runtime该配置创建了两个命名运行时runc与other并将默认运行时设为runc。要点如下这些运行时配置仅用于通过 CRI 调起的运行时。若 Pod 要使用非默认的other运行时其 spec 需要携带名为other的runtime_handler字段来指明使用该命名运行时。命名规范运行时位于[plugins.io.containerd.grpc.v1.cri.containerd.runtimes]下每个运行时使用唯一名称如...runtimes.runc]每个运行时还可在...runtimes.runtime.options]下携带 shim 专属选项如...runtimes.runc.options]。runtime_type指定使用的 shim示例中为io.containerd.runc.v2用于在 Linux 上运行 OCI 兼容运行时而BinaryName是 shim 专属选项指定实际 OCI 运行时的路径。io.containerd.runc.v2运行时在 Linux 上运行 runc 等 OCI 兼容运行时。上例中名为runc的配置会让 shim 启动/usr/bin/runc而名为other的配置会让 shim 启动/usr/bin/path-to-runtime。配置加载、合并与命令行覆盖守护进程的加载顺序从 cmd/containerd/command/main.go 可以看到守护进程启动时的配置处理流程以defaultConfig()作为初始配置仅当配置文件存在或用户显式传入--config时才调用LoadConfigWithPlugins读取并合并磁盘配置config.go通过applyFlags将命令行 flag 应用到配置——flag 优先级高于配置文件main.go。例如--root、--state会覆盖同名配置项--address会写入 gRPC 插件配置并在未显式配置 TTRPC 时顺带把 TTRPC 地址推导为grpcAddress .ttrpc并继承 uid/gid--log-level、--log-format同理。imports 的合并语义LoadConfigWithPlugins会循环处理主文件及其所有 imports并检测循环导入随后用mergeConfigconfig.go合并其规则与手册一致与value合并得value非空简单字段覆盖数组追加去重如[]{1}[]{2}→[]{1,2}map 按 key 合并但值整体替换StreamProcessors、ProxyPlugins、Timeouts整段替换。版本校验ValidateVersionconfig.go会拒绝版本号高于当前配置版本的配置并校验disabled_plugins/required_plugins必须使用含.的完整 URI形如io.containerd.x.vx。配置版本迁移机制手册指出若配置文件中未指定 version则按版本 1 解析版本 4 为最新旧配置在启动时自动迁移。源码给出了完整实现证据迁移函数表migrationsconfig.gov0 视为 v1无迁移、v1→v2 执行v1Migrate、v2→v3 无迁移、v3→v4 执行serviceMigrateMigrateConfigToconfig.go逐版本应用迁移直到目标版本v1→v2v1Migrate把短插件名改写为完整限定 URI。v1MigratePluginNameconfig.go内置了一张映射表例如cri→io.containerd.grpc.v1.cri、cgroups→io.containerd.monitor.v1.cgroups、overlayfs→io.containerd.snapshotter.v1.overlayfs、task→io.containerd.runtime.v2.task等-service后缀映射到io.containerd.service.v1.*无法确定归属的短名按io.containerd.grpc.v1.*处理并给出警告v3→v4serviceMigrate把顶层[grpc]、[ttrpc]、[debug]、[metrics]字段迁移到对应服务器插件块io.containerd.server.v1.grpc/grpc-tcp/ttrpc/debug/metrics与io.containerd.metrics.v1.grpc-prometheus并保持旧版 TTRPC 从 gRPC 地址派生的语义config.go。迁移发生时守护进程启动日志会打印形如Configuration migrated from version %d, use containerd config migrate to avoid migration的警告。这正是containerd config migrate子命令存在的意义——手动、提前把主配置文件升级到最新格式避免每次启动都走迁移路径。需要留意的是migrate不迁移子配置文件imports 引入的文件。与之相对的containerd config dump则把主配置与所有子配置合并后的最终形态输出出来适合做启动前的事前检查。小结与调试建议围绕containerd config命令可以总结出几条实用工作流快速上手containerd config default /etc/containerd/config.toml生成基线配置再按需修改检查最终生效配置containerd config dump查看合并所有 imports 后的完整配置排查配置了却没生效的问题同时结合main.go中 flag 覆盖配置文件的规则确认命令行参数是否覆盖了你的设置平滑升级升级 containerd 大版本后用containerd config migrate主动迁移主配置文件到最新版本避免每次启动时的自动迁移告警多运行时接入在[plugins.io.containerd.grpc.v1.cri.containerd.runtimes]下注册命名运行时并在 Pod spec 中通过runtime_handler指定即可在同一 containerd 实例内混用不同 OCI 运行时。若遇到具体问题可参考本仓库内 containerd-config.8.md 与 containerd-config.toml.5.md 两份手册、config.go 与 server/config/config.go 的实现细节以及 config_test.go 中的单元测试用例按上游仓库的 issue 流程反馈。【免费下载链接】containerdAn open and reliable container runtime项目地址: https://gitcode.com/GitHub_Trending/co/containerd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
