Cilium 1.20 部署指南：在 k3s 上安装与验证

目标：在一台 Ubuntu 22.04 服务器上，为 k3s 单节点集群从零安装 Cilium 1.20.4 作为 CNI，并完成状态验证、组件验证与连通性验证。全文命令与回显均来自本系列实测环境逐行照抄；选型与兼容矩阵依据见《Cilium 1.20 介绍与选型指南》。

一、环境信息

服务器：Ubuntu 22.04.4 LTS，内核 6.8.0-138-generic（amd64）
Kubernetes：k3s v1.36.5+k3s1，单节点 k3s-server（control-plane），节点 IP 10.89.69.10，API 端口 6443
Cilium：v1.20.4（helm chart cilium-1.20.4，部署在 kube-system）
客户端工具：cilium CLI v0.20.1、hubble CLI v1.20.2、helm、kubectl（k3s 内置）
网络形态：IPAM cluster-pool（/24 掩码）、VXLAN 隧道、kubeProxyReplacement=true、Hubble Relay 启用

二、版本选型

组件	版本	说明
k3s	v1.36.5+k3s1	对应上游 Kubernetes 1.36，落在 Cilium 1.20 兼容矩阵（1.33–1.36）内
Cilium	v1.20.4	1.20 维护线当前 patch，最新稳定
cilium CLI	v0.20.1	与 Cilium 1.20 系列配套的客户端工具
hubble CLI	v1.20.2	Hubble 观测客户端，与 1.20 系列配套

Cilium 1.20 的完整兼容矩阵与三条维护线（1.20.x / 1.19.x / 1.18.x）见选型篇，安装前先核对集群版本是否在 1.33–1.36 区间。

三、前置条件：k3s 安装并禁用内置网络组件

3.1 为什么必须先禁用

k3s 默认内置 Flannel（CNI）与内置的 NetworkPolicy 控制器。Cilium 接管网络前必须把它们关掉，否则两套数据面会同时抢网卡、抢策略执行点。k3s 提供两个启动参数：

--flannel-backend=none：不安装内置 Flannel，CNI 位置留给 Cilium；
--disable-network-policy：不启用 k3s 内置策略控制器，策略统一交给 Cilium。

3.2 安装 k3s

curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.36.5+k3s1 sh -s - server \
  --node-name=k3s-server \
  --node-ip=10.89.69.10 \
  --advertise-address=10.89.69.10 \
  --disable=traefik,servicelb,metrics-server \
  --flannel-backend=none \
  --disable-network-policy \
  --write-kubeconfig-mode=644 \
  --tls-san=10.89.69.10 \
  --tls-san=127.0.0.1

说明：

--disable=traefik,servicelb,metrics-server：本系列为聚焦网络组件，关闭了这三项可选组件，按需增减；
--write-kubeconfig-mode=644：kubeconfig 可读，便于本机直接使用；
节点 IP 按服务器实际内网 IP 调整。

安装完成后导出 kubeconfig 并确认节点就绪：

export KUBECONFIG=/etc/rancher/k3s/server/k3s.yaml
kubectl get nodes -o wide

实测输出（节点处于 Ready、运行时为 containerd）：

NAME         STATUS   ROLES           AGE   VERSION        INTERNAL-IP   EXTERNAL-IP   OS-IMAGE           KERNEL-VERSION              CONTAINER-RUNTIME
k3s-server   Ready    control-plane   83m   v1.36.5+k3s1   10.89.69.10   <none>        K3s v1.36.5+k3s1   6.8.0-138-generic (amd64)   containerd://2.3.4-k3s1.36

⚠️ 注意：此时集群还没有 CNI，新调度的 Pod（除 hostNetwork）会停留在 Pending，kubectl get nodes 显示 Ready 但网络不可用，属于正常现象，装完 Cilium 即恢复。

四、安装 cilium CLI 与 hubble CLI

4.1 安装 cilium CLI

官方发布件下载、解压、放入 PATH（版本 v0.20.1，2026-10-24 实查为 cilium-cli 最新 release）：

