Cilium 在 kind 集群中的镜像预加载（Preload）：原理、完整部署流程与故障排查

Cilium 在 kind 集群中的镜像预加载Preload原理、完整部署流程与故障排查【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium导读本指南围绕 Cilium 官方文档中“在 kind 集群每个 worker 节点预加载cilium镜像”这一关键步骤展开讲解为什么需要在 kind 集群里预加载镜像、如何通过docker pull与kind load docker-image完成预加载并串起从依赖安装、kind 配置、建集群、Helm 部署到连通性验证的完整落地流程。读完本文你将掌握在本地多节点 kind 环境尤其是离线或受限网络环境中快速、可靠地部署 Cilium 的完整实战方案并理解镜像预加载与image.pullPolicyIfNotPresent之间的配合关系。说明本文所有文件路径均以当前仓库根目录为起点。核心操作依据见 Documentation/installation/kind.rst 及其引用的 Documentation/installation/kind-preload.rst。为什么需要预加载 Cilium 镜像kindKubernetes in Docker会在 Docker 上以容器方式模拟多节点 Kubernetes 集群。这意味着每个“节点”本质上是一个 Docker 容器节点内的容器运行时containerd与宿主机上的 Docker 是隔离的宿主机 Docker 拉取的镜像并不会自动出现在kind 节点容器内kind 节点内的 containerd 如果需要拉取镜像会直接从远端镜像仓库如quay.io拉取在本地开发、内网或离线air-gapped场景下直接从quay.io/cilium/cilium拉取镜像可能缓慢、不稳定甚至不可达。因此Cilium 官方在 kind 部署流程中专门设计了**预加载preload**环节先在宿主机上用 Docker 拉取 Cilium 镜像再通过kind load docker-image把它导入每个 kind 节点的 containerd从而让集群内的镜像分发不再依赖外部网络。该环节在文档中位于 “Install Cilium” 一节紧跟在 Helm 仓库准备之后、helm install之前见 Documentation/installation/kind.rst。核心操作预加载 Cilium 镜像Documentation/installation/kind-preload.rst 给出的完整操作只有两条命令docker pull quay.io/cilium/cilium:IMAGE_TAG kind load docker-image quay.io/cilium/cilium:IMAGE_TAG下面逐一拆解其含义与注意事项。第一步docker pull拉取镜像到宿主机docker pull quay.io/cilium/cilium:IMAGE_TAG镜像仓库为quay.io/cilium/cilium即 Cilium 的官方镜像仓库IMAGE_TAG是版本占位符由文档系统在渲染时替换为当前文档对应版本的标签在仓库中当前版本号记录在根目录的 VERSION 文件stable.txt则记录稳定版本信息。实际部署时请将IMAGE_TAG替换为你希望安装的版本标签例如v1.x.y并保证与后续 Helm chart 使用的镜像版本一致。这一步骤把镜像放进宿主机 Docker 的本地镜像缓存为下一步导入做准备。如果你的网络能正常访问quay.io此步即可完成若身处受限网络则需要提前在可达环境中完成 pull 并导出/导入镜像。第二步kind load docker-image导入每个节点kind load docker-image quay.io/cilium/cilium:IMAGE_TAG该命令会把宿主机 Docker 中的镜像导入 kind 集群所有节点包括 control-plane 与全部 worker的 containerd默认作用于当前kubectlcontext 指向的 kind 集群若存在多个 kind 集群可结合kind get clusters确认并使用--name指定目标集群也可以使用--nodes参数只向部分节点导入但默认的“全部节点”行为恰好满足 Cilium DaemonSet 在每个节点运行 agent 的诉求。执行成功后kind 节点内的 containerd 已拥有该镜像后续创建 Pod 时无需再从远端拉取从而显著缩短部署时间并规避网络不稳定带来的失败。预加载在整个 kind 部署流程中的位置预加载并非孤立步骤它位于 Cilium kind 安装流程的“Install Cilium”阶段。完整流程按 Documentation/installation/kind.rst 的编排如下1. 安装依赖Install Dependencies按 Documentation/installation/kind-install-deps.rst 要求准备docker稳定版kubectl v1.14.0helm v3.13.0kind v0.7.0。2. 配置 kindConfigure kindkind 集群的创建通过 YAML 配置完成。这一步必须禁用默认 CNI否则无法替换为 Cilium。仓库提供了可直接下载的模板 Documentation/installation/kind-config.yamlkind: Cluster apiVersion: kind.x-k8s.io/v1alpha4 nodes: - role: control-plane - role: worker - role: worker - role: worker networking: disableDefaultCNI: true该配置会创建 1 个 control-plane 3 个 worker 的 4 节点集群。详见 Documentation/installation/kind-configure.rst。注意子网冲突kind 默认 Pod 子网为10.244.0.0/16、Service 子网为10.96.0.0/12。若与本地网络冲突务必在networking段显式指定不冲突的podSubnet与serviceSubnet否则部署 Cilium 后可能出现连通性问题。例如networking: disableDefaultCNI: true podSubnet: 10.10.0.0/16 serviceSubnet: 10.11.0.0/163. 创建集群Create a cluster按 Documentation/installation/kind-create-cluster.rst 执行kind create cluster --configkind-config.yaml等待数十秒到数分钟后一个 4 节点集群即创建完成。此时会新增名为kind-kind的kubectlcontext写入KUBECONFIG未设置时写入~/.kube/config可用以下命令确认kubectl cluster-info --context kind-kind注意在 Cilium 部署完成前节点会一直处于NotReady状态这是预期行为无需惊慌。4. 安装 CiliumInstall Cilium这是预加载步骤所在的阶段。完整顺序为a. 配置 Helm 仓库见 Documentation/installation/k8s-install-download-release.rsthelm repo add cilium https://helm.cilium.io/Cilium chart 也同时发布在 Quay.io 与 Docker Hub 的 OCI Registry 上可直接使用oci://协议安装无需先添加仓库。b. 预加载镜像本文核心见 Documentation/installation/kind-preload.rstdocker pull quay.io/cilium/cilium:IMAGE_TAG kind load docker-image quay.io/cilium/cilium:IMAGE_TAGc. 通过 Helm 安装helm install cilium cilium/cilium --namespace kube-system \ --set image.pullPolicyIfNotPresent \ --set ipam.modekubernetes这里有两个关键配置与预加载步骤紧密配合image.pullPolicyIfNotPresent告知 kubelet“镜像已存在于节点时不要重新拉取”。由于镜像已经通过kind load docker-image注入每个节点使用该策略可确保 Pod 直接使用本地预加载的镜像避免因尝试再次访问远端仓库而失败或变慢ipam.modekubernetes使用 Kubernetes 原生的 Pod IP 分配默认的 CRD 模式在 kind 场景下也可用此处按官方 kind 指南明确指定。5. 验证安装Validate the Installation安装后可用两种方式验证详见 Documentation/installation/k8s-install-validate.rst。方式一Cilium CLI先按 Documentation/installation/cli-status.rst 检查集群状态再运行连通性测试见 Documentation/installation/cli-connectivity-test.rstcilium connectivity test正常情况下输出类似✅ 69/69 tests successful (0 warnings)方式二kubectl 手动验证先观察组件是否就绪见 Documentation/installation/kubectl-status.rstkubectl -n kube-system get pods --watch所有cilium-*与coredns-*Pod 变为Running即说明安装成功通常需要几分钟。随后部署官方连通性检查清单见 Documentation/installation/kubectl-connectivity-test.rstkubectl create ns cilium-test kubectl apply -n cilium-test -f examples/kubernetes/connectivity-check/connectivity-check.yaml清单会部署一系列覆盖“带/不带 Service 负载均衡”“多种网络策略组合”等连通路径的 PodPod 名称标识测试变体READY/STATUS即结果kubectl get pods -n cilium-test提示若在单节点kind 集群中部署涉及多节点的 Pod 会一直停留在Pending这是预期行为多节点测试至少需要 2 个节点才能调度成功。另外若 Pod 因 “too many open files” 部署失败可在宿主机上调大inotify资源限制。测试完成后清理kubectl delete ns cilium-test进阶Socket LB 在 kind 下的 cgroup 前提如果你希望在 kind 中启用 Cilium 的 Socket LB即 kubeproxy-free 模式Documentation/installation/kind.rst 明确列出了三个前提条件必须启用cgroup v2例如内核参数systemd.unified_cgroup_hierarchy1kind 节点必须运行在独立的 cgroup namespace中且与宿主机底层 cgroup namespace 不同这样 Cilium 才能在正确的 cgroup 层级上挂载 BPF 程序。可用以下命令验证三个值互不相同docker exec kind-control-plane ls -al /proc/self/ns/cgroup docker exec kind-worker ls -al /proc/self/ns/cgroup ls -al /proc/self/ns/cgroup在 Docker 中需设置dockerd --default-cgroupns-modeprivate以启用 cgroup namespace同时要求禁用 cgroup v1 的net_cls/net_prio控制器或直接cgroup_no_v1all或宿主内核 5.14含相关修复。故障排查无法连接 k8s api-server若 Cilium agent 日志中出现levelerror msgUnable to contact k8s api-server errorGet https://10.96.0.1:443/api/v1/namespaces/kube-system: dial tcp 10.96.0.1:443: connect: no route to host原因通常是kind 节点是 Docker 容器、与宿主机共享内核若 Socket LB 未被禁用Cilium 挂载的 eBPF 程序可能已过期不再把 api-server 请求路由到当前的kind-control-plane容器。解决办法是重建 kind 集群并重新执行本文的 Helm 安装命令以分离过期的 eBPF 程序。Cilium agent Pod 持续崩溃若 agent Pod 崩溃且日志中出现levelwarning msg bpftool cgroup attach /var/run/cilium/cgroupv2 connect6 pinned /sys/fs/bpf/tc/globals/cilium_cgroups_connect6 subsysdatapath-loader levelwarning msgError: failed to attach program subsysdatapath-loader这通常说明你正在一个已经运行着 Cilium 的环境例如 Cilium 开发 VM里再部署 kind 集群或父级 cgroup 层级上存在重叠的 BPF cgroup 程序。此时应停止原有 Cilium或按 bpftool 文档手动分离父级 cgroup 层级上的重叠 BPF cgroup 程序参见 Documentation/installation/kind.rst 的 Troubleshooting 章节。扩展用 kind 模拟 Cluster Mesh预加载的思路同样适用于更复杂的场景——官方文档还演示了如何用 kind 在沙箱中模拟Cluster Mesh见 Documentation/installation/kind.rst创建两份不重叠子网的 kind 配置如集群 1 用podSubnet: 10.0.0.0/16、serviceSubnet: 10.1.0.0/16集群 2 用10.2.0.0/16、10.3.0.0/16分别执行kind create cluster --namecluster1 --configkind-cluster1.yaml kind create cluster --namecluster2 --configkind-cluster2.yaml随后在两个集群中分别完成镜像预加载与 Cilium 部署再按 Cluster Mesh 指南进行配置kind 场景下需将NodePortService 部署到kube-system命名空间。多个集群并存时记得为kind load docker-image使用--name指定目标集群这正是预加载命令在多集群场景下的正确用法。小结镜像预加载docker pullkind load docker-image是 Cilium 官方 kind 部署流程中承上启下的关键一步它让 Cilium 镜像在无外部网络依赖的情况下抵达每个 kind 节点配合image.pullPolicyIfNotPresent实现本地快速部署并在多集群Cluster Mesh场景下同样适用。按本文梳理的“依赖 → 配置 → 建集群 → 预加载 → Helm 安装 → 验证”流程执行即可获得一个稳定、可复现的本地 Cilium 多节点环境。【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考