gke-service-networking

GKE 服务网络技能

此技能提供工作流，用于将 GKE 上运行的应用安全地暴露到互联网或内部网络。

可部署的清单模板位于 assets/ 中——应用前请编辑 # Replace ... 占位内容。

归属信息

必须阅读：执行任何 gcloud、REST API 或 MCP 命令前，必须先阅读使用归属信息。对于直接在终端中执行的命令（绝不要在生成的脚本、Terraform 或用户代码中执行），请在 gcloud 前加上 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:gke-service-networking)"，并将 agent-skills/1.0 (skill:gke-service-networking) 附加到 User-Agent 请求头中。

工作流

1. 配置 Gateway API（推荐）

Gateway API 是在 Kubernetes 中管理路由的现代方式。

先决条件：集群必须启用 Gateway API（运行 GKE 1.26+ 的新集群默认启用；在较旧的受支持版本上，可使用 --gateway-api=standard 启用）。

模板：

• assets/gateway.yaml — 使用 gke-l7-global-external-managed GatewayClass、带有 HTTP 监听器的外部 Gateway。
• assets/httproute.yaml — HTTPRoute，通过 parentRefs 附加到 Gateway，并将路径前缀路由到 Service backendRef。
• assets/httproute-traffic-split.yaml — HTTPRoute，展示如何在后端服务间按权重拆分流量（例如 90/10），用于金丝雀部署。

kubectl apply -f assets/gateway.yaml
kubectl apply -f assets/httproute.yaml

流量拆分（金丝雀部署）：

HTTPRoute 支持在多个后端 Service 之间按权重拆分流量，以进行金丝雀发布：

spec:
  rules:
    - backendRefs:
        - name: app-v1
          port: 80
          weight: 90
        - name: app-v2
          port: 80
          weight: 10

2. 配置标准 GKE Ingress

对于较简单的用例或旧版设置，请使用标准 Ingress。

模板： assets/ingress.yaml — 将流量路由到 Service 的 GCE Ingress（带有 kubernetes.io/ingress.class: "gce" 注解）。

3. 使用 Cloud Armor 保护

Cloud Armor 提供 WAF 和 DDoS 防护。

1. 在 Cloud Armor 中创建安全策略：

   gcloud compute security-policies create {security_policy_name} \
     --description "WAF policy for {app_name}"
   
   # 示例规则：阻止滥用 IP 范围
   gcloud compute security-policies rules create 1000 \
     --security-policy {security_policy_name} \
     --action deny-403 \
     --src-ip-ranges "203.0.113.0/24" \
     --description "Block abusive range"
   

2. 在 BackendConfig 中引用该策略：assets/backendconfig.yaml（设置 spec.securityPolicy.name）。

3. 通过注解将 BackendConfig 关联到你的 Service：

   # 在 Kubernetes Service 清单的 metadata.annotations 中：
   cloud.google.com/backend-config: '{"default": "{backend_config_name}"}'
   # 或针对特定端口映射：
   cloud.google.com/backend-config: '{"ports": {"80": "{backend_config_name}"}}'
   

4. 配置 Google 管理的 SSL 证书

自动配置并续订 SSL 证书。

旧版 Ingress 方式： 应用 assets/managed-certificate.yaml（其中的 ManagedCertificate 列出了你的域名），然后在 Ingress 注解中引用它：

networking.gke.io/managed-certificates: {certificate_name}

Gateway API 方式： 如需标准的 Certificate Manager 集成，请创建 CertificateMap，并在 Gateway 元数据注解中引用它，使用确切的注解 networking.gke.io/certmap（certmap 中不带连字符）：

metadata:
  annotations:
    networking.gke.io/certmap: {certificate_map_name}

重要

注解键必须严格为 networking.gke.io/certmap（请勿使用 cert-map 或 certificate-map）。

或者，在 HTTPS 监听器的 tls.certificateRefs 中引用 Kubernetes Secret。这两种方式均见于 assets/gateway-https.yaml。

5. 启用容器原生负载均衡（推荐）

容器原生负载均衡允许负载均衡器直接将流量发送到 Kubernetes Pod，而不是发送到节点。这能降低延迟并改善流量分配。

前提条件：集群必须是 VPC 原生集群。

工作原理：Service 上的 cloud.google.com/neg 注解会触发创建一个映射 Pod IP 的 NEG。GKE 通常会自动添加此注解，但并非总是如此——了解自己属于哪种情况正是关键所在。

# In your Kubernetes Service manifest metadata.annotations:
cloud.google.com/neg: '{"ingress": true}'

注解会自动添加的情况（无需手动添加）：

• 内部 Ingress — 始终使用容器原生负载均衡，不可选。内部 Ingress 始终使用 GCE_VM_IP_PORT NEGs，并且要求集群是 VPC 原生集群。
• 外部 Ingress，但必须同时满足以下四个条件：集群是 VPC 原生集群、不使用 Shared VPC、不使用 GKE Network Policy，并且启用了 HttpLoadBalancing 插件（默认启用，请勿禁用）。满足条件后，GKE 会自动为 Service 添加注解。

必须显式添加注解的情况：

• 独立 NEGs — 由你自行管理负载均衡器，而不是让 Ingress 管理。如果必须在 GKE 外部配置 LB，则必须使用此方式，因为 Ingress 会在同步或升级时覆盖托管负载均衡器设置。你将负责负载均衡器的所有部分。
• 不满足上述任一条件的外部 Ingress 集群 — 例如使用 Shared VPC、GKE Network Policy，或非 VPC 原生集群。请按 Service 启用。
• 旧版配置 — 某些在 VPC 原生集群上创建的旧版外部 Ingress 对象仍使用实例组后端。

