在 Rancher Desktop 中禁用默认 CNI 并安装 Cilium 的完整配置指南

在 Rancher Desktop 中禁用默认 CNI 并安装 Cilium 的完整配置指南

【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium

本文是一份基于 Cilium 官方安装文档整理的实战指南，聚焦如何在 Rancher Desktop（macOS / Linux 桌面环境）上通过一个 YAML 覆盖配置文件，彻底禁用其内置的 flannel CNI 与网络策略组件，并为 eBPF 数据面预挂载 bpffs 与 cgroup v2 文件系统，从而为安装 Cilium 铺平道路。读完本文，你将掌握 Rancher Desktop 与 Cilium 集成的标准步骤：编写override.yaml、放置到 Lima 配置目录、执行 Kubernetes 重置，以及通过cilium install、cilium status和cilium connectivity test完成安装与验证。

为什么需要配置 Rancher Desktop 才能安装 Cilium

Rancher Desktop 是一款面向 Mac、Windows 和 Linux 的开源桌面应用，它在本地以轻量虚拟机的方式运行 Kubernetes。其底层托管发行版基于k3s，容器运行时使用containerd。默认情况下，k3s 会随集群启动自带的flannel CNI以及内置的 Network Policy Controller，而 Cilium 作为独立的 CNI 插件必须独占数据面：

• 两个 CNI 插件同时存在会导致 Pod 网络配置冲突，节点上的 Pod 可能被重复配置或绑定错误的网络设备；
• k3s 内置的网络策略控制器会与 Cilium 的 NetworkPolicy 实现（基于 eBPF 的pkg/policy模块）产生职责重叠，行为不可预期。

因此，官方安装流程的第一步就是在启动 Rancher Desktop 之前，通过 YAML 配置文件（override.yaml）改写 k3s 的启动参数并注入预挂载脚本，关闭 flannel 与内置网络策略，这正是本指南要完成的核心配置工作。

认识 override.yaml：Rancher Desktop 的启动覆盖机制

Rancher Desktop 依赖 Lima（Linux 虚拟机管理工具）来创建和管理其虚拟机。Lima 支持通过覆盖配置（override configuration）的方式，在虚拟机启动阶段注入自定义的env、provision等指令。官方为 Cilium 准备了一份现成的覆盖配置，位于仓库的 Documentation/installation/rancher-desktop-override.yaml，完整内容如下：

env: # needed for cilium INSTALL_K3S_EXEC: '--flannel-backend=none --disable-network-policy' provision: # needs root to mount - mode: system script: | #!/bin/sh set -e # needed for cilium mount bpffs -t bpf /sys/fs/bpf mount --make-shared /sys/fs/bpf mkdir -p /run/cilium/cgroupv2 mount -t cgroup2 none /run/cilium/cgroupv2 mount --make-shared /run/cilium/cgroupv2/

这份配置虽短，却包含了两个对 Cilium 至关重要的部分：k3s 启动参数改写与 eBPF 相关文件系统的挂载。

env.INSTALL_K3S_EXEC：关闭 flannel 与内置网络策略

env: INSTALL_K3S_EXEC: '--flannel-backend=none --disable-network-policy'

INSTALL_K3S_EXEC是 k3s 安装脚本的标准环境变量，用于向 k3s 传递额外的启动参数：

• --flannel-backend=none：指示 k3s 不部署 flannel 作为 CNI 后端。Cilium 安装完成后将接管 CNI 配置，成为集群唯一的网络插件；
• --disable-network-policy：禁用 k3s 自带的 Network Policy Controller，将网络策略的执行权完整交给 Cilium 的 eBPF 策略引擎。

这两项缺一不可。忽略其中任何一项，都会导致 Cilium 与 flannel/内置策略控制器并存，出现网络栈互相覆盖的问题。

provision.script：预挂载 bpffs 与 cgroup v2