curl -LO https://github.com/cilium/cilium-cli/releases/download/v0.20.1/cilium-linux-amd64.tar.gz
tar xzvf cilium-linux-amd64.tar.gz
sudo mv cilium /usr/local/bin/cilium
sudo chmod +x /usr/local/bin/cilium

验证版本：

cilium version

实测输出（running 一行在 Cilium 未安装前会提示集群版本未知，安装完成后显示实际版本）：

cilium-cli: v0.20.1 compiled with go1.27.1 on linux/amd64
cilium image (default): v1.20.1
cilium image (stable): v1.20.4
cilium image (running): 1.20.4

💡 说明：default 是 CLI 内置默认版本（对应当前 CLI 发布时点），stable 是 CLI 检测到的当前稳定版。本系列按 stable 实测的 v1.20.4 安装，与 CLI 的 --version 显式指定一致。

4.2 安装 hubble CLI

Hubble 的流观测命令行（版本 v1.20.2，实测下载件约 21 MB）：

curl -LO https://github.com/cilium/hubble/releases/download/v1.20.2/hubble-linux-amd64.tar.gz
tar xzvf hubble-linux-amd64.tar.gz
sudo mv hubble /usr/local/bin/hubble
sudo chmod +x /usr/local/bin/hubble

验证版本：

hubble version

实测输出：

hubble v1.20.2@HEAD-90adec1 compiled with go1.27.1 on linux/amd64

五、安装 Cilium 1.20.4（cilium CLI 主线）

5.1 执行安装

cilium CLI 底层通过 helm 完成部署，一条命令搞定版本、连通参数与 Hubble 组件。以下参数与实测环境的最终 release 值完全一致（逐项对应第六节 helm get values 回显）：

export KUBECONFIG=/etc/rancher/k3s/server/k3s.yaml

cilium install --version 1.20.4 \
  --set kubeProxyReplacement=true \
  --set k8sServiceHost=10.89.69.10 \
  --set k8sServicePort=6443 \
  --set ipam.operator.clusterPoolIPv4PodCIDRList=10.200.0.0/16 \
  --set hubble.relay.enabled=true \
  --set operator.replicas=1 \
  --set routingMode=tunnel \
  --set tunnelProtocol=vxlan

参数说明：

kubeProxyReplacement=true：启用 eBPF 数据面替代 kube-proxy；
k8sServiceHost / k8sServicePort：API server 地址端口（不指定时 CLI 会自动探测，k3s 环境通常能识别）；
ipam.operator.clusterPoolIPv4PodCIDRList：集群 Pod 网段，按集群规划调整，节点从池中按 /24 掩码分片；
hubble.relay.enabled=true：部署 hubble-relay，供 hubble CLI 跨节点读流日志；
routingMode=tunnel + tunnelProtocol=vxlan：跨节点用 VXLAN 隧道组网（单节点集群同样适用，扩展节点时无需改配置）。

实测输出（照抄）：

ℹ️  Using Cilium version 1.20.4
🔮 Auto-detected cluster name: default
🔮 Auto-detected kube-proxy has not been installed
ℹ️  Cilium will fully replace all functionalities of kube-proxy

回显解读：

Using Cilium version 1.20.4：确认安装版本；
Auto-detected cluster name: default：集群名；
kube-proxy has not been installed + will fully replace all functionalities of kube-proxy：本环境 k3s 以 kubeProxyReplacement=true 部署，Cilium 全面接管 Service 转发与 NodePort。

5.2 等待就绪

cilium status --wait

--wait 会阻塞直到各组件全部就绪；单节点 k3s 上全组件就绪通常在 1–2 分钟内。也可以不加 --wait 随时查看进度，就绪后的完整状态见下一节。

六、安装验证（实测回显）

6.1 组件状态：cilium status

cilium status --wait=false

实测输出（逐行照抄）：

    /¯¯\
 /¯¯\__/¯¯\    Cilium:             OK
 \__/¯¯\__/    Operator:           OK
 /¯¯\__/¯¯\    Envoy DaemonSet:    OK
 \__/¯¯\__/    Hubble Relay:       OK
    \__/       ClusterMesh:        disabled

