在 Kind 上部署 Cilium：本地多节点 Kubernetes 集群的完整安装、验证与排错指南

在 Kind 上部署 Cilium本地多节点 Kubernetes 集群的完整安装、验证与排错指南【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium本指南基于当前仓库的官方文档演示如何用 kind 在本地 Docker 中创建多节点 Kubernetes 集群并部署 eBPF 驱动的 Cilium 网络栈提供网络、安全与可观测能力。读完本文你将掌握从依赖安装、kind 集群配置与创建、Helm 安装 Cilium到状态验证、连通性测试与常见故障排查的完整实战链路并了解如何在 Kind 沙箱中模拟 Cluster Mesh 多集群场景。本文核心步骤对应仓库文档 Documentation/installation/kind-create-cluster.rst并串联其所属的完整 kind 安装指南kind.rst中的配置、安装、验证与排错章节。一、方案概览为什么用 Kind 跑 CiliumKindKubernetes in Docker把每个 Kubernetes 节点control-plane 与 worker作为独立的 Docker 容器运行所有节点共享宿主机的内核。这一点与 Cilium 天然契合——Cilium 基于 eBPF 在内核层面注入数据路径程序因此在同一个内核上运行多节点集群能够真实地验证 eBPF 网络、安全策略与可观测能力在跨节点场景下的行为。本仓库的 Kind 安装指南整体由以下环节构成对应 kind.rst安装依赖Docker、kubectl、Helm、kindkind-install-deps.rst配置 kind通过 YAML 禁用默认 CNI为 Cilium 让路kind-configure.rst创建集群用kind create cluster拉起 4 节点集群本文核心kind-create-cluster.rst安装 Cilium预加载镜像并通过 Helm 部署kind-preload.rst、k8s-install-download-release.rst验证与连通性测试k8s-install-validate.rst附带的调试器接入、故障排查与 Cluster Mesh 扩展。二、安装依赖开始之前请确保本机已安装以下组件版本要求来自 kind-install-deps.rst组件最低版本用途Dockerstable最新稳定版承载 kind 节点容器kubectl v1.14.0管理 Kubernetes 集群Helm v3.13.0部署 Cilium 及运维组件kind v0.7.0创建本地 Kubernetes 集群kind 的节点以容器方式运行因此 Docker 守护进程必须可用且资源充足。4 节点集群1 control-plane 3 worker对 CPU 与内存有一定要求建议预留至少 4 核 8GB 以上的可用资源。三、配置 kind禁用默认 CNIKind 默认自带一套 CNIkindnetd而我们要用 Cilium 接管集群网络因此必须在创建集群前通过配置关闭默认 CNI。这一步是整条安装链路的前提动作对应 kind-configure.rst。参照仓库根目录下的模板 kind-config.yaml 创建你自己的配置文件kind: 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 节点集群并通过networking.disableDefaultCNI: true关闭内置 CNI后续由 Cilium 完全接管 Pod 网络。3.1 指定 Kubernetes 版本默认情况下kind 使用其发布时所对应的最新 Kubernetes 版本。如需固定某个版本可以在每个节点下显式定义image完整字段说明见 kind 官方的 Node Configuration 文档例如nodes: - role: control-plane image: kindest/node:v1.28.0 - role: worker image: kindest/node:v1.28.03.2 Pod 与 Service 子网冲突处理Kind 默认使用以下子网见 kind-configure.rst 的提示Networking.PodSubnet 10.244.0.0/16 Networking.ServiceSubnet 10.96.0.0/12如果你的本地网络地址段恰好与上述网段冲突部署 Cilium 时会出现连通性问题。此时应在networking段指定不与本机冲突的子网例如networking: disableDefaultCNI: true podSubnet: 10.10.0.0/16 serviceSubnet: 10.11.0.0/16提示由于 kind 节点共享宿主机内核Pod/Service 网段若与宿主机现有网段重叠eBPF 数据路径如 NAT、L3 转发可能将流量错误地路由到本机网络务必在创建集群前确认网段隔离。四、创建 4 节点集群配置就绪后将上面创建的kind-config.yaml通过--config标志传给 kind这是 kind-create-cluster.rst 的核心命令kind create cluster --configkind-config.yaml经过几秒到几分钟的等待一个 4 节点的集群即创建完成。创建成功后kind 会生成名为kind-kind的新 kubectl 上下文并写入KUBECONFIG若未设置则写入${HOME}/.kube/config。验证上下文可用kubectl cluster-info --context kind-kind4.1 关于节点 NotReady 状态的预期节点在 Cilium 部署完成前会一直处于NotReady状态这是预期行为不是故障。因为默认 CNI 已被禁用disableDefaultCNI: true节点上没有任何网络插件为 Pod 分配 IP、配置路由kubelet 的节点就绪检查依赖网络就绪自然无法通过。只有完成下一节的 Cilium 安装后节点才会转为Ready。可用kubectl get nodes随时观察节点状态变化kubectl get nodes NAME STATUS ROLES AGE VERSION kind-control-plane NotReady control-plane 3m12s v1.31.0 kind-worker NotReady none 2m56s v1.31.0 kind-worker2 NotReady none 2m57s v1.31.0 kind-worker3 NotReady none 2m58s v1.31.0五、安装 Cilium5.1 配置 Helm 仓库Cilium 的 Helm 仓库可通过官方地址添加k8s-install-download-release.rsthelm repo add cilium https://helm.cilium.io/Cilium chart 同样发布在 OCI RegistryQuay.io 与 Docker Hub无需额外 setup可直接用oci://URL 安装具体见 k8s-install-helm.rst。5.2 预加载 Cilium 镜像Kind 节点容器并不直接使用宿主机的 Docker 镜像缓存因此需要先拉取 Cilium 镜像再用kind load docker-image注入到每个节点kind-preload.rstdocker pull quay.io/cilium/cilium:版本号 kind load docker-image quay.io/cilium/cilium:版本号其中版本号替换为当前仓库 VERSION 文件对应的版本。这一步可以显著缩短 Pod 启动时间避免安装时逐节点在线拉取镜像。5.3 通过 Helm 部署 Ciliumkind 场景下的标准安装命令对应 kind.rst 中cilium-helm-install指令展开后的 Helm 命令helm install cilium cilium/cilium --namespace kube-system \ --set image.pullPolicyIfNotPresent \ --set ipam.modekubernetes关键参数说明参数取值含义image.pullPolicyIfNotPresent优先使用预加载到 kind 节点内的镜像避免从远端重复拉取ipam.modekubernetes使用 Kubernetes 自身的 IP 分配k8s Pod CIDR作为 IPAM 模式与 kind 的podSubnet配合5.4 关于 Socket LB 与 cgroup v2 的前置要求若要启用 Cilium 的 Socket LB即 Kubernetes 无 kube-proxy 模式见 kind.rst 中的相关说明需要满足以下内核与运行时条件启用 cgroup v2可通过内核参数systemd.unified_cgroup_hierarchy1开启kind 节点运行在独立的 cgroup 命名空间中且该命名空间必须与宿主机不同Cilium 才能在正确的 cgroup 层级挂载 BPF 程序。验证方法是对比三个命名空间 ID$ docker exec kind-control-plane ls -al /proc/self/ns/cgroup lrwxrwxrwx 1 root root 0 Jul 20 19:20 /proc/self/ns/cgroup - cgroup:[4026532461] $ docker exec kind-worker ls -al /proc/self/ns/cgroup lrwxrwxrwx 1 root root 0 Jul 20 19:20 /proc/self/ns/cgroup - cgroup:[4026532543] $ ls -al /proc/self/ns/cgroup lrwxrwxrwx 1 root root 0 Jul 19 09:38 /proc/self/ns/cgroup - cgroup:[4026531835]三个 ID 互不相同即为满足条件。要为容器运行时开启独立的 cgroup 命名空间例如 Docker 需将 dockerd 的--default-cgroupns-mode设为private。cgroup v1 约束Socket LB 正常工作的另一个前提是要么禁用 cgroup v1 的net_cls与net_prio控制器或直接通过内核参数cgroup_no_v1all整体禁用 cgroup v1要么宿主机内核不低于 5.14该版本合入了相关修复。不满足上述条件时kind 上启用 Socket LB 可能遇到 BPF 程序挂载或流量路径异常。六、验证安装安装后进入验证环节官方提供 Cilium CLI 与 kubectl 手工两条路径k8s-install-validate.rst。6.1 方式一使用 Cilium CLI安装 Cilium CLI下载与安装方式见 cli-download.rst然后执行状态检查$ cilium status --wait /¯¯\ /¯¯\__/¯¯\ Cilium: OK \__/¯¯\__/ Operator: OK /¯¯\__/¯¯\ Hubble: disabled \__/¯¯\__/ ClusterMesh: disabled \__/ DaemonSet cilium Desired: 4, Ready: 4/4, Available: 4/4 Deployment cilium-operator Desired: 2, Ready: 2/2, Available: 2/2 Containers: cilium-operator Running: 2 cilium Running: 4 Image versions cilium quay.io/cilium/cilium:版本号: 4 cilium-operator quay.io/cilium/operator-generic:版本号: 2--wait会阻塞直到 Cilium 完全就绪。输出中Cilium: OK、Operator: OK表示核心组件正常DaemonSet 与 Deployment 的 Ready 数量应等于节点数。6.2 方式二使用 kubectl 手工检查监控安装过程中各组件的状态$ kubectl -n kube-system get pods --watch NAME READY STATUS RESTARTS AGE cilium-operator-cb4578bc5-q52qk 0/1 Pending 0 8s cilium-s8w5m 0/1 PodInitializing 0 7s coredns-86c58d9df4-4g7dd 0/1 ContainerCreating 0 8m57s coredns-86c58d9df4-4l6b2 0/1 ContainerCreating 0 8m57s所有组件可能需要几分钟才能完全就绪cilium-operator-cb4578bc5-q52qk 1/1 Running 0 4m13s cilium-s8w5m 1/1 Running 0 4m12s coredns-86c58d9df4-4g7dd 1/1 Running 0 13m coredns-86c58d9df4-4l6b2 1/1 Running 0 13m此时节点应从NotReady转为Ready。七、连通性测试7.1 使用 Cilium CLI 一键测试$ cilium connectivity test ℹ️ Monitor aggregation detected, will skip some flow validation steps ✨ [k8s-cluster] Creating namespace for connectivity check... (...) --------------------------------------------------------------------------------------------------------------------- Test Report --------------------------------------------------------------------------------------------------------------------- ✅ 69/69 tests successful (0 warnings)该命令会在集群中创建临时测试命名空间自动验证 Pod 间、跨节点、Service 负载均衡与网络策略等场景最终输出测试报告。注意如果测试 Pod 因too many open files启动失败需要提高宿主机上的inotify资源限制该问题在 kind 已知问题列表中已有说明可参考 kind 官方文档相关章节。7.2 使用手工 connectivity-check 清单你也可以使用仓库中维护的 connectivity-check 资源集定义与生成方式见 examples/kubernetes/connectivity-check/README.mdkubectl create ns cilium-test kubectl apply -n cilium-test -f examples/kubernetes/connectivity-check/connectivity-check.yaml它会部署一系列 Deployment覆盖有无 Service 负载均衡、各种网络策略组合的连通路径。Pod 名称标识连通性变体readiness/liveness 探针状态即代表测试成败$ kubectl get pods -n cilium-test NAME READY STATUS RESTARTS AGE echo-a-76c5d9bd76-q8d99 1/1 Running 0 66s echo-b-795c4b4f76-9wrrx 1/1 Running 0 66s echo-b-host-6b7fc94b7c-xtsff 1/1 Running 0 66s host-to-b-multi-node-clusterip-85476cd779-bpg4b 1/1 Running 0 66s host-to-b-multi-node-headless-dc6c44cb5-8jdz8 1/1 Running 0 65s pod-to-a-79546bc469-rl2qq 1/1 Running 0 66s pod-to-a-allowed-cnp-58b7f7fb8f-lkq7p 1/1 Running 0 66s pod-to-a-denied-cnp-6967cb6f7f-7h9fn 1/1 Running 0 66s pod-to-b-intra-node-nodeport-9b487cf89-6ptrt 1/1 Running 0 65s pod-to-b-multi-node-clusterip-7db5dfdcf7-jkjpw 1/1 Running 0 66s pod-to-b-multi-node-headless-7d44b85d69-mtscc 1/1 Running 0 66s pod-to-b-multi-node-nodeport-7ffc76db7c-rrw82 1/1 Running 0 65s pod-to-external-1111-d56f47579-d79dz 1/1 Running 0 66s pod-to-external-fqdn-allow-google-cnp-78986f4bcf-btjn7 1/1 Running 0 66s全部Running/1/1即表示各连通路径通过。注意如果在单节点集群上部署该测试涉及多节点的 Pod 会停留在Pending状态——这是预期行为因为这类 Pod 至少需要 2 个节点才能被调度。测试完成后清理命名空间kubectl delete ns cilium-test7.3 connectivity-check 的仓库内实现仓库中的 connectivity-check 资源集用 CUE 语言编写examples/kubernetes/connectivity-check/README.md定义按职责拆分为多个文件resources.cue所有 Kubernetes 资源Deployment、Service、CiliumNetworkPolicy的主模板定义echo-servers.cue各echo-*服务端的数据定义defaults.cue默认参数探针目标选择、Pod 亲和性、默认镜像network.cue、policy.cue、proxy.cue、services.cue不同网络层、不同特性的检查定义其中 L7 策略检查位于proxy.cue*_tool.cue用于列出与生成 YAML 的 CLI 工具。目录下还提供make help、cue ls、cue dump等命令可按组件、拓扑、流量类型等维度过滤并重新生成 YAML 清单例如connectivity-check-internal.yaml用于仅内部流量场景被用于 kind IPv6 集群的 GitHub Action 一致性测试。八、故障排查8.1 无法连接 k8s api-server若 Cilium agent 日志相关日志查看指引见 k8s-install-validate.rst 上下文中出现如下内容levelinfo msgEstablishing connection to apiserver hosthttps://10.96.0.1:443 subsysk8s 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 ipAddrhttps://10.96.0.1:443 subsysk8s levelfatal msgUnable to initialize Kubernetes subsystem errorunable to create k8s client: unable to create k8s client: Get https://10.96.0.1:443/api/v1/namespaces/kube-system: dial tcp 10.96.0.1:443: connect: no route to host subsysdaemon原因分析kind 节点作为 Docker 容器运行与宿主机共享内核。如果之前启用过 Socket LB 而未正确关闭Cilium 此前挂载的 eBPF 程序可能已过时不再把 api-server 请求路由到当前kind-control-plane容器。解决办法重建 kind 集群并用 kind.rst 中给出的 Helm 命令重新安装 Cilium即可脱离过时的 eBPF 程序。8.2 Cilium agent Pod 持续崩溃如果 Cilium agent Pod 崩溃且日志中出现如下 BPF 挂载失败信息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 levelwarning msg RETCODE255 subsysdatapath-loader可能的原因你在一个Cilium 已经在运行的环境中部署 kind 集群例如 Cilium 开发虚拟机或者有其它重叠的 BPF cgroup 类型程序挂载在 kind 容器节点的父 cgroup 层级上。处理方式要么先拆除环境中已运行的 Cilium要么手动摘除父 cgroup 层级中重叠的 BPF cgroup 程序可按 bpftool cgroup 相关文档操作。九、进阶用 Kind 模拟 Cluster Mesh 多集群沙箱Kind 的本地多集群能力还可以用来模拟 Cilium Cluster Mesh 跨集群互联场景见 kind.rst 的 Cluster Mesh 章节。9.1 双集群配置为两个集群各准备一份config.yaml并显式配置互不重叠的pod-network-cidr与service-cidr。kind-cluster1.yamlkind: Cluster apiVersion: kind.x-k8s.io/v1alpha4 nodes: - role: control-plane - role: worker - role: worker - role: worker networking: disableDefaultCNI: true podSubnet: 10.0.0.0/16 serviceSubnet: 10.1.0.0/16kind-cluster2.yamlkind: Cluster apiVersion: kind.x-k8s.io/v1alpha4 nodes: - role: control-plane - role: worker - role: worker - role: worker networking: disableDefaultCNI: true podSubnet: 10.2.0.0/16 serviceSubnet: 10.3.0.0/169.2 创建两个集群并接入 Cluster Meshkind create cluster --namecluster1 --configkind-cluster1.yaml kind create cluster --namecluster2 --configkind-cluster2.yaml在两个集群中分别部署 Cilium 后按照 Cluster Mesh 指南完成互联配置相关指引见仓库的 clustermesh 文档。对于 Kind 环境需要将NodePort类型的 Service 部署到kube-system命名空间以便集群间通过节点端口交换 kvstore 与 API 访问信息。十、附加能力与后续方向调试器支持仓库的 Kind 配置默认在 agent 与 operator Pod 内开放 Delve 调试服务器可接入调试器进行源码级调试可观测性安装完成后可进一步启用 Hubble可观测性组件并配置 Hubble CLI / UI多集群参考 Cluster Mesh 指南将上述沙箱扩展为真实的多集群互通环境。上述进阶方向在仓库文档中均有对应入口可参考 Documentation/installation/kind.rst 的 Next Steps 章节逐一展开。小结本文以 kind-create-cluster.rst 为核心完整串联了 Kind 上运行 Cilium 的全流程先通过kind-config.yaml禁用默认 CNI再用kind create cluster --configkind-config.yaml创建 4 节点集群期间节点保持NotReady属预期随后预加载镜像、以 Helm 部署 Cilium并依次通过cilium status、cilium connectivity test与手工 connectivity-check 验证最后给出 api-server 失联与 agent 崩溃两类典型问题的根因与解法。掌握这套流程后你可以在任意本地 Docker 主机上快速搭建一个可用于开发、测试与演示的 Cilium 多节点环境。【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考