企业官网建设流程全解析

Cilium CLIcilium upgrade完全指南：基于 Helm 的无缝升级、参数详解与源码级工作原理

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

cilium upgrade是 Cilium 官方 CLI（cilium-cli）提供的升级命令，负责通过 Helm 在 Kubernetes 集群中就地升级已有的 Cilium 安装，实现版本更新、配置调整与多集群参数设置。本文以 cilium_upgrade.md 的命令参考文档为主线，结合仓库内 CLI 与 Helm 的源码实现，完整讲解该命令的全部参数、使用场景、值合并策略与底层工作流程，帮助你安全、可控地完成 Cilium 升级。

一、命令概览：一条命令完成 Cilium 升级

cilium upgrade的作用是在 Kubernetes 集群中通过 Helm 升级一个已有的 Cilium 安装。它面向的是已经通过cilium install或 Helm 方式部署了 Cilium 的集群，其核心思路是：

1. 读取当前集群状态并完成环境预检（preinstall）；
2. 确定要使用的 Helm Chart（指定版本或本地目录）；
3. 合并 Helm values（命令行--set、values 文件、上一次 release 的值）；
4. 调用 Helm 的upgrade动作执行升级；
5. 按需执行 dry-run、强制重启 Pod 等后续动作。

该命令在 CLI 中的注册实现位于 cilium-cli/cli/install.go 的newCmdUpgradeWithHelm函数，命令执行时创建install.K8sInstaller并调用UpgradeWithHelm，其核心逻辑位于 cilium-cli/install/upgrade.go。

二、命令语法与内置示例

cilium upgrade [flags]

命令文档内置了两个典型示例，分别覆盖"默认升级"与"为多集群做准备"两种场景：

示例 1：使用现有参数升级到最新版本

$ cilium upgrade

该命令会沿用当前 Helm release 的参数，将 Cilium 升级到最新可用版本。

示例 2：升级并设置集群名称与 ID（多集群准备）

$ cilium upgrade --set cluster.id=1 --set cluster.name=cluster1

在升级的同时通过--set注入cluster.id=1与cluster.name=cluster1，为后续启用 ClusterMesh 多集群能力做准备。--set支持逗号分隔多组键值对（如key1=val1,key2=val2），也可以重复多次指定。

三、参数全表：升级相关的完整 Flags

cilium upgrade的选项分为两部分：升级专属 Flags 与继承自父命令（cilium）的全局 Flags。以下为完整清单：

3.1 升级专属参数

3.2 继承自父命令的全局参数

四、参数详解与源码级说明

4.1 values 相关的三组参数

cilium upgrade提供了三组用于注入/覆盖 Helm values 的参数：

• --set（helm-set）：命令行直接设置键值对，key1=val1,key2=val2逗号分隔；
• --set-string（helm-set-string）：强制作为字符串设置，适用于需要保留字符串语义（如版本号、带前导零的数字）的场景；
• --set-file（helm-set-file）：从本地文件读取值，格式为key1=path1,key2=path2；
• -f, --values（helm-values）：指定 YAML 文件或 URL，可多次指定进行叠加。

值得注意的是，CLI 源码通过 normalizeFlags 将内部helm-set、helm-set-file、helm-set-string、helm-values分别规范化为用户可见的set、set-file、set-string、values，保证与 Helm 原生命令行体验一致。

4.2 values 合并与升级策略：--reset-values/--reuse-values/--reset-then-reuse-values

升级时如何处理"新 chart 内置值、上次 release 的值、命令行覆盖值"三者关系，是升级正确性的关键：

• --reset-then-reuse-values（默认 true）：先以新 chart 内置值为基准重置，再应用上次 release 保存的值，最后合并命令行--set/-f覆盖。这是最平衡的默认策略，保证升级既不会丢掉历史配置，又能接收新版本 chart 的新默认值；
• --reset-values：完全丢弃上次 release 的值，只用新 chart 内置值加命令行覆盖；
• --reuse-values：完全复用上次 release 的值（除非命令行显式覆盖），忽略 chart 中新增默认值；该选项优先级高于--reset-values。

这些标志在源码中直接映射到 Helm v4 的action.Upgrade客户端，见 cilium-cli/internal/helm/helm.go：

helmClient := action.NewUpgrade(actionConfig) helmClient.ResetThenReuseValues = params.ResetThenReuseValues helmClient.ResetValues = params.ResetValues helmClient.ReuseValues = params.ReuseValues

4.3 数据路径模式自动探测：--datapath-mode

--datapath-mode支持tunnel、native、aws-eni、gke、azure、aks-byocni六种模式，默认不指定时由 detectDatapathMode 自动探测：

1. 若用户显式指定，则直接使用并打印Custom datapath mode日志；
2. 否则先检查 helm values 中的routingMode：native对应 native 模式，tunnel对应 tunnel 模式；
3. 仍未命中则按集群类型推断：Kind/Minikube →tunnel，EKS →aws-eni，GKE →gke；AKS 会先调用azureAutodetect()判断是否为 BYOCNI 模式，是则选aks-byocni，否则选azure；
4. 其余平台默认tunnel。

4.4--nodes-without-cilium：在"无 Cilium 节点"上跳过调度

当集群中存在标记为cilium.io/no-schedule=true的节点（例如已经由其他方案提供连通性的基础设施节点）时，开启该选项会为 Cilium Agent、Operator 以及 SPIRE Agent 注入调度亲和性，避免将 Cilium 组件调度到这些节点上。源码实现见 cilium-cli/install/install.go，它通过向--set-string追加defaults.CiliumScheduleAffinity、defaults.CiliumOperatorScheduleAffinity、defaults.SpireAgentScheduleAffinity三组亲和性配置实现。

