Cilium Gateway API 参数化 GatewayClass用 CiliumGatewayClassConfig 定制网关 Service、gRPC-web 与 Server 头行为【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium本文围绕 Cilium Gateway API 的参数化 GatewayClass 机制展开讲解如何通过CiliumGatewayClassConfigCRD 向 GatewayClass 注入参数从而改变其管理的 Gateway 的默认行为——包括把入口 Service 从默认的LoadBalancer切换为NodePort、关闭 Envoy 的 gRPC-web 到 gRPC 请求转换以及控制 HTTPServer响应头的处理方式。读完本文你可以掌握这套GatewayClass 级配置的完整用法理解每个参数在源码与 CRD 中的定义、默认值与生效位置并能复现 NodePort 网关的部署与验证流程。核心概念GatewayClass 的 parametersRef 与 CiliumGatewayClassConfigGateway API 允许实现方通过 GatewayClass 的parametersRef字段接收实现方特有的配置。Cilium 的 Gateway 控制器controllerName: io.cilium/gateway-controller接收的参数类型就是CiliumGatewayClassConfigCRDciliumgatewayclassconfigs.cilium.io。其使用模型是先创建一个命名空间作用域scope: Namespaced的CiliumGatewayClassConfig对象在GatewayClass.spec.parametersRef中引用它group: cilium.io、kind: CiliumGatewayClassConfig所有使用该 GatewayClass 的 Gateway 都会继承这套配置。参数化的意义在于不同业务场景可以用不同的 GatewayClass 复用同一套 Gateway/HTTPRoute 路由定义只通过 class 级参数调整入口 Service 形态与代理行为而不需要逐个 Gateway 修改。源码层面的类型定义位于 gatewayclassconfig_types.goAPI 组为cilium.io/v2alpha1短名为cgcc并带有一个Accepted列的 printer column.status.conditions[?(.typeAccepted)].status可直接通过kubectl get cgcc观察控制器是否已接受该配置。实战部署 NodePort 类型的 Cilium Gateway官方示例gateway-with-parameters.yaml演示了把 Cilium Gateway 的入口 Service 从默认的LoadBalancer改为NodePort。示例基于 Istio 项目 bookinfo 演示应用的微服务拓扑。资源清单清单包含 4 个对象完整内容如下--- apiVersion: gateway.networking.k8s.io/v1 kind: GatewayClass metadata: name: nodeport-gateway-class spec: controllerName: io.cilium/gateway-controller description: The default Cilium GatewayClass parametersRef: group: cilium.io kind: CiliumGatewayClassConfig name: nodeport-gateway-config namespace: default --- apiVersion: cilium.io/v2alpha1 kind: CiliumGatewayClassConfig metadata: name: nodeport-gateway-config namespace: default spec: service: type: NodePort --- apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: name: nodeport-gateway spec: gatewayClassName: nodeport-gateway-class listeners: - protocol: HTTP port: 80 name: web-gw allowedRoutes: namespaces: from: Same --- apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: http-app-1 spec: parentRefs: - name: nodeport-gateway namespace: default rules: - matches: - path: type: PathPrefix value: /details backendRefs: - name: details port: 9080关键说明GatewayClass的parametersRef指向default/nodeport-gateway-config注意namespace字段是必填的——operator 在解析时如果缺少 name 或 namespace 会直接拒绝。该逻辑见 gateway_reconcile.gospec.parametersRef.kind不是CiliumGatewayClassConfig时Gateway 会被标记AcceptedFalsereason 为InvalidParametersparametersRef缺少 name 或 namespace 时同样以InvalidParameters拒绝。另外Gateway.spec.infrastructure.parametersRef目前不受支持设置后 Gateway 也会被置为AcceptedFalsegateway_reconcile.go。CiliumGatewayClassConfig.spec.service.type: NodePort决定了为该 Gateway 生成的 Service 的类型。从源码类型定义看ServiceConfig.Type的枚举只允许LoadBalancer与NodePort两种且默认值为LoadBalancergatewayclassconfig_types.go——CRD 注释也明确Only LoadBalancer and NodePort are supported。Gateway声明了一个监听 80 端口的 HTTP listenerweb-gw只允许本命名空间的 HTTPRoute 绑定allowedRoutes.namespaces.from: SameHTTPRoute将前缀/details路由到 bookinfo 的details:9080后端。应用与验证应用配置$ kubectl apply -f examples/kubernetes/gateway/gateway-with-parameters.yamlGateway 部署完成后可以确认生成的 Service 是 NodePort 类型$ kubectl get services cilium-gateway-nodeport-gateway NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE cilium-gateway-nodeport-gateway NodePort 10.96.45.118 none 80:30493/TCP 11s随后 SSH 到任意一个 Kubernetes 节点通过 NodePort 端口访问路由rootkind-worker:/# curl http://localhost:30493/details/1 {id:1,author:William Shakespeare,year:1595,type:paperback,pages:200,publisher:PublisherA,language:English,ISBN-10:1234567890,ISBN-13:123-1234567890}返回 bookinfodetails服务的数据说明整条链路NodePort Service → Gateway listener → HTTPRoute → 后端 Pod工作正常。关闭 gRPC-web 翻译Cilium Gateway API 默认开启 Envoy 的 gRPC-web 到 gRPC 请求转换translation。如果你希望 gRPC-web 请求原样透传、不做翻译可以把httpOptions.grpcWebTranslation.enabled设为falseapiVersion: cilium.io/v2alpha1 kind: CiliumGatewayClassConfig metadata: name: grpc-web namespace: default spec: httpOptions: grpcWebTranslation: enabled: false参数语义与默认值在源码中可以得到印证GRPCWebTranslationConfig.Enabled是一个指针布尔kubebuilder 默认值为truegatewayclassconfig_types.go。类型上还提供了一个判定辅助函数GRPCWebTranslationEnabled()gatewayclassconfig_types.go其逻辑是除非显式禁用否则翻译始终启用——即配置对象不存在、httpOptions不存在、grpcWebTranslation不存在、或enabled为 nil 时均返回true。这意味着只有明确写enabled: false才会关闭翻译且由于该参数挂在 GatewayClass 上它对使用该 GatewayClass 的全部 Gateway 生效。Server 响应头转换ServerHeaderTransformationCilium Gateway API 还支持控制 Envoy 对 HTTPServer响应头的处理对应 Envoy 的ServerHeaderTransformation共三种模式gatewayclassconfig_types.go取值行为是否默认OVERWRITE用envoy覆盖已有的 Server 头是APPEND_IF_ABSENT响应中没有 Server 头时追加envoy已有则原样透传否PASS_THROUGH完全透传上游值没有 Server 头时也不追加否示例将转换模式设为PASS_THROUGH的CiliumGatewayClassConfigapiVersion: cilium.io/v2alpha1 kind: CiliumGatewayClassConfig metadata: name: test-gateway-config namespace: default spec: envoy: serverHeaderTransformation: PASS_THROUGH该字段位于 CRD 的spec.envoy.serverHeaderTransformation枚举为OVERWRITE/APPEND_IF_ABSENT/PASS_THROUGH默认OVERWRITE见 CRD 定义 ciliumgatewayclassconfigs.yaml 与类型定义 EnvoyConfig。PASS_THROUGH适合需要在响应中保留上游应用自身 Server 头信息的场景例如多层代理排障时。CiliumGatewayClassConfig 完整参数参考完整支持列表以 CRD 为准ciliumgatewayclassconfigs.yaml。spec下共有 5 个可选字段description描述该配置用途的字符串最长 64 字符会显示在kubectl get cgcc -o wide的 Description 列priority 1 列。service控制为该 Gateway 生成的 Service 对象注意并非上游 Service.Spec 的全部字段都受支持。字段类型默认值说明typeenum:LoadBalancer|NodePortLoadBalancer生成 Service 的spec.type仅此两种取值externalTrafficPolicystringCluster对应Service.Spec.ExternalTrafficPolicyloadBalancerClassstring无对应Service.Spec.LoadBalancerClassipFamiliesstring 数组IPv4/IPv6无对应Service.Spec.IPFamiliesipFamilyPolicystring无对应Service.Spec.IPFamilyPolicyallocateLoadBalancerNodePortsboolean无对应Service.Spec.AllocateLoadBalancerNodePortsloadBalancerSourceRangesstring 数组无对应Service.Spec.LoadBalancerSourceRangesloadBalancerSourceRangesPolicyenum:Allow|DenyAllow来源网段的放行/拒绝策略常量定义见 gatewayclassconfig_types.gotrafficDistributionstring无对应Service.Spec.TrafficDistributionhttpOptionsHTTP connection manager 选项目前包含grpcWebTranslation.enabled默认true见上文。telemetry可观测性选项包含accessLogs1~8 项MinItems1、MaxItems8。每项必须声明formatJSON或TextJSON字段名到 Envoy 命令操作符command operator的映射默认提供start_time、method、path、response_code、upstream_host等约 15 个字段取值限制为 1~64 个属性TextEnvoy 访问日志格式串长度 1~4096默认是经典组合日志格式两者都支持 Cilium 特有的两个格式器%CILIUM_GATEWAY_NAME%替换为 Gateway 资源名与%CILIUM_GATEWAY_NAMESPACE%替换为 Gateway 资源命名空间targets指定日志输出的代理组件HTTPEnvoy HTTP connection manager与TCPEnvoy TCP proxy含 TLS 透传默认仅{HTTP}列表为 set 语义、最少 1 项。访问日志目前写入 Envoy stdout。对应的辅助判定函数IsTelemetryConfigured()/IsAccessLogsConfigured()gatewayclassconfig_types.go供控制器判断是否需要生成访问日志配置。envoy非 Gateway API 标准的代理级配置目前含serverHeaderTransformation默认OVERWRITE见上文。status侧则维护标准的conditions数组lastTransitionTime、reason、status等必填其中Accepted条件用于反映控制器是否接受该配置gatewayClassConfigReconcilergatewayclassconfig_reconcile.go负责 watch 该资源并更新Accepted状态而 operator 侧对 Gateway 的parametersRef做合法性校验后才会把配置应用到生成的 Envoy/Service 对象上。注意事项CiliumGatewayClassConfig是alpha 版本 APIcilium.io/v2alpha1。按 Kubernetes 标准对象版本化规则alpha API 可能发生不兼容变更。如果在使用该 CRD建议仔细阅读每次发布的 release notes 中是否存在破坏性变更并在遇到问题时通过 GitHub 或 Slack 反馈使用场景与问题。小结通过GatewayClass.spec.parametersRef引用CiliumGatewayClassConfig即可在 class 级别定制 Cilium Gateway 的入口 Service如NodePort、gRPC-web 翻译开关与 Server 头行为参数默认值以 CRD/类型定义为基准Service 类型默认LoadBalancer、gRPC-web 翻译默认开启、Server 头默认OVERWRITE实现链路可追溯到 类型定义、operator 的 parametersRef 校验 与 配置 reconciler配合 NodePort 示例清单 与 CRD 清单 可直接落地验证。【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cilium Gateway API 参数化 GatewayClass：用 CiliumGatewayClassConfig 定制网关 Service、gRPC-web 与 Server 头行为
Cilium Gateway API 参数化 GatewayClass用 CiliumGatewayClassConfig 定制网关 Service、gRPC-web 与 Server 头行为【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium本文围绕 Cilium Gateway API 的参数化 GatewayClass 机制展开讲解如何通过CiliumGatewayClassConfigCRD 向 GatewayClass 注入参数从而改变其管理的 Gateway 的默认行为——包括把入口 Service 从默认的LoadBalancer切换为NodePort、关闭 Envoy 的 gRPC-web 到 gRPC 请求转换以及控制 HTTPServer响应头的处理方式。读完本文你可以掌握这套GatewayClass 级配置的完整用法理解每个参数在源码与 CRD 中的定义、默认值与生效位置并能复现 NodePort 网关的部署与验证流程。核心概念GatewayClass 的 parametersRef 与 CiliumGatewayClassConfigGateway API 允许实现方通过 GatewayClass 的parametersRef字段接收实现方特有的配置。Cilium 的 Gateway 控制器controllerName: io.cilium/gateway-controller接收的参数类型就是CiliumGatewayClassConfigCRDciliumgatewayclassconfigs.cilium.io。其使用模型是先创建一个命名空间作用域scope: Namespaced的CiliumGatewayClassConfig对象在GatewayClass.spec.parametersRef中引用它group: cilium.io、kind: CiliumGatewayClassConfig所有使用该 GatewayClass 的 Gateway 都会继承这套配置。参数化的意义在于不同业务场景可以用不同的 GatewayClass 复用同一套 Gateway/HTTPRoute 路由定义只通过 class 级参数调整入口 Service 形态与代理行为而不需要逐个 Gateway 修改。源码层面的类型定义位于 gatewayclassconfig_types.goAPI 组为cilium.io/v2alpha1短名为cgcc并带有一个Accepted列的 printer column.status.conditions[?(.typeAccepted)].status可直接通过kubectl get cgcc观察控制器是否已接受该配置。实战部署 NodePort 类型的 Cilium Gateway官方示例gateway-with-parameters.yaml演示了把 Cilium Gateway 的入口 Service 从默认的LoadBalancer改为NodePort。示例基于 Istio 项目 bookinfo 演示应用的微服务拓扑。资源清单清单包含 4 个对象完整内容如下--- apiVersion: gateway.networking.k8s.io/v1 kind: GatewayClass metadata: name: nodeport-gateway-class spec: controllerName: io.cilium/gateway-controller description: The default Cilium GatewayClass parametersRef: group: cilium.io kind: CiliumGatewayClassConfig name: nodeport-gateway-config namespace: default --- apiVersion: cilium.io/v2alpha1 kind: CiliumGatewayClassConfig metadata: name: nodeport-gateway-config namespace: default spec: service: type: NodePort --- apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: name: nodeport-gateway spec: gatewayClassName: nodeport-gateway-class listeners: - protocol: HTTP port: 80 name: web-gw allowedRoutes: namespaces: from: Same --- apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: http-app-1 spec: parentRefs: - name: nodeport-gateway namespace: default rules: - matches: - path: type: PathPrefix value: /details backendRefs: - name: details port: 9080关键说明GatewayClass的parametersRef指向default/nodeport-gateway-config注意namespace字段是必填的——operator 在解析时如果缺少 name 或 namespace 会直接拒绝。该逻辑见 gateway_reconcile.gospec.parametersRef.kind不是CiliumGatewayClassConfig时Gateway 会被标记AcceptedFalsereason 为InvalidParametersparametersRef缺少 name 或 namespace 时同样以InvalidParameters拒绝。另外Gateway.spec.infrastructure.parametersRef目前不受支持设置后 Gateway 也会被置为AcceptedFalsegateway_reconcile.go。CiliumGatewayClassConfig.spec.service.type: NodePort决定了为该 Gateway 生成的 Service 的类型。从源码类型定义看ServiceConfig.Type的枚举只允许LoadBalancer与NodePort两种且默认值为LoadBalancergatewayclassconfig_types.go——CRD 注释也明确Only LoadBalancer and NodePort are supported。Gateway声明了一个监听 80 端口的 HTTP listenerweb-gw只允许本命名空间的 HTTPRoute 绑定allowedRoutes.namespaces.from: SameHTTPRoute将前缀/details路由到 bookinfo 的details:9080后端。应用与验证应用配置$ kubectl apply -f examples/kubernetes/gateway/gateway-with-parameters.yamlGateway 部署完成后可以确认生成的 Service 是 NodePort 类型$ kubectl get services cilium-gateway-nodeport-gateway NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE cilium-gateway-nodeport-gateway NodePort 10.96.45.118 none 80:30493/TCP 11s随后 SSH 到任意一个 Kubernetes 节点通过 NodePort 端口访问路由rootkind-worker:/# curl http://localhost:30493/details/1 {id:1,author:William Shakespeare,year:1595,type:paperback,pages:200,publisher:PublisherA,language:English,ISBN-10:1234567890,ISBN-13:123-1234567890}返回 bookinfodetails服务的数据说明整条链路NodePort Service → Gateway listener → HTTPRoute → 后端 Pod工作正常。关闭 gRPC-web 翻译Cilium Gateway API 默认开启 Envoy 的 gRPC-web 到 gRPC 请求转换translation。如果你希望 gRPC-web 请求原样透传、不做翻译可以把httpOptions.grpcWebTranslation.enabled设为falseapiVersion: cilium.io/v2alpha1 kind: CiliumGatewayClassConfig metadata: name: grpc-web namespace: default spec: httpOptions: grpcWebTranslation: enabled: false参数语义与默认值在源码中可以得到印证GRPCWebTranslationConfig.Enabled是一个指针布尔kubebuilder 默认值为truegatewayclassconfig_types.go。类型上还提供了一个判定辅助函数GRPCWebTranslationEnabled()gatewayclassconfig_types.go其逻辑是除非显式禁用否则翻译始终启用——即配置对象不存在、httpOptions不存在、grpcWebTranslation不存在、或enabled为 nil 时均返回true。这意味着只有明确写enabled: false才会关闭翻译且由于该参数挂在 GatewayClass 上它对使用该 GatewayClass 的全部 Gateway 生效。Server 响应头转换ServerHeaderTransformationCilium Gateway API 还支持控制 Envoy 对 HTTPServer响应头的处理对应 Envoy 的ServerHeaderTransformation共三种模式gatewayclassconfig_types.go取值行为是否默认OVERWRITE用envoy覆盖已有的 Server 头是APPEND_IF_ABSENT响应中没有 Server 头时追加envoy已有则原样透传否PASS_THROUGH完全透传上游值没有 Server 头时也不追加否示例将转换模式设为PASS_THROUGH的CiliumGatewayClassConfigapiVersion: cilium.io/v2alpha1 kind: CiliumGatewayClassConfig metadata: name: test-gateway-config namespace: default spec: envoy: serverHeaderTransformation: PASS_THROUGH该字段位于 CRD 的spec.envoy.serverHeaderTransformation枚举为OVERWRITE/APPEND_IF_ABSENT/PASS_THROUGH默认OVERWRITE见 CRD 定义 ciliumgatewayclassconfigs.yaml 与类型定义 EnvoyConfig。PASS_THROUGH适合需要在响应中保留上游应用自身 Server 头信息的场景例如多层代理排障时。CiliumGatewayClassConfig 完整参数参考完整支持列表以 CRD 为准ciliumgatewayclassconfigs.yaml。spec下共有 5 个可选字段description描述该配置用途的字符串最长 64 字符会显示在kubectl get cgcc -o wide的 Description 列priority 1 列。service控制为该 Gateway 生成的 Service 对象注意并非上游 Service.Spec 的全部字段都受支持。字段类型默认值说明typeenum:LoadBalancer|NodePortLoadBalancer生成 Service 的spec.type仅此两种取值externalTrafficPolicystringCluster对应Service.Spec.ExternalTrafficPolicyloadBalancerClassstring无对应Service.Spec.LoadBalancerClassipFamiliesstring 数组IPv4/IPv6无对应Service.Spec.IPFamiliesipFamilyPolicystring无对应Service.Spec.IPFamilyPolicyallocateLoadBalancerNodePortsboolean无对应Service.Spec.AllocateLoadBalancerNodePortsloadBalancerSourceRangesstring 数组无对应Service.Spec.LoadBalancerSourceRangesloadBalancerSourceRangesPolicyenum:Allow|DenyAllow来源网段的放行/拒绝策略常量定义见 gatewayclassconfig_types.gotrafficDistributionstring无对应Service.Spec.TrafficDistributionhttpOptionsHTTP connection manager 选项目前包含grpcWebTranslation.enabled默认true见上文。telemetry可观测性选项包含accessLogs1~8 项MinItems1、MaxItems8。每项必须声明formatJSON或TextJSON字段名到 Envoy 命令操作符command operator的映射默认提供start_time、method、path、response_code、upstream_host等约 15 个字段取值限制为 1~64 个属性TextEnvoy 访问日志格式串长度 1~4096默认是经典组合日志格式两者都支持 Cilium 特有的两个格式器%CILIUM_GATEWAY_NAME%替换为 Gateway 资源名与%CILIUM_GATEWAY_NAMESPACE%替换为 Gateway 资源命名空间targets指定日志输出的代理组件HTTPEnvoy HTTP connection manager与TCPEnvoy TCP proxy含 TLS 透传默认仅{HTTP}列表为 set 语义、最少 1 项。访问日志目前写入 Envoy stdout。对应的辅助判定函数IsTelemetryConfigured()/IsAccessLogsConfigured()gatewayclassconfig_types.go供控制器判断是否需要生成访问日志配置。envoy非 Gateway API 标准的代理级配置目前含serverHeaderTransformation默认OVERWRITE见上文。status侧则维护标准的conditions数组lastTransitionTime、reason、status等必填其中Accepted条件用于反映控制器是否接受该配置gatewayClassConfigReconcilergatewayclassconfig_reconcile.go负责 watch 该资源并更新Accepted状态而 operator 侧对 Gateway 的parametersRef做合法性校验后才会把配置应用到生成的 Envoy/Service 对象上。注意事项CiliumGatewayClassConfig是alpha 版本 APIcilium.io/v2alpha1。按 Kubernetes 标准对象版本化规则alpha API 可能发生不兼容变更。如果在使用该 CRD建议仔细阅读每次发布的 release notes 中是否存在破坏性变更并在遇到问题时通过 GitHub 或 Slack 反馈使用场景与问题。小结通过GatewayClass.spec.parametersRef引用CiliumGatewayClassConfig即可在 class 级别定制 Cilium Gateway 的入口 Service如NodePort、gRPC-web 翻译开关与 Server 头行为参数默认值以 CRD/类型定义为基准Service 类型默认LoadBalancer、gRPC-web 翻译默认开启、Server 头默认OVERWRITE实现链路可追溯到 类型定义、operator 的 parametersRef 校验 与 配置 reconciler配合 NodePort 示例清单 与 CRD 清单 可直接落地验证。【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考