Kubespray Docker 容器运行时部署指南cri-dockerd 接入原理与全参数详解【免费下载链接】kubesprayDeploy a Production Ready Kubernetes Cluster项目地址: https://gitcode.com/GitHub_Trending/ku/kubespray在 Kubespray 中部署 Kubernetes 时Docker 依然是官方支持的容器管理器之一。随着 Kubernetes 1.24 移除内置 dockershim本文讲解 Kubespray 如何通过 cri-dockerd 项目继续支持 Docker 运行时并逐项解析container_manager: docker背后的全部配置参数存储驱动、cgroup 驱动、DNS 限制、日志轮转、镜像加速等。读完后你能够直接在 inventory 中完成 Docker 节点的各项定制并理解每个参数在 Ansible 角色中的真实落点与生效机制。为什么 Kubespray 还要支持 Dockercri-dockerd 的定位Kubernetes 从 1.24 起废弃了 kubelet 内置的 dockershim但这并不意味着 Docker 被放弃。Kubespray 的官方立场在 docs/CRI/docker.md 中表述得很明确Docker 运行时受支持其替代方案是通过 Mirantis 支持的 cri-dockerd 项目——它是一个独立的 CRI 插件将 kubelet 的 CRI 调用桥接到 Docker Engine API。在 Kubespray 2.20 起cri-dockerd已经在所有受支持的 Kubernetes 版本中全面取代了dockershim。这一选择在角色编排中有直接体现在 container-engine/tasks/main.yml 中容器管理器到角色的映射如下container_manager_role: crio: cri-o docker: cri-dockerd containerd: containerd也就是说当你在 inventory 中设置container_manager: docker时Kubespray 实际加载的是container-engine/cri-dockerd角色来部署 CRI 端点而container-engine/docker角色负责安装 Docker Engine 本体。两者分工明确共同构成Docker 作为 Kubernetes 容器运行时的完整链路。启用方式只有一行container_manager: dockerCI 测试矩阵中也验证了该配置的多种形态例如 tests/files/debian12-docker.yml、tests/files/almalinux9-docker.yml、tests/files/ubuntu22-all-in-one-docker.yml 等。Docker 角色的默认值与安装机制所有参数默认值集中在 roles/container-engine/docker/defaults/main.yml关键项包括变量默认值说明docker_version28.3Docker Engine 版本docker_cli_version{{ docker_version }}docker CLI 版本默认与 Engine 一致docker_cgroup_driversystemdcgroup 驱动仅支持systemd或cgroupfsdocker_bin_dir/usr/bindocker 可执行文件目录docker_orphan_clean_upfalse是否启用 Docker 孤儿资源清理docker_repo_key_keyring默认注释Debian 系 GPG key 存放路径roles/container-engine/docker/tasks/main.yml 的执行流程体现了 Kubespray 的健壮性设计OS 变量分发通过with_first_found按发行版大版本、发行版、OS 家族等优先级依次匹配 vars 目录 下的文件debian.yml、redhat.yml、fedora.yml、suse.yml等确定各发行版对应的 docker-ce 软件源与包名仓库配置Debian/Ubuntu 用apt_key/apt_repository安装 GPG key 与仓库可经docker_repo_key_keyring指定 keyring 路径Fedora 与 RedHat 系则分别渲染 fedora_docker.repo.j2 和 rh_docker.repo.j2旧包清理默认移除发行版自带的旧 docker 包docker、docker-engine、docker.io等见docker_remove_packages_yum/docker_remove_packages_apt以及 podman避免与 containerd 冲突安装并锁定版本package模块安装docker_package_info.pkgs安装成功后在 apt 系上用dpkg_selections将docker-ce、docker-ce-cli等置为hold注释明确写着 This is required to ensure any apt upgrade will not break kubernetes——防止系统级 apt upgrade 意外变更 Docker 版本破坏集群失败自愈如果docker服务启动失败rescue 分支会自动删除/etc/systemd/system/docker.service.d/下 Kubespray 生成的全部 drop-in 配置文件并重启从错误配置中恢复插件安装循环包含 docker_plugin.yml 安装docker_plugins指定的插件如 gvisor、kata-containers 运行时见 roles/container-engine/tasks/main.yml 中gvisor_enabled and container_manager in [docker, containerd]的联动条件systemd 配置落盘由 systemd.yml 统一处理下一节详述。核心参数逐项解析对照官方文档以下参数说明完整继承自 docs/CRI/docker.md 与 inventory/sample/group_vars/all/docker.yml并补充了源码中的实际渲染位置。存储与 cgroup 驱动# 强制使用 overlay2 存储驱动仅较新内核支持 docker_storage_options: -s overlay2 # 修改 cgroup 驱动native.cgroupdriver可选 systemd 或 cgroupfs默认 systemd docker_cgroup_driver: systemddocker_cgroup_driver的最终落点在 docker-options.conf.j2 中被渲染为 dockerd 启动参数--exec-opt native.cgroupdriver{{ docker_cgroup_driver }}。保持systemd是 Kubespray 的默认推荐因为 kubelet 同样使用 systemd cgroup 驱动两者一致可避免容器统计与资源限制异常。DNS 数量限制docker_dns_servers_strict: falseDocker 最多只接受 3 个 nameserver。Kubespray 默认行为docker_dns_servers_strict: false且resolvconf_mode docker_dns时会通过 set_facts_dns.yml 收集 DNS facts仅取前 3 个 nameserver 写入docker-dns.conf.j2对应的 systemd drop-insystemd.yml 第 34-40 行。若你希望 DNS 超过 3 个时不截断由系统自行处理可将该变量置为false的严格语义按文档描述默认下超过 3 个 nameserver 会导致部署失败设置为false可避免该失败。数据目录、iptables 与日志# Docker 数据目录 docker_daemon_graph: /var/lib/docker # dockerd 的 iptables 支持字符串 false/true docker_iptables_enabled: false # 容器 stderr/stdout 日志50m 轮转保留最近 5 个 docker_log_opts: --log-opt max-size50m --log-opt max-file5从 docker-options.conf.j2 可以看到三者的真实拼接方式EnvironmentDOCKER_OPTS{{ docker_options|default() }} --iptables{{ docker_iptables_enabled | default(false) }} \ --exec-opt native.cgroupdriver{{ docker_cgroup_driver }} \ ... \ --data-root{{ docker_daemon_graph }} \ {% if ansible_facts[os_family] not in [openSUSE Leap, openSUSE Tumbleweed, Suse] %}{{ docker_log_opts }}{% endif %}值得注意的两个实现细节docker_iptables_enabled默认即为falseinventory/sample/group_vars/all/docker.yml 第 25 行。Kubespray 默认关闭 dockerd 的 iptables因为 Kubernetes 的网络插件Calico/Flannel/Cilium 等会自行管理 kube-proxy 所需的 iptables 规则双重管理容易冲突docker_log_opts在 SUSE 系发行版上会被跳过不写入这是对发行版 dockerd 构建差异的兼容处理。二进制目录、包缓存与 GPG keyring# docker 可执行文件目录除非使用自定义 docker 包否则不应修改 docker_bin_dir: /usr/bin # 安装后保留 docker 安装包kubespray 每次运行会删除包文件 # 缓存为 1 时加速重复的 ansible 执行 docker_rpm_keepcache: 1 # Debian 系指定 GPG key 存放路径避免使用 apt_key 模块的默认位置 docker_repo_key_keyring: /etc/apt/trusted.gpg.d/docker.gpgdocker_bin_dir不仅影响 handlerhandlers/main.yml 中等待 Docker 就绪时执行{{ docker_bin_dir }}/docker images并重试 20 次也影响孤儿清理脚本的安装路径systemd.yml 将其复制到{{ bin_dir }}/cleanup-docker-orphans.sh。关于docker_repo_key_keyring任务代码 tasks/main.yml 第 49-61 行在 apt 系主机上以apt_key: keyring: {{ docker_repo_key_keyring | default(omit) }}安装 GPG key——即只有显式设置该变量才会覆盖apt_key模块的默认 keyring 路径。私有仓库与镜像加速# 允许以 http 方式访问自建 registry可以是 IP 或域名 docker_insecure_registries: - mirror.registry.io - 172.19.16.11 # 添加额外的 registry mirror文档示例为国内镜像 docker_registry_mirrors: - https://registry.docker-cn.com - https://mirror.aliyuncs.com这两组变量在 docker-options.conf.j2 中通过 for 循环渲染为 dockerd 的--insecure-registry与--registry-mirror启动参数。前者用于私有/自签证书的仓库访问例如配合 docs/advanced/registry.md 部署的集群内 registry后者用于加速公有镜像拉取。挂载传播与自定义启动参数# 覆盖默认 MountFlags可选 shared / slave / private留空为系统默认 docker_mount_flags: # 追加传给 docker daemon 的任意字符串内容原样出现 docker_options: 在 docker-options.conf.j2 中docker_mount_flags只有非空时才渲染为 systemd unit 的MountFlags指令控制 Docker 文件系统命名空间内挂载/卸载事件是否传播docker_options则以字符串拼接方式置于DOCKER_OPTS最前文档特别强调该字符串会原样出现因此书写时要保证它本身是合法的 dockerd 参数片段。systemd drop-in 全景roles/container-engine/docker/tasks/systemd.yml 是全部 Docker 定制化参数的最终汇聚点它按条件渲染以下文件目标文件触发条件承载的参数/etc/systemd/system/docker.servicedocker.service.j2非 Flatcar / 非 Fedora CoreOS服务主体docker_daemon_graph、docker_storage_options等docker.service.d/http-proxy.confhttp-proxy.conf.j2定义了http_proxy/https_proxy代理环境变量docker.service.d/docker-options.conf始终上表全部 daemon 参数docker.service.d/docker-dns.confdocker-dns.conf.j2dns_mode ! none且resolvconf_mode docker_dns截断后的 nameserver 列表docker.service.d/docker-orphan-cleanup.confdocker_orphan_clean_up: true配合 cleanup-docker-orphans.sh 定期清理孤儿容器/网络每次 drop-in 变更都会notify: Restart docker由 handlers/main.yml 执行daemon_reload 重启服务 docker images就绪探测。对于 Flatcar/Fedora CoreOS 这类只读根文件系统场景handler 转而重启docker.socket——这也解释了为何角色中多处出现is_ostree、is_fedora_coreos判断。版本升级与退出 Docker 的迁移路径升级tasks/pre-upgrade.yml 在每次执行时负责升级 Docker 组件升级场景可参考 tests/files/ubuntu24-crio-upgrade.yml 所在目录的 CI 用例命名约定pre-upgrade → 主流程 → post-upgrade回滚清理tasks/reset.yml 供reset.ymlplaybook 使用负责卸载 Docker 相关组件迁移到 containerd如果未来你决定从 Docker 切换到 containerd仓库提供了专门的迁移文档 docs/upgrades/migrate_docker2containerd.md核心动作是在 inventory 中改回container_manager: containerd该值也是 roles/kubespray_defaults/defaults/main/main.yml 中container_manager的全局默认值。小结一份可复制的最小 Docker 节点配置综合以上各节一个典型的 Docker 节点 inventory 片段置于group_vars/all/下container_manager: docker docker_storage_options: -s overlay2 docker_cgroup_driver: systemd docker_dns_servers_strict: false docker_daemon_graph: /var/lib/docker docker_iptables_enabled: false docker_log_opts: --log-opt max-size50m --log-opt max-file5 docker_rpm_keepcache: 1 # docker_insecure_registries: # - 172.19.16.11 # docker_registry_mirrors: # - https://mirror.aliyuncs.com # docker_mount_flags: # docker_options: # docker_repo_key_keyring: /etc/apt/trusted.gpg.d/docker.gpg需要记住的关键事实链container_manager: docker→ 安装 roles/container-engine/docker 部署 Docker Engine 28.3默认→ 加载 roles/container-engine/cri-dockerd 提供 CRI 端点 → kubelet 通过 cri-dockerd 驱动容器。所有 daemon 级定制最终都汇聚到/etc/systemd/system/docker.service.d/下的 drop-in 文件这一设计使得 Kubespray 的管理配置与发行版原生docker.service解耦也便于排查我的参数为什么没生效——答案几乎总是检查对应的 drop-in 是否按触发条件被渲染。【免费下载链接】kubesprayDeploy a Production Ready Kubernetes Cluster项目地址: https://gitcode.com/GitHub_Trending/ku/kubespray创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考