Cilium Gateway API 安装实战前置条件、CRD 安装与 Controller 启用全流程【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium本文围绕 Cilium 官方文档Documentation/network/servicemesh/gateway-api/installation.rst展开系统讲解在 Kubernetes 集群中启用 Cilium Gateway API Controller 的完整流程包括 kube-proxy 替代、L7 代理与 TPROXY 等前置条件Gateway API 必需/可选 CRD 的安装命令Standard 与 Experimental 两条发布通道以及通过 Helm 或 Cilium CLI 启用 Controller 的实操步骤。读完本文你可以独立完成一套可运行的 Cilium Gateway API 数据面部署并从源码层面理解gatewayAPI.enabled等 Helm 参数在 chart 模板中的实际作用。一、前置条件数据面依赖决定了部署成败Gateway API 功能不是装个 CRD 就能用的独立组件它建立在 Cilium 的 kube-proxy 替代与 L7 代理Envoy能力之上。官方文档明确要求以下三项配置与一项可选替代方案。1. kube-proxy 替代必须开启Cilium 必须配置kubeProxyReplacementtrue。原因从源码结构上可以印证Gateway API 的流量终结由运行在每个节点上的 Envoy 完成而 Envoy 监听器的上游负载均衡正是由 Cilium 的 kube-proxy 替代Socket LB / Maglev 等提供若仍依赖 kube-proxyService 流量路径与 L7 代理无法正确衔接。2. L7 代理必须启用Cilium 必须启用 L7 代理即l7Proxytrue该值为默认开启。Gateway API 的 Listener、HTTPRoute 等最终都会翻译成 Envoy 配置下发L7 代理是承载这些配置的运行时载体。3. TPROXY流量如何透明进入 Envoy到达 Gateway Service 的流量会通过内核TPROXY机制被透明转发到 Envoy。这里的默认值选择直接影响节点系统依赖默认bpf.tproxyfalseTPROXY 由 iptables 实现节点必须提供 iptables 以及 L7 代理所需的 netfilter 内核模块。官方文档特别提醒部分发行版并不默认携带这些模块缺失时连接到 Gateway 的流量会直接超时、根本到不了 Envoy——这是排查 Gateway 不通时最值得优先检查的项bpf.tproxytruebeta基于 eBPF 实现 TPROXY可去除对 iptables 的依赖。4. 服务暴露方式LoadBalancer 或 Host Network默认情况下Cilium Gateway API Controller 会为 Gateway 创建LoadBalancer 类型的 Service因此运行环境必须支持 LoadBalancer云厂商或集群内 LB 方案如 MetalLB。替代方案自 Cilium 1.16 起可以直接将 Cilium L7 代理暴露在宿主机网络上绕过 LoadBalancer 依赖。对应 Helm 参数为gatewayAPI.hostNetwork相关配置见 values.yaml 中gatewayAPI.hostNetwork字段其文档说明中明确该配置控制 Envoy 监听器是否暴露到 host network。二、安装 Gateway API CRD1. 必需 CRD 清单Cilium Gateway API 要求安装 Gateway API 的以下 7 个 CRD缺一不可CRD作用GatewayClass声明 Gateway 实现即控制器类别Gateway定义流量入口与 ListenerHTTPRouteHTTP 层路由规则GRPCRoutegRPC 路由规则BackendTLSPolicy后端 TLS 策略ReferenceGrant跨命名空间引用授权TLSRouteTLS 层路由规则2. 安装命令Standard / Experimental 通道Gateway API 提供 standard 与 experimental 两条发布通道。experimental 通道包含 standard 通道的全部内容外加若干实验性资源与字段。如果你需要用到当前标记为experimental的字段例如HTTPRoute资源中的 HTTPRoute Retry就必须安装 experimental 通道的 CRD。Standard 通道kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.0/experimental-install.yaml | 0/dev/null || true # 逐文件安装与官方文档一致 kubectl apply --server-side -f GATEWAY_API_RAW_BASE_URL/config/crd/standard/gateway.networking.k8s.io_gatewayclasses.yaml kubectl apply --server-side -f GATEWAY_API_RAW_BASE_URL/config/crd/standard/gateway.networking.k8s.io_gateways.yaml kubectl apply --server-side -f GATEWAY_API_RAW_BASE_URL/config/crd/standard/gateway.networking.k8s.io_httproutes.yaml kubectl apply --server-side -f GATEWAY_API_RAW_BASE_URL/config/crd/standard/gateway.networking.k8s.io_referencegrants.yaml kubectl apply --server-side -f GATEWAY_API_RAW_BASE_URL/config/crd/standard/gateway.networking.k8s.io_grpcroutes.yaml kubectl apply --server-side -f GATEWAY_API_RAW_BASE_URL/config/crd/standard/gateway.networking.k8s.io_backendtlspolicies.yaml kubectl apply --server-side -f GATEWAY_API_RAW_BASE_URL/config/crd/standard/gateway.networking.k8s.io_tlsroutes.yamlExperimental 通道将上述路径中的config/crd/standard/替换为config/crd/experimental/即可文件名完全一致。官方文档使用|GATEWAY_API_RAW_BASE_URL|占位符指代 Gateway API 上游 raw 资源地址实际执行时替换为对应版本的 raw URL。3. 可选 CRD不装则自动降级TCPRoute、UDPRoute、ListenerSet三个 CRD 是可选的。官方文档给出了一个重要的行为约定如果这些 CRD 未安装Cilium 会自动禁用对应功能而不是启动报错。因此最小化部署只需装上述 7 个必需 CRD。如需启用按同样方式安装 optional CRD同样分 standard / experimental 两个目录kubectl apply --server-side -f GATEWAY_API_RAW_BASE_URL/config/crd/standard/gateway.networking.k8s.io_listenersets.yaml kubectl apply --server-side -f GATEWAY_API_RAW_BASE_URL/config/crd/standard/gateway.networking.k8s.io_tcproutes.yaml kubectl apply --server-side -f GATEWAY_API_RAW_BASE_URL/config/crd/standard/gateway.networking.k8s.io_udproutes.yaml4. 升级场景的注意事项文档特别提示如果你是在升级既有安装务必先查阅 Cilium 的升级指南upgrade guide确认目标版本的破坏性变更与弃用项。以 Cilium 1.20 为例文档明确要求在更新 Gateway API CRD 之前先审阅升级指南中关于 Gateway API v1.6.1 与TLSRoute的说明。三、启用 Cilium Gateway API ControllerCRD 就绪后通过 Helm 或 Cilium CLI 打开 Controller 开关。核心参数就是gatewayAPI.enabledtrue。1. Helm 方式已有集群上启用对既有 Helm 安装进行升级helm upgrade cilium cilium/cilium \ --namespace kube-system \ --reuse-values \ --set kubeProxyReplacementtrue \ --set gatewayAPI.enabledtrue升级后重启 agent 与 operator 使配置生效kubectl -n kube-system rollout restart deployment/cilium-operator kubectl -n kube-system rollout restart ds/cilium新装集群则按 Cilium 的 Helm 全新安装流程在--set中带上同样两个参数。gatewayAPI.enabled在 chart 中的作用范围可以从 values.yaml 的注释与字段直接确认——它会自动设置 enable-envoy-config即开启该开关同时拉起 Envoy 数据面。同一gatewayAPI块下还有若干安装时即可一并规划的参数enableProxyProtocol为所有 Gateway API Listener 启用 Proxy Protocol开启后仅接受Proxy Protocol 流量useRemoteAddress默认true从远端地址而非 proxy protocol 头确定源 IPenableAppProtocol默认false启用 GEP-1911 后端协议选择enableAlpn默认false为 Listener 启用 ALPN先尝试 HTTP/2再回退 HTTP/1.1同时隐含启用 appProtocol 支持xffNumTrustedHops默认0信任的额外 XFF 代理跳数externalTrafficPolicy默认Cluster控制外部流量如何路由到 Gateway 的 LoadBalancer Service取Cluster或Local注意 host network 模式下该值被忽略gatewayClass.create默认auto控制是否自动创建 GatewayClass 资源secretsNamespaceEnvoy SDS 拉取 TLS 证书的命名空间默认创建cilium-secrets并同步 TLS Secret。当gatewayAPI.enabledtrue且gatewayClass.create为auto/true时chart 会渲染出默认 GatewayClass见 cilium-gateway-api-class.yamlapiVersion: gateway.networking.k8s.io/v1 kind: GatewayClass metadata: name: cilium spec: controllerName: io.cilium/gateway-controller description: The default Cilium GatewayClass这个模板本身也有条件逻辑第 1-2 行createauto时还会检查集群是否已存在gateway.networking.k8s.io/v1/GatewayClass据此决定是否创建——这解释了为什么create字段被设计为boolean | string两种类型。后续所有 Gateway 资源指定gatewayClassName: cilium即由该控制器接管。2. Cilium CLI 方式cilium upgrade --version CHART_VERSION \ --set kubeProxyReplacementtrue \ --set gatewayAPI.enabledtrue3. 验证两种方式下最终都以cilium status检查 agent 与 operator 状态$ cilium status从源码结构看enable-gateway-api最终通过 configmap 下发给 operator 进程见 cilium-configmap.yaml 中的enable-gateway-api配置项Gateway API 的调和逻辑运行在 cilium-operator 中这也是为什么 Helm 升级示例中同时要求 restart operator 与 agent。四、最小可行部署清单自检按本文流程部署后可对照以下清单逐项验证kubeProxyReplacementtrue、l7Proxytrue已生效cilium status/ configmap 确认节点 iptables 与 netfilter 模块可用或已启用 beta 的bpf.tproxytrue7 个必需 CRD 已安装kubectl get crd | grep gateway.networking若使用 TCP/UDP Route 或 ListenerSetoptional CRD 已安装gatewayAPI.enabledtrue已设置cilium-operator与ciliumDaemonSet 已滚动重启GatewayClassciliumcontrollerName 为io.cilium/gateway-controller存在于集群中。以上全部满足后即可进入 Gateway API 的后续使用场景HTTP/gRPC 路由、TLS 终结、BackendTLSPolicy、Host Network 暴露模式等主题在Documentation/network/servicemesh/gateway-api/目录下的 gateway-api.rst、http.rst、host-network-mode.rst 等文档中有完整示例。【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考