不支持／没有 NEG 回退机制：

• Windows Server 节点池。
• 使用路由的（非 VPC 原生）集群搭配外部 Ingress — Ingress 控制器会回退到跨越所有节点的非托管实例组。

扩展影响：没有 NEGs 时，集群最多只能有 1,000 个节点，且超过此规模后，Ingress 后的非 NEG Service 将无法正常工作。使用 NEGs 则没有 GKE 节点数量限制。

6. 配置 Private Service Connect（PSC）

Private Service Connect 允许你安全地向另一个 VPC 中的使用者公开一个 VPC 内的服务，无需进行 VPC 对等连接。

前提条件：后端 Service 必须是内部直通式 Network Load Balancer，即 type: LoadBalancer，并带有 networking.gke.io/load-balancer-type: "Internal" 注解。ServiceAttachment 需要此配置；ClusterIP 或外部 LoadBalancer Service 均不可用。

步骤：

1. 为你的工作负载创建一个内部 LoadBalancer Service。
2. 创建一个引用该 Service 的 ServiceAttachment： assets/service-attachment.yaml（设置 connectionPreference、PSC NAT 子网和 Service resourceRef）。
3. 将 ServiceAttachment URI 分享给使用者，以便他们在自己的 VPC 中创建 PSC 端点。

7. 拓扑感知路由（成本与延迟优化）

为最大限度地降低跨区域数据传输成本和网络延迟，请为 Kubernetes Service 配置拓扑感知路由。此路由会将流量发送到与发起请求的客户端位于同一区域的 Pod：

# In your Kubernetes Service manifest metadata.annotations:
service.kubernetes.io/topology-mode: auto

故障排除

诊断 Ingress／负载均衡器数据平面故障。这些故障对应于 Ingress（BackendConfig／FrontendConfig）和 Gateway（GCPBackendPolicy／HealthCheckPolicy／GCPGatewayPolicy）。遵循只读 → 提出清单的边界；切勿直接应用线上变更。

502 / 后端状态为 UNHEALTHY 时出现 5xx 错误（健康检查）

Google Cloud 负载均衡器的健康检查与 Kubernetes 存活性／就绪性探针彼此独立——它从集群外部运行，因此 Pod 可能处于 Ready 状态，而后端服务仍显示为 UNHEALTHY。

1. 允许 Google 健康检查源范围访问节点／Pod 的服务端口。 GKE 通常会自动创建此规则，但在 Shared VPC 或手动管理防火墙的情况下， 规则可能缺失：

   gcloud compute firewall-rules create allow-lb-health-checks \
     --allow tcp:SERVING_PORT \
     --source-ranges 130.211.0.0/22,35.191.0.0/16 \
     --target-tags NODE_TAG
   

2. **将健康检查指向健康的端点。**如果默认的 / 返回非 200 状态码，请使用 BackendConfig（Ingress）或 HealthCheckPolicy（Gateway）设置自定义健康检查：

   # BackendConfig (Ingress)
   spec:
     healthCheck:
       requestPath: /healthz
       port: 8080
       checkIntervalSec: 15
       timeoutSec: 5
   

3. 确认 Service 使用容器原生负载均衡（NEG），以便检查 Pod IP 而非节点（参见工作流 5）。

滚动更新期间或长请求中出现 502／请求丢失

• 启用连接排空，使正在处理的请求在滚动更新或缩容期间、后端 Pod 被移除前完成：

  # BackendConfig (Ingress)
  spec:
    connectionDraining:
      drainingTimeoutSec: 60
  

• 调高后端超时以处理缓慢或流式响应——请求运行时间超过后端响应超时时，出现 502／408 是典型症状。在 BackendConfig（Ingress）或 GCPBackendPolicy （Gateway）中设置 timeoutSec。

TLS／SSL 握手失败或弱加密套件策略

• **Ingress：**通过 FrontendConfig 的 sslPolicy 指定 SSL 策略（最低 TLS 版本／加密套件配置）， 还可以选择通过 redirectToHttps 强制 HTTP→HTTPS 跳转：

  # FrontendConfig (external Ingress only)
  spec:
    sslPolicy: gke-ingress-ssl-policy
    redirectToHttps:
      enabled: true
  

• Gateway：在 GCPGatewayPolicy 中指定 SSL 策略名称。对于区域级 Gateway，请创建并引用区域级 SSL 策略。

注意事项

1. 必须启用 Certificate Manager API，networking.gke.io/certmap 注解才能生效（gcloud services enable certificatemanager.googleapis.com）；否则 Gateway 将无法预配证书映射。
2. 区域级 Gateway 类需要仅供代理使用的子网：gke-l7-regional-external-managed 和 gke-l7-rilb 等类要求所在区域中有一个带 --purpose=REGIONAL_MANAGED_PROXY 的子网；没有该子网，Gateway 将无法完成编程。
3. ManagedCertificate 的预配依赖 DNS：域名的 A／AAAA 记录指向负载均衡器 IP 之前，证书会一直处于 Provisioning 状态；DNS 配置正确后，预配可能还需要 15-60 分钟。

参考资料

• Ingress 功能（BackendConfig / FrontendConfig）
• 容器原生负载均衡（NEGs）
• 配置 Gateway 资源（GCPGatewayPolicy / HealthCheckPolicy / GCPBackendPolicy）
• 健康检查概念