DaemonSet              cilium                   Desired: 1, Ready: 1/1, Available: 1/1
DaemonSet              cilium-envoy             Desired: 1, Ready: 1/1, Available: 1/1
Deployment             cilium-operator          Desired: 1, Ready: 1/1, Available: 1/1
Deployment             hubble-relay             Desired: 1, Ready: 1/1, Available: 1/1
Containers:            cilium                   Running: 1
                       cilium-envoy             Running: 1
                       cilium-operator          Running: 1
                       clustermesh-apiserver
                       hubble-relay             Running: 1
Cluster Pods:          17/17 managed by Cilium
Helm chart version:    1.20.4
Image versions         cilium             quay.io/cilium/cilium:v1.20.4@sha256:20fe92e4c86641233a450098c158d2d29085f3419931ab6bf681d2485dedf16e: 1
                       cilium-envoy       quay.io/cilium/cilium-envoy:v1.39.5-1792733054-8c73b2816bc8239e27f1fd53b271884688137459@sha256:547ab45f6092f681d9f54f3be9fa8fb1e705c9c5dc2df388efe3a52aa6965629: 1
                       cilium-operator    quay.io/cilium/operator-generic:v1.20.4@sha256:7a7a3489dc66ad67e420d285c8a8d2e169b0957ad15e120f593d27081bf38d82: 1
                       hubble-relay       quay.io/cilium/hubble-relay:v1.20.4@sha256:cb23408209697ed30d2bc462e1f01eb622ea4423a891458f78bc88d7255bbfc1: 1

要点：

五个组件全部 OK（ClusterMesh 未启用属正常，未配多集群）；
Cluster Pods: 17/17 managed by Cilium：集群内全部 Pod 已由 Cilium 托管网络；
Helm chart version: 1.20.4：release 使用的 chart 版本。

6.2 helm release 状态

helm list -A

实测输出：

NAME    NAMESPACE       REVISION        UPDATED                                 STATUS          CHART           APP VERSION
cilium  kube-system     1               2026-10-24 02:55:34.029993547 +0800 CST deployed        cilium-1.20.4   1.20.4

6.3 实际生效的安装参数

helm get values cilium -n kube-system

实测输出（USER-SUPPLIED VALUES 即安装时显式传入的参数，与 5.1 的 --set 列表一一对应）：

USER-SUPPLIED VALUES:
cluster:
  name: default
hubble:
  relay:
    enabled: true
ipam:
  operator:
    clusterPoolIPv4PodCIDRList: 10.200.0.0/16
k8sServiceHost: 10.89.69.10
k8sServicePort: 6443
kubeProxyReplacement: true
operator:
  replicas: 1
routingMode: tunnel
tunnelProtocol: vxlan

6.4 组件运行视图：kube-system 下的 Pod

kubectl get pods -n kube-system -o wide

实测输出：

NAME                                      READY   STATUS    RESTARTS      AGE   IP            NODE         NOMINATED NODE   READINESS GATES
cilium-envoy-rzckl                        1/1     Running   0             81m   10.89.69.10   k3s-server   <none>           <none>
cilium-fqphz                              1/1     Running   0             81m   10.89.69.10   k3s-server   <none>           <none>
cilium-operator-55bdbc97d-6r9jv           1/1     Running   1 (12m ago)   81m   10.89.69.10   k3s-server   <none>           <none>
coredns-7cfb7bc9c7-z79x9                  1/1     Running   0             89m   10.0.0.145    k3s-server   <none>           <none>
hubble-relay-7b9cc7bdd5-vtbp6             1/1     Running   0             81m   10.0.0.194    k3s-server   <none>           <none>
local-path-provisioner-77b9867795-sqs8l   1/1     Running   0             89m   10.0.0.8      k3s-server   <none>           <none>

要点：cilium/cilium-envoy 两个 DaemonSet Pod 使用节点 IP 10.89.69.10（hostNetwork 形态），其余工作负载 Pod 已从 Cilium 地址池获得 IP（10.0.0.x 段）。

