企业官网建设流程全解析

Cilium 在 GKE 上的 Kubernetes Host-Scope IPAM：架构、配置与排障实战指南

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

导读

本文围绕 Cilium 在 Google Kubernetes Engine（GKE）上的 IPAM 运行模式展开，讲解其如何直接复用 Google Cloud 原生网络层完成地址管理与 IP 转发，并依托 Kubernetes 节点上的spec.podCIDR/spec.podCIDRs进行 Pod 地址分配。读完本文你将掌握：GKE IPAM 的架构与数据面配合方式、ipam.mode=kubernetes（Helm）与ipam: kubernetes（ConfigMap）的启用方法，以及如何通过kubectl与cilium-dbg status快速验证 PodCIDR 分配并排查 IPAM 异常。

一、GKE IPAM 架构总览

1.1 直接复用 Google Cloud 原生网络层

当 Cilium 运行在 Google GKE 上时，不再使用 Cilium 自建的叠加网络与地址池管理，而是直接利用 Google Cloud 的原生网络层（VPC 网络）来完成地址管理和 IP 转发。这意味着 Pod 的 IP 直接从 Google Cloud 网络中分配，天然具备云网络的可路由性。

1.2 Kubernetes Host-Scope IPAM 模式

从 IPAM 角度看，GKE 配置模式下 Cilium 使用Kubernetes host-scope IPAM 模式（即ipam.mode=kubernetes）。其核心行为是：

• Cilium agent 在启动时会等待Kubernetes 节点资源被填充spec.podCIDR或spec.podCIDRs字段（字段的选择取决于当前启用的地址族：IPv4 使用spec.podCIDR，IPv4/IPv6 双栈则使用spec.podCIDRs）；
• 一旦节点 PodCIDR 就绪，Cilium 即从该网段内为本地节点上的 Pod 分配地址；
• 该模式将地址分配职责委托给集群中的每一个节点，由 Kubernetes 负责为每个节点划分 PodCIDR 网段。

这一机制与 Kubernetes Host Scope 模式的完整说明 一脉相承，可在该文档中查看更详细的字段与注解机制。

注意：为了让 Kubernetes 节点能获得 PodCIDR，需要确保kube-controller-manager以--allocate-node-cidrs标志运行，否则节点上不会出现spec.podCIDR字段。

1.3 数据面配合：Google Cloud 原生路由

与 IPAM 配套的数据面行为记录在 路由概念文档的 Google Cloud 小节（gke_datapath锚点）中。当 Cilium 运行在 GKE 上时，采用native routing（原生路由）配置，带来以下效果：

• 寻址（Addressing）：Cilium 从分配给特定 Kubernetes 节点的 PodCIDR 中为 Pod 分配 IP。借助 Google Cloud 的Alias IP ranges，这些 IP 在 Google Cloud 网络中是原生可路由的，无需额外的封装（encapsulation）或路由分发。
• Masquerading（SNAT）：所有目标不在ipv4-native-routing-cidr范围内的流量都会被伪装（masquerade）为节点 IP，从而变为公网可路由。
• 负载均衡（Load-balancing）：对于所有版本的 GKE，ClusterIP 负载均衡都通过eBPF实现。
• 策略执行与可观测性：所有 NetworkPolicy 执行和可见性能力均由 eBPF 提供。

1.4 GKE 数据面开启配置

在routing.rst中明确给出了运行 GKE 数据面必须设置的选项：

• gke.enabled: true：启用 Google Kubernetes Engine（GKE）数据面。设为true会级联启用以下选项：
  • ipam: kubernetes：启用 Kubernetes host-scope IPAM；
  • routing-mode: native：启用原生路由模式；
  • enable-endpoint-routes: true：在节点上启用 per-endpoint 路由（自动禁用本地节点路由）。
• ipv4-native-routing-cidr: x.x.x.x/y：设置支持原生路由的 CIDR 范围，该范围内的流量不做伪装（masquerade）。

二、启用 GKE IPAM：两种配置方式

GKE IPAM 模式可通过以下两种等价方式启用：

方式一：Helm 选项

helm install cilium cilium/cilium --namespace kube-system \ --set ipam.mode=kubernetes

方式二：ConfigMap 选项

在 Cilium 的 ConfigMap 中设置：

ipam: kubernetes

从配置语义上看，设置ipam: kubernetes会启用 Kubernetes IPAM 模式，且会自动执行以下联动（详见 Kubernetes Host Scope 配置小节）：

• 若enable-ipv4为true，自动启用k8s-require-ipv4-pod-cidr；
• 若enable-ipv6为true，自动启用k8s-require-ipv6-pod-cidr。

这两个选项会指示 Cilium agent 等待对应地址族的 PodCIDR 通过 Kubernetes 节点资源提供后才完成启动。对应 Helm 写法为：

--set ipam.mode=kubernetes --set k8s.requireIPv4PodCIDR=true --set k8s.requireIPv6PodCIDR=true

其中后两个--set只在配合--set ipam.mode=kubernetes时生效。

关于spec.podCIDR与spec.podCIDRs的选择

Kubernetes Host Scope 模式从v1.Node对象获取 PodCIDR 有两种途径（字段方式）：

在双栈（IPv4+IPv6）场景下使用spec.podCIDRs；若只启用单一地址族，则spec.podCIDR即可满足。此外，该模式还支持通过节点注解提供 CIDR（如network.cilium.io/ipv4-pod-cidr、network.cilium.io/ipv6-pod-cidr等），主要用于不支持spec.podCIDRs的旧版 Kubernetes 且同时启用 IPv4/IPv6 的场景。

