Cilium CLIcilium upgrade完全指南基于 Helm 的无缝升级、参数详解与源码级工作原理【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/ciliumcilium upgrade是 Cilium 官方 CLIcilium-cli提供的升级命令负责通过 Helm 在 Kubernetes 集群中就地升级已有的 Cilium 安装实现版本更新、配置调整与多集群参数设置。本文以 cilium_upgrade.md 的命令参考文档为主线结合仓库内 CLI 与 Helm 的源码实现完整讲解该命令的全部参数、使用场景、值合并策略与底层工作流程帮助你安全、可控地完成 Cilium 升级。一、命令概览一条命令完成 Cilium 升级cilium upgrade的作用是在 Kubernetes 集群中通过 Helm 升级一个已有的 Cilium 安装。它面向的是已经通过cilium install或 Helm 方式部署了 Cilium 的集群其核心思路是读取当前集群状态并完成环境预检preinstall确定要使用的 Helm Chart指定版本或本地目录合并 Helm values命令行--set、values 文件、上一次 release 的值调用 Helm 的upgrade动作执行升级按需执行 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.id1 --set cluster.namecluster1在升级的同时通过--set注入cluster.id1与cluster.namecluster1为后续启用 ClusterMesh 多集群能力做准备。--set支持逗号分隔多组键值对如key1val1,key2val2也可以重复多次指定。三、参数全表升级相关的完整 Flagscilium upgrade的选项分为两部分升级专属 Flags 与继承自父命令cilium的全局 Flags。以下为完整清单3.1 升级专属参数参数类型默认值说明--chart-directory stringstring空Helm chart 本地目录指定后直接从本地目录加载 chart而非从仓库下载--datapath-mode stringstring自动探测数据路径模式tunnel、native、aws-eni、gke、azure、aks-byocni--dry-runboolfalse将待安装资源输出到 stdout不实际执行安装--dry-run-helm-valuesboolfalse仅将非默认的 Helm values 输出到 stdout不执行实际升级-h, --helpbool-显示 upgrade 命令帮助--history-max intint10每个 release 最多保留的修订版本数量设为 0 表示不限制--list-versionsboolfalse仅列出所有可用版本不实际执行升级--nodes-without-ciliumboolfalse配置亲和性避免将 Cilium 组件调度到带有cilium.io/no-schedule标签的节点上前提基础设施已在这些节点上配置好路由以提供集群内连通性--repository stringstringhttps://helm.cilium.io下载 Cilium chart 的 Helm 仓库地址--reset-then-reuse-valuesbooltrue升级时先重置为 chart 内置 values再应用上一次 release 的值最后合并命令行--set与-f覆盖项若显式指定了--reset-values或--reuse-values则本参数被忽略--reset-valuesboolfalse升级时将 Helm values 重置为 chart 内置值-r, --restartboolfalse升级后强制重启 Cilium Pod--reuse-valuesboolfalse复用最新 release 的 Helm values除非其他 flag 设置了覆盖项优先级高于--reset-values--set stringArray[]string-在命令行设置 Helm values可多次指定或用逗号分隔--set-file stringArray[]string-从文件读取 Helm valueskey1path1,key2path2--set-string stringArray[]string-在命令行设置 STRING 类型的 Helm values-f, --values strings[]string-指定 YAML 文件或 URL 形式的 Helm values可多次指定--version stringstringv1.20.1要安装的 Cilium 版本以当前仓库文档生成为准--waitboolfalse等待 Helm upgrade 完成--wait-duration durationduration5m0s等待状态的最大时长3.2 继承自父命令的全局参数参数默认值说明--as string-模拟的用户名可以是普通用户或某命名空间下的 ServiceAccount--as-group stringArray-模拟的用户组可重复指定多个--context string-Kubernetes 配置上下文--helm-release-name stringciliumHelm release 名称--kubeconfig string-kubeconfig 文件路径-n, --namespace stringkube-systemCilium 运行所在的命名空间也可通过环境变量CILIUM_NAMESPACE设置四、参数详解与源码级说明4.1 values 相关的三组参数cilium upgrade提供了三组用于注入/覆盖 Helm values 的参数--sethelm-set命令行直接设置键值对key1val1,key2val2逗号分隔--set-stringhelm-set-string强制作为字符串设置适用于需要保留字符串语义如版本号、带前导零的数字的场景--set-filehelm-set-file从本地文件读取值格式为key1path1,key2path2-f, --valueshelm-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.gohelmClient : action.NewUpgrade(actionConfig) helmClient.ResetThenReuseValues params.ResetThenReuseValues helmClient.ResetValues params.ResetValues helmClient.ReuseValues params.ReuseValues4.3 数据路径模式自动探测--datapath-mode--datapath-mode支持tunnel、native、aws-eni、gke、azure、aks-byocni六种模式默认不指定时由 detectDatapathMode 自动探测若用户显式指定则直接使用并打印Custom datapath mode日志否则先检查 helm values 中的routingModenative对应 native 模式tunnel对应 tunnel 模式仍未命中则按集群类型推断Kind/Minikube →tunnelEKS →aws-eniGKE →gkeAKS 会先调用azureAutodetect()判断是否为 BYOCNI 模式是则选aks-byocni否则选azure其余平台默认tunnel。4.4--nodes-without-cilium在无 Cilium 节点上跳过调度当集群中存在标记为cilium.io/no-scheduletrue的节点例如已经由其他方案提供连通性的基础设施节点时开启该选项会为 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-appcilium与 Cilium Operator Pod选择器io.cilium/appoperator由 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的完整调用链如下版本列表模式若指定--list-versions直接列出全部可用版本并返回不执行升级预检preinstall检查集群状态、自动探测数据路径模式等合并 values通过MergeValues将-f文件、--set/--set-file/--set-string合并为最终 values构造升级参数将命名空间、release 名称、chart、values、三类 values 策略、wait、dry-run、history-max 等封装为helm.UpgradeParameters执行 Helm upgrade创建action.NewUpgrade配置ResetThenReuseValues/ResetValues/ReuseValues、WaitStrategy、Timeout、DryRunStrategy、MaxHistory最终调用RunWithContext执行升级结果输出--dry-run将生成的 manifest 输出到 stdoutdry-run 模式下 CLI 会丢弃其他日志便于管道处理见 cilium-cli/cli/install.go--dry-run-helm-values将非默认 Helm values 以 YAML 形式输出可选重启未指定--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 默认值有差异的 valuesYAML 格式可直接用于审计升级后的配置变化。注意 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.id1 --set cluster.namecluster1场景四使用本地 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.masqueradetrue场景六升级后立即重启 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考