6.5 IPAM 分配视图：CiliumNode 与 CiliumEndpoint

Cilium 以 CRD 记录节点与端点的地址分配：

kubectl get ciliumnodes
kubectl get ciliumendpoints -A -o custom-columns='NS:.metadata.namespace,POD:.metadata.name,IP:.status.networking.addressing[*].ipv4'

实测输出（节点持有 /24 分片，端点 IP 落在该分片内）：

NAME         CILIUMINTERNALIP   INTERNALIP    AGE
k3s-server   10.0.0.250         10.89.69.10   82m

NS                  POD                                       IP
cilium-test-1       client-657b75749d-9hr6f                   10.0.0.251
cilium-test-1       client2-78bbbfb455-pfflt                  10.0.0.246
cilium-test-1       echo-same-node-55ddf564bd-zfc85           10.0.0.147
cilium-test-1       l7-lb-7ddb9855ff-pg7xt                    10.0.0.195
cilium-test-2       client-657b75749d-d2gwz                   10.0.0.29
cilium-test-2       client2-78bbbfb455-7lshp                  10.0.0.120
cilium-test-2       echo-same-node-8468d66595-gmv68           10.0.0.217
cilium-test-2       l7-lb-7ddb9855ff-vhdzh                    10.0.0.164
cilium-test-3       client-657b75749d-h4fgb                   10.0.0.226
cilium-test-3       client2-78bbbfb455-z7fj9                  10.0.0.69
cilium-test-3       echo-same-node-85d9547c4b-26lhz           10.0.0.81

💡 说明：CiliumEndpoint 是 Cilium 为每个被托管 Pod 维护的端点对象（含安全身份与地址）；上表的 cilium-test-* 命名空间是第七节连通性测试创建的。

七、连通性验证

7.1 cilium connectivity test

cilium connectivity test 会自动创建测试命名空间、部署 client/echo 测试负载，按官方矩阵执行 70+ 项连通动作（Pod 间、Service、DNS、NetworkPolicy L3/L4/L7 等）并输出汇总：

export KUBECONFIG=/etc/rancher/k3s/server/k3s.yaml
cilium connectivity test

本系列环境的实测结论：

内网连通、Service、DNS、NetworkPolicy 相关测试全部通过；
失败项均为 pod-to-world 外网访问类（访问 one.one.one.one.:443 / 1.1.1.1:443）；
跳过项均为需要第二个节点的跨节点场景（本环境为单节点）。

汇总与失败原因实测回显（照抄）：

❌ 2/22 tests failed (4/73 actions), 12 tests skipped, 0 scenarios skipped:

  curl: (28) Failed to connect to one.one.one.one. port 443 after 2002 ms: Timeout was reached
  curl: (28) Failed to connect to 1.1.1.1 port 443 after 2001 ms: Timeout was reached

⚠️ 解读：curl (28) 是连接超时——本测试环境服务器无直连外网出口，Pod 访问公网目标必然超时，这不是 Cilium 数据面故障。判定方法：同一 namespace 内 Pod 访问 Service 的测试项全部通过、cilium status 全绿，即可确认数据面健康；外网项请在有公网出口的环境中复测。

7.2 测试后的清理

connectivity test 默认会自动清理测试命名空间；若中途中断可手动清理：

cilium connectivity test --force-deploy

重新部署测试负载并再次执行；彻底清理：

kubectl delete ns cilium-test --ignore-not-found

八、备用方案：Helm 安装

cilium CLI 的 install 等价于对官方 chart 执行 helm install。习惯 helm 工作流（或需要在 values 文件里长期管理配置）时可用以下方式，参数与 5.1 完全一致：

export KUBECONFIG=/etc/rancher/k3s/server/k3s.yaml

helm repo add cilium https://helm.cilium.io/
helm repo update