三、在 GKE 上安装 Cilium 的前提与命令

3.1 集群要求

根据 GKE 安装要求，在 GKE 上的默认配置组合为：

要求中特别强调：创建集群时应使用--node-taints参数打上node.cilium.io/agent-not-ready=true:NoExecute污点，以保证在 Cilium 就绪之前，业务 Pod 不会被调度到节点上执行（也可参考文档中提到的其他备选方案）。

3.2 创建 GKE 集群

参考 快速安装指南 中的 GKE 分步说明，先确保已安装gcloud并完成账号准备：

export NAME="$(whoami)-$RANDOM" # 创建节点池时加上污点，确保只有 Cilium 就绪后 Pod 才会被调度 gcloud container clusters create "${NAME}" \ --node-taints node.cilium.io/agent-not-ready=true:NoExecute \ --zone us-west2-a gcloud container clusters get-credentials "${NAME}" --zone us-west2-a

3.3 安装 Cilium

cilium install --version <CHART_VERSION>

其中<CHART_VERSION>替换为当前仓库 VERSION 文件所对应的版本号。安装完成后，Cilium 即运行在 GKE IPAM 模式下。

四、Troubleshooting：验证 PodCIDR 与 IPAM 状态

4.1 验证节点暴露的 PodCIDR 字段

首先确认 Kubernetes 节点上是否填充了podCIDR字段，使用如下命令一次性输出集群所有节点的名称与其 PodCIDR：

kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.podCIDR}{"\n"}{end}'

预期输出形如：

gke-cluster4-default-pool-b195a3f3-k431 10.4.0.0/24 gke-cluster4-default-pool-b195a3f3-zv3p 10.4.1.0/24

每个节点应拥有互不重叠的 PodCIDR 网段。如果该字段为空，说明kube-controller-manager未开启--allocate-node-cidrs，或节点尚未完成 PodCIDR 分配，Cilium agent 将一直等待该字段填充。

4.2 在指定节点上查看 Cilium 状态

定位目标节点上的 Cilium Pod，然后进入 Pod 执行cilium-dbg status：

kubectl -n kube-system get pods -o wide | grep gke-cluster4-default-pool-b195a3f3-k431

输出示例：

cilium-lv4xd 1/1 Running 0 3h8m 10.164.0.112 gke-cluster4-default-pool-b195a3f3-k431 <none> <none>

进入该 Pod 查看状态：

kubectl -n kube-system exec -ti cilium-lv4xd -- cilium-dbg status

重点关注输出中的IPAM行：

KVStore: Disabled Kubernetes: Ok 1.14+ (v1.14.10-gke.27) [linux/amd64] Kubernetes APIs: ["CustomResourceDefinition", "cilium/v2::CiliumClusterwideNetworkPolicy", "cilium/v2::CiliumEndpoint", "cilium/v2::CiliumNetworkPolicy", "cilium/v2::CiliumNode", "core/v1::Endpoint", "core/v1::Namespace", "core/v1::Pods", "core/v1::Service", "networking.k8s.io/v1::NetworkPolicy"] KubeProxyReplacement: Probe [] Cilium: Ok OK NodeMonitor: Disabled Cilium health daemon: Ok IPAM: IPv4: 7/255 allocated from 10.4.0.0/24, Controller Status: 36/36 healthy Proxy Status: OK, ip 10.4.0.190, 0 redirects active on ports 10000-20000 Hubble: Disabled Cluster health: 2/2 reachable (2020-04-23T13:46:36Z)

判定方法：IPAM行中显示的分配源网段（示例中为10.4.0.0/24）必须与该节点在kubectl get nodes中公布的 PodCIDR 一致。若两者不一致或显示异常，说明 IPAM 与 Kubernetes 节点资源不同步，可结合节点事件与 Cilium agent 日志进一步排查。

附加要点：在 host-scope 模式下KVStore显示为Disabled属正常现象，因为该模式不依赖外部键值存储，地址信息完全由 Kubernetes 节点资源承载。

五、深入理解：host-scope IPAM 的机制细节

为了让读者更好地理解该模式的边界与适用前提，这里补充 kubernetes.rst 中关于该 IPAM 模式的几个关键细节：

1. 每节点独立分配：IP 从与每个节点关联的PodCIDR网段中分配，各节点间互不共享地址池，天然避免跨节点地址冲突。
2. 启动阻塞语义：在ipam.mode=kubernetes下，agent 启动时对 PodCIDR 的等待是强制前置条件（配合k8s-require-ipv4-pod-cidr/k8s-require-ipv6-pod-cidr），因此节点资源上 PodCIDR 的可用性是 GKE 模式下 Cilium 正常启动的前提。
3. 注解兜底机制：除v1.Node字段外，host-scope 模式还支持network.cilium.io/ipv4-pod-cidr等注解方式传递 PodCIDR 与 host/health/ingress 地址，适用于旧版 Kubernetes 双栈场景，可作为字段机制的补充。

六、常见问题速查

总结

在 GKE 上，Cilium 通过Kubernetes host-scope IPAM直接消费 Google Cloud 的 PodCIDR 分配结果，配合原生路由数据面（Alias IP ranges + eBPF）实现零封装的 Pod 网络。启用方式极为简洁：Helm 设置--set ipam.mode=kubernetes或 ConfigMap 设置ipam: kubernetes。日常运维中最关键的排障手段是双向核对——用kubectl get nodes确认节点公布 PodCIDR，用cilium-dbg status确认 agent 实际使用的分配网段，两者一致即说明 GKE IPAM 链路健康。

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