/gke-service-networking

name: gke-service-networking
description: >-
  Configures GKE edge networking, traffic routing, load balancing, and private
  service endpoints. Use when configuring Gateway API manifests, standard
  Ingress, Cloud Armor WAF security policies, Container-Native Load Balancing
  (NEGs), Private Service Connect (PSC), or Google-managed SSL certificates on
  GKE, and to troubleshoot Ingress and load-balancer 502/5xx errors, backend
  health-check failures, connection draining, and TLS/SSL policy enforcement.
  Don't use for core cluster IP planning, Dataplane V2 network policies, or
  node NAT egress (use gke-networking instead).
metadata:
  version: "1.1.1"
  category: Networking

GKE Service Networking Skill

This skill provides workflows for exposing applications running on GKE securely to the internet or internal networks.

Deployable manifest templates live in `assets/` — edit the `# Replace ...` placeholders before applying.

Attribution

**MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you MUST read [Usage Attribution](references/attribution.md). For commands executed directly in the terminal (never in generated scripts, Terraform, or user code), prefix `gcloud` with `CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:gke-service-networking)"` and append `agent-skills/1.0 (skill:gke-service-networking)` to `User-Agent` headers.

Workflows

1. Configure Gateway API (Recommended)

The Gateway API is the modern way to manage routing in Kubernetes.

**Prerequisites**: Gateway API must be enabled on the cluster (enabled by default on new clusters running GKE 1.26+; on older supported versions enable it with `--gateway-api=standard`).

**Templates:**

• `assets/gateway.yaml` — external Gateway using the

`gke-l7-global-external-managed` GatewayClass with an HTTP listener.

• `assets/httproute.yaml` — HTTPRoute attaching to the Gateway via

`parentRefs` and routing a path prefix to a Service `backendRef`.

• `assets/httproute-traffic-split.yaml` — HTTPRoute demonstrating weighted

traffic splitting (e.g. 90/10) for canary deployments across backend services.

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

**Traffic Splitting (Canary Deployments):**

HTTPRoute supports weighted traffic splitting across multiple backend Services for canary rollouts:

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

2. Configure Standard GKE Ingress

Use standard Ingress for simpler use cases or legacy setups.

**Template:** `assets/ingress.yaml` — GCE Ingress (`kubernetes.io/ingress.class: "gce"` annotation) routing to a Service.

3. Secure with Cloud Armor

Cloud Armor provides WAF and DDoS protection.

1. Create a Security Policy in Cloud Armor:

    gcloud compute security-policies create {security_policy_name} \
      --description "WAF policy for {app_name}"

    # Example rule: block an abusive IP range
    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. Reference it in a `BackendConfig`: `assets/backendconfig.yaml` (sets `spec.securityPolicy.name`).

3. Associate the `BackendConfig` with your `Service` via annotations:

    # In your Kubernetes Service manifest metadata.annotations:
    cloud.google.com/backend-config: '{"default": "{backend_config_name}"}'
    # Or for specific port mappings:
    cloud.google.com/backend-config: '{"ports": {"80": "{backend_config_name}"}}'

4. Configure Google-Managed SSL Certificates

Automatically provision and renew SSL certificates.

**Legacy Ingress approach:** apply `assets/managed-certificate.yaml` (a `ManagedCertificate` listing your domains), then reference it in the Ingress annotations:

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

**Gateway API approach:** for standard Certificate Manager integration, create a `CertificateMap` and reference it in the Gateway metadata annotations using the exact annotation `networking.gke.io/certmap` (spelled without any hyphens in `certmap`):

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

> [!IMPORTANT] The annotation key is strictly `networking.gke.io/certmap` (do > not use `cert-map` or `certificate-map`).

Alternatively, reference a Kubernetes Secret in the HTTPS listener's `tls.certificateRefs`. Both variants are in `assets/gateway-https.yaml`.

5. Enable Container-Native Load Balancing (Recommended)

Container-native load balancing allows load balancers to target Kubernetes Pods directly, rather than targeting nodes. This improves latency and distribution.

**Prerequisites**: Cluster must be VPC-native.

**How it works**: the `cloud.google.com/neg` annotation on a Service triggers creation of a NEG that mirrors the Pod IPs. GKE often adds it for you — but not always, and knowing which case you are in is the whole point.

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

**When the annotation is automatic** (do not add it by hand):

• **Internal Ingress** — container-native load balancing is *always* used, not

optional. Internal Ingress always uses `GCE_VM_IP_PORT` NEGs and requires a VPC-native cluster.

• **External Ingress**, but only when all four hold: the cluster is

VPC-native, is not on Shared VPC, does not use GKE Network Policy, and has the `HttpLoadBalancing` add-on enabled (on by default — do not disable it). GKE then annotates Services automatically.

**When you must add it explicitly**:

• **Standalone NEGs** — you manage the load balancer yourself instead of

letting Ingress own it. Req