使用 cilium install 命令在 Kubernetes 集群中通过 Helm 安装 Cilium【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/ciliumcilium install是 Cilium CLIcilium-cli的核心命令它基于 Helm 一键将 CiliumeBPF 驱动的网络、安全与可观测性数据面安装到当前 Kubernetes 集群中并自动完成集群类型、数据面模式与 kube-proxy 状态的探测。本文以 Documentation/cmdref/cilium_install.md 为骨架结合 cilium-cli/install 与 cilium-cli/cli/install.go 源码系统讲解该命令的全部参数、典型安装场景、底层 Helm 执行链路与各类云厂商环境下的自动配置逻辑帮助你掌握从默认安装到多集群、多云环境定制化安装的完整能力。一、命令概览安装的本质是一次增强版 Helm 操作cilium install的完整定义位于 cilium-cli/cli/install.go 的newCmdInstallWithHelm()其官方 Synopsis 为Install Cilium in a Kubernetes cluster using Helm命令的完整语法如下cilium install [flags]与cilium upgrade、cilium uninstall一样该命令在底层调用 Helm v4 的 Go APIhelm.sh/helm/v4/pkg/action执行安装动作但在安装前会额外完成三件聪明的准备工作详见 cilium-cli/install/install.go解析并加载 Helm chart支持内嵌 chart、本地目录、远程仓库三种来源自动探测集群环境Kubernetes 发行版类型、集群名称、数据面模式datapath mode、kube-proxy 是否安装合并 Helm 值将自动探测结果、--set等命令行参数与用户提供的 values 文件合并为最终 Helm values再执行helm install。安装命令的入口函数InstallWithHelm依次执行listVersions()若指定--list-versions→preinstall()自动探测与校验→getHelmValues()生成 Helm 值→action.NewInstall(...)→RunWithContext(...)最终完成 Release 创建。二、快速上手两种典型安装场景原文档给出了两个最常用的安装示例这里结合源码补充说明其含义。场景一使用默认参数在当前 Kubernetes 上下文安装 Cilium$ cilium install执行后CLI 会读取当前 kubeconfig 指定的集群自动探测集群类型与数据面模式并从默认的 Helm 仓库https://helm.cilium.io拉取默认版本当前默认v1.20.1的 Cilium chart安装到kube-system命名空间Helm Release 名默认cilium。场景二指定 Kubernetes 上下文并预先配置集群名称与 ID为多集群ClusterMesh能力做准备$ cilium install --context kind-cluster1 --set cluster.id1 --set cluster.namecluster1--context kind-cluster1切换 kubeconfig 中的目标上下文将 Cilium 安装到名为kind-cluster1的集群--set cluster.id1 --set cluster.namecluster1通过 Helm 值显式指定集群 ID 与名称。这正是开启 Cilium 多集群ClusterMesh功能的前置步骤——每个集群必须有唯一且一致的cluster.id与cluster.name。从源码看cluster.name会通过 cilium-cli/install/helm.go 被写入helmMapOpts[cluster.name]若未显式指定autodetectAndValidate会自动从集群中探测名称详见 cilium-cli/install/autodetect.goEKS 集群名还会经过trimEKSClusterName裁剪并将_、.、:等非法字符替换为-。三、安装前的自动探测CLI 比裸 Helm 多做了什么cilium install与直接使用 Helm 的最大区别在于安装前自动探测autodetectAndValidate见 cilium-cli/install/autodetect.go。整个流程分为三步。3.1 自动探测集群类型FlavorClient.AutodetectFlavor实现于 cilium-cli/k8s/client.go通过检测集群 Node 标签、上下文名称等方式识别 Kubernetes 发行版可能的取值定义在 cilium-cli/k8s/client.go枚举值对应环境KindMinikubeMinikubeKindKindKindKubernetes in DockerKindEKSAWS EKSKindGKEGoogle GKEKindAKSAzure AKSKindMicrok8sMicroK8ssnap 安装KindRancherDesktopRancher DesktopKindK3sK3sKindUnknown无法识别探测完成后 CLI 会输出 Auto-detected Kubernetes kind: 类型。不同发行版在安装时会自动追加不同的 Helm 值见 cilium-cli/install/helm.goKindipam.modekubernetesGKEnodeinit.removeCbrBridgetrue、nodeinit.reconfigureKubelettrue、cni.binPath/home/kubernetes/binMicroK8scni.binPath/var/snap/microk8s/current/opt/cni/bin、cni.confPath/var/snap/microk8s/current/args/cni-network、daemon.runPath/var/snap/microk8s/current/var/run/ciliumRancher Desktopcni.binPath/usr/libexec/cni。3.2 自动探测数据面模式Datapath ModedetectDatapathModecilium-cli/install/autodetect.go的判定逻辑为若用户通过--datapath-mode显式指定则直接采用用户值否则读取 Helm 值中已有的routingModenative对应 native 模式tunnel对应 tunnel 模式都没有时按集群类型推断默认值Kind / Minikube / 未知类型 →tunnel隧道模式EKS →aws-eniGKE →gkeAKS → 先调用azureAutodetect()判断是否为 BYOCNI自带 CNI模式BYOCNI 集群选aks-byocni否则选azure。3.3 自动探测 kube-proxy 并决定替换策略autodetectKubeProxycilium-cli/install/autodetect.go会检查kube-system命名空间中是否存在名为kube-proxy的 DaemonSet存在保持默认kube-proxy 继续负责 Service 转发不存在CLI 推断kube-proxy 未安装并自动追加kubeProxyReplacementtrue同时探测 API Server 地址与端口设置k8sServiceHost/k8sServicePort让 Cilium完全替代 kube-proxy的功能此时会输出ℹ️ Cilium will fully replace all functionalities of kube-proxy。特别地在 Kind 环境中 API Server 的地址端口是从default/kubernetes服务的 EndpointSlice 中探测的因为 Kind 的 API Server 经过端口转发。此外K3s 集群会跳过该项探测。3.4 云厂商特定校验GKE若未通过参数或 Helm 值提供ipv4NativeRoutingCIDRCLI 会调用gkeNativeRoutingCIDR尝试通过gcloud自动获取 GKE 原生路由 CIDR见 cilium-cli/install/install.go。若gcloud不可用会提示用--set ipv4NativeRoutingCIDRx.x.x.x/x手动指定。AKS使用 Azure IPAM即azure数据面模式时azureSetupServicePrincipal会要求提供 Azure 服务主体凭据。EKSawsSetupChainingMode负责配置与 AWS VPC CNI 的 chaining 模式。四、安装选项详解全部参数速查表以下是cilium install的全部命令选项与 Documentation/cmdref/cilium_install.md 保持一致并补充源码层面的默认值与行为说明。这些标志定义于 cilium-cli/cli/install.go。选项默认值说明--chart-directory string空指定本地 Helm chart 目录适合在正式 Helm Release 发布前测试上游代码时使用见 cilium-cli/install/install.go--datapath-mode string自动探测数据面模式可选tunnel/native/aws-eni/gke/azure/aks-byocni--dry-runfalse将待安装的资源清单输出到 stdout但不实际安装。输出便于直接管道给kubectl等其他命令--dry-run-helm-valuesfalse仅将非默认的 Helm values 输出到 stdout不执行安装-h, --help—显示帮助信息--history-max int10限制每个 Release 保留的最大修订revision数量0表示不限制--list-versionsfalse仅列出所有可用版本不执行安装。输出中会以(default)标记默认版本--nodes-without-ciliumfalse为 Cilium 组件配置亲和性避免调度到带cilium.io/no-scheduletrue标签的节点上前提基础设施已为这些节点配置了集群内路由--repository stringhttps://helm.cilium.io下载 Cilium Helm chart 的仓库地址--set stringArray—在命令行设置 Helm 值可多次指定或用逗号分隔多个key1val1,key2val2--set-file stringArray—从文件读取值来设置 Helm 值可多次指定或用逗号分隔key1path1,key2path2--set-string stringArray—在命令行设置 Helm字符串值强制按字符串处理语法同--set-f, --values strings—通过 YAML 文件或 URL 指定 Helm values可多次指定--version stringv1.20.1当前仓库文档默认值指定要安装的 Cilium 版本--waitfalse等待 Helm 安装完成即等待资源就绪而非仅等待 hook 完成--wait-duration duration5m0s等待状态的最大时长关于--set系列标志名的说明在源码中这些标志注册为--helm-set、--helm-set-file、--helm-set-string、--helm-values随后通过normalizeFlagscilium-cli/cli/install.go规范化为文档中展示的--set、--set-file、--set-string、--values从而保证与 Helm 原生命令的使用习惯完全一致。继承自父命令的全局选项cilium install还继承cilium根命令的通用选项用于指定访问目标集群的方式选项默认值说明--as string—以指定用户名或 Service Account身份模拟执行操作--as-group stringArray—模拟用户所属的组可重复指定多个组--context string—指定 kubeconfig 中的 Kubernetes 上下文--helm-release-name stringcilium指定 Helm Release 名称。可用于关联通过原生 Helm 直接安装的 Cilium 实例或覆盖 CLI 默认 Release 名--kubeconfig string—指定 kubeconfig 文件路径-n, --namespace stringkube-system可通过环境变量CILIUM_NAMESPACE设置Cilium 运行的命名空间五、参数注入机制--set、--set-file、--set-string与--values的区别cilium install提供了四类 Helm 值注入方式全部合并进install.Parameters.HelmOpts类型为values.Options见 cilium-cli/install/install.go--set keyvalue注入普通值CLI 会按 Helm 的strvals语法解析支持key.subkeyv、列表、整数、布尔等类型推断--set-string keyvalue强制以字符串类型注入适合需要避免类型推断如版本号1.0被解析成数字的场景--set-file keypath值来自文件内容适合注入证书、密钥等较长的文本-f/--values file.yaml或 URL提供完整的 YAML values 文件可多次指定多个文件。这些参数在 cilium-cli/install/helm.go 中通过helm.MergeVals(k.params.HelmOpts, helmMapOpts)与自动探测生成的 Helm 值合并用户显式指定的值优先级高于自动探测结果因此你可以用--set覆盖任何自动探测出的默认配置。六、数据面模式与 Helm 值的映射关系--datapath-mode与 Helm 值的映射实现在 cilium-cli/install/helm.go理解该映射有助于针对不同云环境选择合适的模式--datapath-mode生成的 Helm 值适用场景tunnel默认自动探测兜底值routingModetunnel、tunnelProtocolvxlan通用环境通过 VXLAN 隧道封装流量对底层网络无特殊要求native由用户自行通过--set routingModenative等配合原生路由模式依赖底层网络的连通性aws-eniipam.modeeni、eni.enabledtrue、routingModenativeAWS EKS直接使用 ENI 分配 Pod IPgkeipam.modekubernetes、gke.enabledtrue、gke.disableDefaultSnattrueGoogle GKE配合原生路由通常需同时设置ipv4NativeRoutingCIDRazureipam.modeazure、azure.enabledtrue及azure.subscriptionID/azure.resourceGroup/azure.tenantID/azure.clientID/azure.clientSecret同时关闭 BPF 与 IPv4/IPv6 伪装bpf.masqueradefalse、enableIPv4Masqueradefalse、enableIPv6MasqueradefalseAzure AKS非 BYOCNI使用 Azure IPAMaks-byocniaksbyocni.enabledtrueAzure AKS 的 BYOCNI自带 CNI模式此时不使用 Azure IPAM相关常量定义于 cilium-cli/install/install.go数据面模式为DatapathTunnel/DatapathNative/DatapathAwsENI/DatapathGKE/DatapathAzure/DatapathAKSBYOCNI对应routingMode与tunnelProtocol等取值。另外无论选择哪种模式CLI 都会为1.16.0的 Cilium 版本默认设置operator.replicas1见 cilium-cli/install/helm.go并在需要时如 GKE、AKS 等环境启用nodeinit.enabledtrue。七、--nodes-without-cilium混合节点池的调度控制当集群中存在不需要运行 Cilium 的节点如仅供数据面转发的基础设施节点时可先给这些节点打上标签$ kubectl label node node-name cilium.io/no-scheduletrue再使用--nodes-without-cilium安装$ cilium install --nodes-without-ciliumCLI 会为三类组件追加requiredDuringSchedulingIgnoredDuringExecution类型的 NodeAffinityoperatorNotIn、values[0]true即不调度到带该标签的节点定义于 cilium-cli/defaults/defaults.goCilium Agentaffinity.nodeAffinity...键为cilium.io/no-scheduleCilium Operatoroperator.affinity.nodeAffinity...SPIRE Agentauthentication.mutual.spire.install.agent.affinity...。这些亲和性通过k.params.HelmOpts.StringValues注入cilium-cli/install/install.go。使用前提是这些节点上的路由已由基础设施预先配置好保证 Cilium 集群内的连通性不受影响。八、安装前的预演--dry-run与--dry-run-helm-values在真正落地到生产集群之前强烈建议先用预演模式核对将要部署的内容预览将要创建的全部 Kubernetes 资源清单$ cilium install --dry-run执行后所有 YAML 资源会输出到 stdout且不会对集群做任何写入。源码在--dry-run时会将安装日志输出重定向到io.Discard保证 stdout 干净、便于管道处理见 cilium-cli/cli/install.go随后以action.DryRunClient策略执行渲染最终通过release.NewAccessor(rel).Manifest()输出清单cilium-cli/install/install.go。仅预览非默认的 Helm 值$ cilium install --dry-run-helm-values该模式输出的是合并了自动探测结果后、与 chart 默认值相比发生变更的 Helm values以 YAML 形式非常适合排查自动探测给我配了什么。两个标志可组合使用且均被Parameters.IsDryRun()视为预演cilium-cli/install/install.go。九、版本管理--list-versions、--version与--history-max查看可用版本cilium install --list-versions会从仓库拉取版本列表并全部打印最新版本在前默认版本以(default)标注随后直接退出不执行安装cilium-cli/install/install.go。指定安装版本cilium install --version v1.20.1。chart 的解析顺序是显式指定--chart-directory时优先加载本地目录否则在 CLI 二进制内嵌的 chart 中查找github.com/cilium/charts未命中再从--repository指定的远程仓库下载并缓存到本地 cache 目录见 cilium-cli/internal/helm/helm.go。仓库地址支持 HTTP 仓库与 OCI Registry 两种形式。控制 Release 历史--history-max默认保留 10 个修订版本防止 Helm Release 历史无限增长设为0表示不限制。十、等待安装完成与安装后验证默认情况下cilium install只等待 Helm hook 完成即返回加上--wait后CLI 会以kube.StatusWatcherStrategy持续观察资源直到全部就绪超时时间由--wait-duration控制默认5m0s常量定义见 cilium-cli/defaults/defaults.go$ cilium install --wait--wait-duration可与--wait配合调整超时例如$ cilium install --wait --wait-duration 10m安装完成后建议依次执行cilium status查看 Agent、Operator 与集群连通性状态cilium connectivity test运行完整的连通性测试套件验证 Cilium 数据面与安全策略是否正常工作。上述命令的具体用法可参见仓库内的命令参考文档 Documentation/cmdref/cilium_status.md 与 Documentation/cmdref/cilium_connectivity_test.md。十一、源码级验证安装逻辑的测试保障cilium install的自动探测与参数合并逻辑均有配套测试可作为理解其行为的权威依据cilium-cli/install/autodetect_test.go覆盖数据面模式自动探测、集群名称裁剪等场景cilium-cli/install/install_test.go覆盖安装参数解析与预演输出逻辑cilium-cli/install/helm_test.go覆盖 Helm 值的生成与合并结果cilium-cli/k8s/client_test.go覆盖AutodetectFlavor对 GKE、EKS 等集群类型的识别如通过 Node 标签检测 GKE。如需在不影响现有集群的前提下完整演练安装流程最实用的组合是cilium install --dry-run查看资源清单再用cilium install --dry-run-helm-values确认最终生效的配置最后在测试集群中正式执行cilium install --wait并配合cilium connectivity test验证。【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考