4.5--restart：升级后强制重启组件

Helm 升级只会更新资源定义，ConfigMap 等配置变更需要 Pod 重启才能生效。因此升级完成后 CLI 会提示：

⚠️ You maybe need to restart Cilium pods for configmap changes to take effect

若指定-r, --restart，则升级成功后主动删除 Cilium Agent Pod（选择器k8s-app=cilium）与 Cilium Operator Pod（选择器io.cilium/app=operator），由 Deployment 自动重建，实现"升级即生效"，见 cilium-cli/install/upgrade.go。两个 Pod 选择器的默认值定义在 cilium-cli/defaults/defaults.go。

4.6--wait与--wait-duration：等待升级完成

--wait让 Helm 在升级完成后等待资源就绪，超时时间由--wait-duration控制，默认 5 分钟（对应 defaults.StatusWaitDuration）。源码中通过设置WaitStrategy实现：开启--wait时使用kube.StatusWatcherStrategy等待所有 chart 资源就绪；未开启时使用kube.HookOnlyStrategy（仅等待 hooks 完成，保持旧版Wait:false的快速返回语义），见 cilium-cli/internal/helm/helm.go。

五、升级执行流程（源码视角）

结合 cilium-cli/install/upgrade.go 与 cilium-cli/internal/helm/helm.go，一次cilium upgrade的完整调用链如下：

1. 版本列表模式：若指定--list-versions，直接列出全部可用版本并返回，不执行升级；
2. 预检（preinstall）：检查集群状态、自动探测数据路径模式等；
3. 合并 values：通过MergeValues将-f文件、--set/--set-file/--set-string合并为最终 values；
4. 构造升级参数：将命名空间、release 名称、chart、values、三类 values 策略、wait、dry-run、history-max 等封装为helm.UpgradeParameters；
5. 执行 Helm upgrade：创建action.NewUpgrade，配置ResetThenReuseValues/ResetValues/ReuseValues、WaitStrategy、Timeout、DryRunStrategy、MaxHistory，最终调用RunWithContext执行升级；
6. 结果输出：
   • --dry-run：将生成的 manifest 输出到 stdout（dry-run 模式下 CLI 会丢弃其他日志，便于管道处理，见 cilium-cli/cli/install.go）；
   • --dry-run-helm-values：将非默认 Helm values 以 YAML 形式输出；
7. 可选重启：未指定--restart时提示可能需要重启 Pod；指定时删除 Agent/Operator Pod 触发重建。

六、升级前安全检查：dry-run 双模式

升级属于高风险操作，官方推荐先做两种 dry-run 预演：

预览将要生成的资源清单：

$ cilium upgrade --dry-run

该模式不会改动集群，仅将 Helm 渲染出的全部 Kubernetes 资源写入 stdout，方便 review 即将发生的变更。

预览将要生效的非默认 Helm values：

$ cilium upgrade --dry-run-helm-values

该模式输出的是"相对 chart 默认值有差异"的 values（YAML 格式），可直接用于审计升级后的配置变化。注意 dry-run 期间 CLI 会屏蔽常规日志输出，保证 stdout 内容纯净、可管道化处理。

组合使用建议：先在测试环境执行--dry-run与--dry-run-helm-values核对变更，再在正式环境执行真实升级，升级前用--list-versions确认目标版本存在。

七、常见升级场景速查

场景一：沿用历史配置升级到最新版（默认行为）

$ cilium upgrade

场景二：升级到指定版本并等待就绪

$ cilium upgrade --version v1.20.1 --wait --wait-duration 10m

场景三：升级时为多集群（ClusterMesh）注入集群标识

$ cilium upgrade --set cluster.id=1 --set cluster.name=cluster1

场景四：使用本地 Chart 目录升级（离线/定制场景）

$ cilium upgrade --chart-directory ./install/kubernetes/cilium

仓库内的官方 Chart 源码位于 install/kubernetes，该目录下包含完整的 Helm Chart 模板（142 个 YAML 文件与 8 个 tpl 模板等），适合在离线环境或需要深度定制时作为--chart-directory的来源。

场景五：通过 values 文件批量调整参数

$ cilium upgrade -f my-values.yaml --set bpf.masquerade=true

场景六：升级后立即重启 Cilium 组件使配置生效

$ cilium upgrade -r

八、注意事项

• 命名空间一致性：升级默认针对kube-system命名空间下的ciliumHelm release，若安装时使用了自定义命名空间或 release 名称，请通过-n/--namespace与--helm-release-name保持一致；
• values 策略优先级：--reuse-values>--reset-values>--reset-then-reuse-values，显式指定前两者时默认的--reset-then-reuse-values会被忽略；
• ConfigMap 生效延迟：即便升级成功，ConfigMap 类配置变更仍需要 Pod 重启才能完全生效，建议在变更配置类参数时配合-r使用；
• 版本默认值：命令文档生成的默认版本为v1.20.1，实际以你使用的 cilium-cli 版本--version默认值及可用版本列表为准，升级前可通过cilium upgrade --list-versions确认。

九、总结

cilium upgrade将"版本升级、配置变更、多集群准备、组件重启"整合为一条 Helm 驱动的原子命令：默认的--reset-then-reuse-values策略在保留历史配置与接收新默认值之间取得平衡，--dry-run/--dry-run-helm-values提供了升级前的无损预演，--restart解决了 ConfigMap 变更的生效问题，而--datapath-mode的自动探测与--nodes-without-cilium的亲和性控制则覆盖了多环境适配需求。理解其背后的 Helm 调用链（cilium-cli/internal/helm/helm.go）与 values 合并逻辑，将帮助你在大规模集群中安全、可控地完成每一次 Cilium 升级。

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