k0s项目Airgap部署中containerd配置问题解析与解决方案

背景介绍

k0s作为一款轻量级Kubernetes发行版，在离线环境（Airgap）部署时需要特别注意容器镜像的管理。近期在v1.30.4+k0s.0版本中，用户报告了Airgap部署失败的问题，核心表现为pause容器镜像无法正确加载。

问题现象

在全新安装的v1.30.4+k0s.0环境中，当使用Airgap模式部署时，系统组件Pod（如calico-node、kube-proxy等）均无法正常启动。通过查看Pod事件日志，发现containerd尝试从外部拉取pause:3.8镜像失败，而实际上Airgap包中只包含pause:3.9版本。

根本原因分析

经过深入排查，发现该问题主要由以下因素导致：

1. containerd配置版本不匹配：用户部署时覆盖了默认的containerd.toml配置文件，使用了旧版格式的配置，导致k0s无法正确注入默认的pause镜像设置。

2. 配置覆盖机制变化：从k0s 1.27.1版本开始，containerd配置采用了新的动态加载机制，旧版的全量覆盖方式会破坏k0s的默认配置。

3. 镜像版本硬编码：虽然k0s默认使用pause:3.9镜像，但旧版配置可能导致containerd回退到硬编码的pause:3.8版本。

解决方案

正确配置containerd

对于需要自定义containerd配置的场景，应采用k0s推荐的配置方式：

1. 使用动态配置目录：将自定义配置放置在/etc/k0s/containerd.d/目录下，而非直接覆盖/etc/k0s/containerd.toml文件。

2. 保留默认配置：k0s会自动生成基础配置，用户只需添加必要的自定义部分。

3. 镜像仓库认证：如需配置私有仓库认证，可创建单独的配置文件，例如：

# /etc/k0s/containerd.d/registry.toml
[plugins."io.containerd.grpc.v1.cri".registry]
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
      endpoint = ["https://registry-1.docker.io"]
  [plugins."io.containerd.grpc.v1.cri".registry.configs]
    [plugins."io.containerd.grpc.v1.cri".registry.configs."registry.example.com".auth]
      username = "user"
      password = "pass"

Airgap部署最佳实践

1. 验证镜像包完整性：部署前检查airgap-images-list.txt确保包含所有必需镜像。

2. 配置镜像拉取策略：在k0s配置中明确设置imagePullPolicy为Never。

3. 版本兼容性检查：确保k0s版本与containerd配置格式匹配。

经验总结

1. 避免全量覆盖配置：现代容器运行时通常采用模块化配置，应优先使用追加方式而非覆盖。

2. 版本升级注意事项：跨多个次要版本升级时，需特别注意配置格式的变化。

3. 离线环境测试：Airgap部署前应在隔离环境充分验证，特别是镜像依赖关系。

通过正确理解k0s的containerd配置机制，并遵循推荐的配置方式，可以避免类似问题的发生，确保Airgap环境下的稳定部署。对于需要深度定制的场景，建议参考k0s官方文档中的运行时配置指南，采用符合当前版本的最佳实践。