helm install cilium cilium/cilium \
  --version 1.20.4 \
  --namespace kube-system \
  --set kubeProxyReplacement=true \
  --set k8sServiceHost=10.89.69.10 \
  --set k8sServicePort=6443 \
  --set ipam.operator.clusterPoolIPv4PodCIDRList=10.200.0.0/16 \
  --set hubble.relay.enabled=true \
  --set operator.replicas=1 \
  --set routingMode=tunnel \
  --set tunnelProtocol=vxlan

安装后验证命令相同：helm list -A、cilium status、kubectl get pods -n kube-system。两种方式二选一，不要叠加使用；后续升级统一用同一种工具操作。

九、升级与卸载

9.1 升级

cilium CLI 方式：

cilium upgrade --version <目标版本号>

helm 方式（先 helm repo update 再 upgrade）：

helm upgrade cilium cilium/cilium -n kube-system --reuse-values --version <目标版本号>

⚠️ 升级前务必阅读官方 Upgrade Guide 中对应版本的 breaking changes；Cilium 约每 6 个月一个 minor，1.19.x 与 1.18.x 为仍在维护的旧线，跨多个 minor 升级需逐版推进。

9.2 卸载

cilium CLI 方式：

cilium uninstall

helm 方式：

helm uninstall cilium -n kube-system

卸载会移除 Cilium 的 DaemonSet/Deployment 与 CR 资源。若 k3s 已按 3.1 节参数禁用了 Flannel，卸载后集群将没有 CNI，需要先重新启用 k3s 内置网络再执行卸载，避免 Pod 网络长时间不可用。

十、常见问题（含实测排障）

10.1 kubectl 报 localhost:8080 connection refused

现象（实测回显）：

E1023 20:10:15.174877   22158 memcache.go:265] "Unhandled Error" err="couldn't get current server API group list: Get \"http://localhost:8080/api?timeout=32s\": dial tcp [::1]:8080: connect: connection refused"
E1023 20:10:15.179417   22158 memcache.go:265] "Unhandled Error" err="couldn't get current server API group list: Get \"http://localhost:8080/api?timeout=32s\": dial tcp [::1]:8080: connect: connection refused"
The connection to the server localhost:8080 was refused - did you specify the right host or port?

原因：KUBECONFIG 未导出，kubectl/cilium CLI 找不到集群配置，退回默认 http://localhost:8080。解决：

export KUBECONFIG=/etc/rancher/k3s/server/k3s.yaml

cilium CLI 同样读取该环境变量，建议把导出语句写入 ~/.bashrc。

10.2 connectivity test 的外网测试项失败

见 7.1 的 ⚠️ 解读：环境无公网出口时 pod-to-world 类测试必然超时（curl (28)），不影响内网数据面健康判定；有外网的环境中此类项应全部通过。

10.3 大量测试被 skip

单节点集群没有第二个节点，connectivity test 会跳过所有跨节点场景（本次实测跳过 12 项）。这不是故障；需要完整验证时扩容为两节点集群再跑。

10.4 忘记禁用 Flannel 就装了 Cilium

两套 CNI 并存会导致路由冲突、策略双重执行，表现为 Pod 间偶发不通或策略行为异常。处理：按 3.1 节参数重新部署 k3s（或在 k3s systemd 配置中补齐 --flannel-backend=none --disable-network-policy 后重启 k3s），再安装 Cilium。

十一、参考链接

Cilium Quick Installation：https://docs.cilium.io/en/stable/gettingstarted/k8s-install-default/
Installation using Helm：https://docs.cilium.io/en/stable/installation/k8s-install-helm/
Installation with K8s distributions（k3s 等）：https://docs.cilium.io/en/stable/installation/k8s-distributions/
cilium-cli 发布页：https://github.com/cilium/cilium-cli/releases
hubble 发布页：https://github.com/cilium/hubble/releases

本系列导航

上一篇：《Cilium 1.20 介绍与选型指南》——定位、eBPF 架构与 Calico/Flannel 量化对比
本篇：Cilium 1.20 部署指南：在 k3s 上安装与验证
《Cilium 1.20 配置参数详解》——helm values 核心项与运行时配置
《Cilium 1.20 CLI 命令详解：cilium 与 hubble》——本篇工具的完整命令实战