在 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），僅供參考