Cilium 的数据面完全构建在 eBPF 之上，运行时有三个硬性前提：

1. BPF 文件系统（bpffs）：Cilium 将各类 eBPF Map 与程序以 pin 的方式持久化在/sys/fs/bpf下，例如tc/globals目录中的全局 Map（对应源码 pkg/bpf/bpffs_linux.go 中TCGlobalsPath()返回的<bpffs>/tc/globals路径）。只有 bpffs 被正确挂载，Agent 重启后 eBPF 状态才能无缝衔接；
2. 共享挂载传播（shared mount propagation）：mount --make-shared让/sys/fs/bpf的挂载事件可以在虚拟机各命名空间之间传播，确保容器内的 Cilium Agent 也能看到宿主侧的挂载点；
3. cgroup v2 文件系统：Cilium 依赖 cgroup v2 实现 Pod 级带宽管理、socket 负载均衡、以及基于 cgroup 的流量策略。官方约定的挂载路径是/run/cilium/cgroupv2，这与源码 pkg/cgroups/cgroups_linux.go 中 Cilium Agent 查找 cgroup 根路径的逻辑保持一致。

#!/bin/sh set -e mount bpffs -t bpf /sys/fs/bpf mount --make-shared /sys/fs/bpf mkdir -p /run/cilium/cgroupv2 mount -t cgroup2 none /run/cilium/cgroupv2 mount --make-shared /run/cilium/cgroupv2/

这段脚本的逻辑要点：

• set -e：任一挂载命令失败立即中止整个 provision 脚本，避免虚拟机在文件系统未就绪的状态下继续启动；
• 先创建目录再挂载，保证挂载目标存在；
• bpffs 挂载类型为bpf，cgroup v2 挂载类型为cgroup2；
• 两个挂载点都执行mount --make-shared，这是 Rancher Desktop/Lima 虚拟机环境中 Cilium Agent 以容器形态访问这些挂载点的关键前提。

提示：provision段标注了mode: system，因为挂载文件系统需要 root 权限，该模式会在虚拟机的 system 阶段以 root 身份执行脚本。

放置 override.yaml 到 Rancher Desktop 的 Lima 配置目录

创建好上述override.yaml后，需要将其放入 Rancher Desktop 的lima/_config目录。不同操作系统路径不同：

Linux：

cp override.yaml ~/.local/share/rancher-desktop/lima/_config/override.yaml

macOS：

cp override.yaml ~/Library/Application\ Support/rancher-desktop/lima/_config/override.yaml

macOS 路径中的Application Support含空格，复制命令中需使用反斜杠转义（如上所示），或为整个路径加引号。

通过 "Reset Kubernetes" 让配置生效

文件放置完成后，打开 Rancher Desktop 的图形界面，进入Troubleshooting（故障排查）面板，点击"Reset Kubernetes"（重置 Kubernetes）按钮。

这一步的作用是销毁并重新创建本地的 k3s 集群。只有经历完整的重建流程，override.yaml中的INSTALL_K3S_EXEC参数和 provision 挂载脚本才会被重新应用到新的虚拟机/集群实例。等待数分钟，Rancher Desktop 会重新启动，此时集群已经处于"待安装 Cilium"的就绪状态——flannel 已停用、内置网络策略已关闭、bpffs 与 cgroup v2 已就位。

安装 Cilium CLI

验证与安装 Cilium 需要用到 Cilium 官方命令行工具。Cilium CLI 的源码位于仓库的 cilium-cli 目录，其功能涵盖：

• 安装 Cilium 及可选组件（Hubble、ClusterMesh 等）；
• 检查已安装集群的运行状态；
• 执行集群网络连通性测试；
• 生成系统诊断信息（sysdump）。

