Kubespray 镜像加速实战:用 *_image_repo 与 files_repo 变量配置公共下载镜像 Kubespray 镜像加速实战用 *_image_repo 与 files_repo 变量配置公共下载镜像【免费下载链接】kubesprayDeploy a Production Ready Kubernetes Cluster项目地址: https://gitcode.com/GitHub_Trending/ku/kubespray本篇技术文章围绕 Kubespray 仓库中的 公共下载镜像文档 展开讲清楚“公共下载镜像”这一机制的设计目的、底层实现原理与完整配置方法。读完后你将能够在网络受限地区如中国大陆部署生产级 Kubernetes 集群时通过一组镜像仓库变量gcr_image_repo、kube_image_repo等和文件源变量files_repo把 Kubespray 的全部下载流量切换到可信镜像站并结合源码理解镜像变量如何生效、哪些资源不受镜像控制以及镜像方案与离线air-gap方案的边界。1. 什么是公共下载镜像Kubespray 部署集群时需要从公网拉取两类资源容器镜像etcd、Calico、Cilium、CoreDNS、pause、kube-proxy 等组件镜像分别托管在gcr.io、registry.k8s.io、docker.io、quay.io、ghcr.io等公共镜像仓库静态文件kubelet/kubeadm/kubectl 二进制、etcd 压缩包、CNI 插件、containerd、Cilium CLI、Helm 等二进制/压缩包来自 GitHub Releases、dl.k8s.io、storage.googleapis.com、get.helm.sh等地址。在这些资源原始站点访问缓慢或不通的地区文档原文明确以中国为例可以使用公共下载镜像站做转发代理。公共镜像站本质上是一层透明的内容转发/缓存层保持与源站相同的仓库路径和文件路径结构客户端只需把“源站域名/地址前缀”替换为“镜像站域名/地址前缀”即可。Kubespray 没有为镜像站写死任何专用逻辑而是把仓库前缀和文件前缀全部抽成了 Ansible 变量这正是镜像加速方案能够以“纯配置变更”实现的原因。2. 源码原理镜像变量在哪里定义、如何生效2.1 镜像仓库变量的默认值所有镜像相关变量的默认定义集中在 kubespray_defaults 角色的默认值文件# gcr and kubernetes image repo define gcr_image_repo: gcr.io kube_image_repo: registry.k8s.io kubeadm_image_repo: {{ kube_image_repo }} # docker image repo define docker_image_repo: docker.io # quay image repo define quay_image_repo: quay.io # github image repo define (ex multus only use that) github_image_repo: ghcr.io这 5 个外加派生的kubeadm_image_repo变量就是整个镜像加速机制的“开关面板”。每个变量对应一个上游镜像站变量默认值对应上游典型消费者举例kube_image_reporegistry.k8s.ioKubernetes 官方镜像仓库pod_infra_image_repo: {{ kube_image_repo }}/pause、CoreDNS、metrics-server、Nodelocal DNS、各 CSI sidecar 组件gcr_image_repogcr.ioGoogle Container RegistryGKE 相关镜像等docker_image_repodocker.ioDocker HubFlannel、Kube-OVN、kube-router、Nginx/HAProxy LB 镜像等quay_image_repoquay.ioQuayetcdetcd_image_repo: {{ quay_image_repo }}/coreos/etcd、Calico 全系镜像、Cilium、cert-manager、MetalLB 等github_image_repoghcr.ioGitHub Container Registrymultus-cni、kube-vip 等2.2 变量如何拼成最终镜像地址从源码结构看download.yml中所有组件镜像地址都是**“仓库前缀变量 固定路径”拼接**出来的。例如 download.ymlkube_proxy_image_repo: {{ kube_image_repo }}/kube-proxy etcd_image_repo: {{ quay_image_repo }}/coreos/etcd etcd_image_tag: v{{ etcd_version }} flannel_image_repo: {{ docker_image_repo }}/flannel/flannel calico_node_image_repo: {{ quay_image_repo }}/calico/node pod_infra_image_repo: {{ kube_image_repo }}/pause这意味着只要把quay_image_repo从quay.io改成quay.m.daocloud.ioetcd 和 Calico 镜像的拉取地址就整体切换为quay.m.daocloud.io/coreos/etcd、quay.m.daocloud.io/calico/node路径结构与上游完全一致——这正是镜像站能够无缝替换的前提。2.3 下载流程downloads 表 download 角色文件与镜像清单集中定义在 download.yml 的downloads字典中每一项声明container镜像或file文件、repo/url、checksum、目标节点组groups等字段。下载逻辑由 download 角色 驱动- name: Download | Download files / images include_tasks: {{ include_file }} loop: {{ downloads | combine(kubeadm_images) | dict2items }} vars: download: {{ download_defaults | combine(item.value) }} include_file: download_{% if download.container %}container{% else %}file{% endif %}.yml文件类走 download_file.yml用get_url拉取并强制做 checksum 校验checksum: {{ download.checksum }}校验失败会触发重新下载镜像类走 download_container.yml按container_manager选择 pull 命令docker / nerdctl / crictl对image_reponame即“镜像仓库变量 路径 tag”拼接结果执行 pull。因此镜像变量既影响 Kubespray 预下载阶段的 pull 地址也影响后续各组件 Deployment 中声明的 image 字段——一处修改全链路生效。2.4 静态文件的前缀变量github_url 等文件下载地址由 4 个“URL 根”变量拼出默认值见 download.ymlgithub_url: https://github.com dl_k8s_io_url: https://dl.k8s.io storage_googleapis_url: https://storage.googleapis.com get_helm_url: https://get.helm.sh kubelet_download_url: {{ dl_k8s_io_url }}/release/v{{ kube_version }}/bin/linux/{{ image_arch }}/kubelet etcd_download_url: {{ github_url }}/etcd-io/etcd/releases/download/v{{ etcd_version }}/etcd-v{{ etcd_version }}-linux-{{ image_arch }}.tar.gz cni_download_url: {{ github_url }}/containernetworking/plugins/releases/download/v{{ cni_version }}/cni-plugins-linux-{{ image_arch }}-v{{ cni_version }}.tgz helm_download_url: {{ get_helm_url }}/helm-v{{ helm_version }}-linux-{{ image_arch }}.tar.gz例如etcd_download_url展开后是https://github.com/etcd-io/etcd/releases/download/...。把github_url换成镜像站对应前缀后路径含/etcd-io/etcd/releases/...保持不变即可命中镜像缓存。此外还有download_retries默认 4 次重试、download_run_once、download_cache_dir等配套参数与镜像配置正交可按需组合。3. 配置 Kubespray 使用镜像站按 官方镜像文档 给出的做法将如下内容写入your_inventory/group_vars/k8s_cluster.ymlinventory 的 group_vars 优先级高于 role defaults因此可覆盖 默认值# this should be in your_inventory/group_vars/k8s_cluster.yml gcr_image_repo: gcr.m.daocloud.io kube_image_repo: k8s.m.daocloud.io docker_image_repo: docker.m.daocloud.io quay_image_repo: quay.m.daocloud.io github_image_repo: ghcr.m.daocloud.io files_repo: https://files.m.daocloud.io逐项说明前 5 行把 5 个镜像仓库前缀整体切换到 DaoCloud 公共镜像站*.m.daocloud.io。注意kube_image_repo的镜像前缀是k8s.m.daocloud.io而非registry.m.daocloud.io各前缀与源站的对应关系以镜像站文档为准files_repo这是 Kubespray 中“文件镜像源”的统一入口变量。在离线/代理场景中它被拼接成{{ files_repo }}/github.com、{{ files_repo }}/dl.k8s.io等 URL 根见下节供二进制与压缩包下载使用。配置完成后按常规方式执行集群部署即可例如ansible-playbook -i inventory/hosts.ini -b cluster.yml下载任务会自动走镜像地址。安全边界原文重要提醒请只在你信任的提供商处使用镜像站。Kubespray 团队无法验证公共镜像的可靠性与安全性镜像站本质上是“别人替你缓存并转发二进制/镜像”一旦镜像站被污染或篡改影响等同于直接执行了被篡改的组件。你可以把m.daocloud.io替换为任何你信任的、路径结构与源站一致的镜像站。不受镜像变量控制的地址从 download.yml 的源码结构看azure_csi_image_repomcr.microsoft.com/...与gcp_pd_csi_image_repogke.gcr.io等个别 CSI 镜像地址是硬编码的完整域名未走*_image_repo变量拼接。可以推断如果启用了这些云厂商 CSI 组件镜像站方案不覆盖其镜像需要另行处理例如在 containerd 层面配置对应 prefix 的 registry mirror。4. 与离线air-gap环境的files_repo用法对比镜像文档 开头明确指出镜像站的配置方式可参照 离线环境文档 中“把镜像/文件下载指向替代站点”的同一套变量。两者的关键区别在于镜像站方案镜像站自动同步上游内容你只需改前缀不关心内容完整性离线方案需要你在有网环境预先用 contrib/offline/generate_list.sh 生成清单把静态文件、OS 包、镜像搬运到内网 HTTP 服务/私有 registry再配置 offline.yml 风格的变量。离线方案对files_repo目录结构的约定值得镜像场景直接借鉴离线文档 中的 Tip 与示例配置github_url: {{ files_repo }}/github.com dl_k8s_io_url: {{ files_repo }}/dl.k8s.io storage_googleapis_url: {{ files_repo }}/storage.googleapis.com get_helm_url: {{ files_repo }}/get.helm.sh即用原始域名作为files_repo下的一级目录github.com/、dl.k8s.io/、storage.googleapis.com/、get.helm.sh/这样所有*_download_url展开后路径与上游逐字节一致。inventory 内置的离线示例文件 进一步展示了另一种粒度的做法——不覆盖整个 URL 根而是逐个覆盖具体二进制的*_download_urlcni、crictl、etcd、calicoctl、helm、containerd 等只镜像你真正用到的组件。离线方案还支持带认证的files_repoURL 中内嵌user:pass并提醒unsafe_show_logs为 true 时 download_file.yml 打印下载 URL 的任务会泄露凭据。另外镜像站方案与容器运行时的 registry mirrorcontainerd_registries_mirrors/containerd_registry_auth是两个层面的机制前者决定Kubespray 预下载与各组件 manifest 中的镜像地址后者决定节点运行时 kubelet/容器运行时自行 pull 时的回退路由见 离线文档 中 containerd 私有 registry 的配置示例。若集群中还有 Kubespray 之外的工作负载需要拉取上游镜像建议同时配置运行时层面的 mirror。5. 社区维护的镜像站官方镜像文档 列出了当前社区维护的公共镜像站点DaoCloud中国其开源项目分别为镜像转发项目public-image-mirror对应gcr.m.daocloud.io、k8s.m.daocloud.io、docker.m.daocloud.io、quay.m.daocloud.io、ghcr.m.daocloud.io等前缀与二进制文件转发项目public-binary-files-mirror对应files.m.daocloud.io前缀。接入前建议先到该项目仓库确认其覆盖的上游域名与缓存策略。对于自建镜像contrib/offline 目录提供了离线部署的工具链清单生成、离线文件/镜像管理脚本、Nginx 配置、Artifactory 上传脚本等可以作为自建“私有 files_repo 私有 registry”的参考起点。6. 配置后如何验证与排查确认变量生效在运行 playbook 前可用ansible-inventory --list或ansible-playbook ... --list-tasks配合debug检查 inventory 变量是否按预期覆盖 role defaults观察下载日志文件下载任务download_file.yml使用get_url并强制 checksum 校验。若镜像站返回内容不完整checksum 不匹配会触发重下download_retries控制重试次数若镜像站缺失某个对象则表现为 404 类错误——此时可退回单文件粒度参考 offline.yml 的方式只把失败的*_download_url指回源站镜像拉取镜像类下载download_container.yml最终执行的是 docker/nerdctl/crictl 的 pull 命令pull 地址来自*_image_repo拼接结果download_always_pull、download_run_once可控制重复拉取与集中缓存行为保持信任链无论使用公共镜像站还是自建文件源Kubespray 始终会对二进制做 checksum 校验校验值来自 download.yml 中与各版本绑定的*_checksum这是你应对“镜像站内容不一致/被篡改”风险的最后一道校验不要关闭download_validate_certs等安全开关去迁就镜像站。7. 小结Kubespray 的镜像加速机制可以概括为三句话所有镜像地址 *_image_repo前缀变量 固定路径所有文件地址 github_url/dl_k8s_io_url等 URL 根 固定路径定义于 download.yml在your_inventory/group_vars/k8s_cluster.yml中覆盖这些前缀变量即可把全部下载流量切到任意“路径一致”的镜像站官方给出的 DaoCloud 配置为现成模板公共镜像站无法验证安全性务必选择可信提供方gke.gcr.io、mcr.microsoft.com等硬编码地址不受变量控制需单独评估。核心参考文件镜像文档、离线环境文档、默认下载变量、离线示例 inventory、离线工具集。【免费下载链接】kubesprayDeploy a Production Ready Kubernetes Cluster项目地址: https://gitcode.com/GitHub_Trending/ku/kubespray创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考