官方推荐的方式是从 cilium-cli 项目的发布渠道下载与当前平台、CPU 架构（amd64/arm64）匹配的二进制包，解压到/usr/local/bin（Linux）或相应目录（macOS）后即可使用。若你希望使用主分支上的最新 Helm Chart 进行安装，也可以先git clone本仓库，再在仓库根目录执行 Cilium CLI 的相关命令，使其直接读取主分支尚未发布的 Helm Chart。

安装 Cilium

运行以下命令将 Cilium 安装进 Rancher Desktop 管理的 k3s 集群：

cilium install

Cilium CLI 会读取当前 kubeconfig 上下文中的集群，自动检测集群类型并应用合理的默认配置（如自动探测 Pod CIDR、Service CIDR，选择匹配的 IPAM 模式等）。官方文档中使用的形式为cilium install --version |CHART_VERSION|，其中CHART_VERSION是文档构建时注入的版本号占位符——在实际操作中，如果你需要固定某个版本，可以显式传入--version参数，例如：

cilium install --version v1.16.0

不指定--version时则安装 Cilium CLI 内置默认的稳定版本。

验证安装

检查集群状态

$ cilium status --wait /¯¯\ /¯¯\__/¯¯\ Cilium: OK \__/¯¯\__/ Operator: OK /¯¯\__/¯¯\ Hubble: disabled \__/¯¯\__/ ClusterMesh: disabled \__/ DaemonSet cilium Desired: 2, Ready: 2/2, Available: 2/2 Deployment cilium-operator Desired: 2, Ready: 2/2, Available: 2/2 Containers: cilium-operator Running: 2 cilium Running: 2 Image versions cilium quay.io/cilium/cilium:v1.9.5: 2 cilium-operator quay.io/cilium/operator-generic:v1.9.5: 2

cilium status --wait会持续等待直到 Cilium 完全就绪：

• Cilium / Operator显示OK，说明 Agent 与 Operator 组件健康；
• Hubble与ClusterMesh显示disabled属于正常现象，它们是可选组件，默认不启用；
• DaemonSet cilium与Deployment cilium-operator的 Desired/Ready 数值一致，表示每个节点上的 Agent 和 Operator 副本都已正常运行。

运行连通性测试

$ 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)

cilium connectivity test会在集群中临时创建测试命名空间与一组测试 Pod，自动执行 Pod 到 Pod、Pod 到 Service、DNS 解析、南北向流量等多项网络场景验证，最终输出测试报告。当所有用例全部通过（如示例中的69/69 tests successful），即证明 Cilium 数据面在 Rancher Desktop 集群中工作正常。

注意：连通性测试偶尔会因为宿主机inotify资源限制（文件描述符过多）导致测试 Pod 部署失败。若遇到too many open files类错误，需要在宿主机上提高 inotify 资源上限后重试。

后续可选的扩展方向

Cilium 安装并验证通过后，可以继续探索官方推荐的进阶功能（对应文档 Documentation/installation/next-steps.rst）：

• Hubble：启用可观测性组件，获得基于 eBPF 的流量可视化与服务依赖图（命令行工具hubble与 Web UIhubble-ui）；
• L7 HTTP 策略：通过 CiliumNetworkPolicy 体验七层协议感知的安全策略（示例见仓库 examples/policies）；
• ClusterMesh：将多个本地或远程集群组成网状互联，实现跨集群 Service 与策略共享。

小结

在 Rancher Desktop 上运行 Cilium 的关键在于启动前完成三层准备：一是用INSTALL_K3S_EXEC参数关闭 flannel 与 k3s 内置网络策略，把 CNI 与策略执行权完整让渡给 Cilium；二是通过 Lima 的 provision 脚本在虚拟机内挂载 bpffs 与 cgroup v2 并开启共享传播，满足 eBPF 数据面的运行前提；三是执行 "Reset Kubernetes" 让覆盖配置真正生效。之后即可通过 Cilium CLI 完成安装、状态检查与连通性验证，获得一套在本地桌面即可体验的 eBPF 网络、安全与可观测性集群。

【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium