Configure GKE Granular NAT

This document shows you how to configure Google Kubernetes Engine (GKE) Granular NAT to assign dedicated egress IP addresses to specific Kubernetes namespaces.

With Granular NAT, you can configure specific source external IP addresses for public NAT, or you can configure specific source internal IP addresses for private NAT, powered by Cloud NAT gateways.

To configure Granular NAT, you declare your routing policies using two cluster-scoped custom resources:

  • CloudNATGateway: use this resource to provision a new public or private Cloud NAT gateway for your cluster or to configure your cluster to use an existing Cloud NAT gateway. The Cloud NAT gateway must be located in your cluster's region and VPC network.
  • TrafficSelector: use this resource to define your egress routing rules by mapping source namespaces (namespaceSelector) and destination CIDRs to a target CloudNATGateway.

Before you begin

Before you configure GKE Granular NAT, complete the following prerequisites:

  • Verify cluster requirements: verify that your VPC-native cluster is running GKE version 1.37.1-gke.2611000 or later with GKE Dataplane V2 enabled. GKE Granular NAT is supported on both Autopilot and Standard clusters, and on both regional and zonal clusters.
  • Verify IAM permissions:
    • Verify that you have the Kubernetes Engine Admin (roles/container.admin) role on the cluster to apply custom resources.
    • If using Shared VPC: the host project administrator must grant your service project's GKE service agent (service-SERVICE_PROJECT_NUMBER@container-engine-robot.s3ns-system.iam.gserviceaccount.com) the Compute Network Admin (roles/compute.networkAdmin) role in the IAM policy of the host project. This role allows GKE to create and manage the underlying Cloud NAT gateways, Cloud Routers, and IP addresses in the Shared VPC network. Standalone VPC networks don't require this manual grant.
  • Update firewall rules to include Link-Local IP addresses if necessary: before outbound packets leave a node, GKE Granular NAT translates their source IP address to a Link-Local address in the 169.254.32.0/20 range. If your organization enforces strict custom firewall rules, verify that your rules accommodate this behavior:
    • Egress rules: avoid specifying a source parameter in egress allow rules whose targets are cluster nodes. If you do specify a source parameter, you must include the Link-Local address range (169.254.32.0/20).
    • Ingress rules: avoid specifying the destination parameter in ingress allow rules whose targets are cluster nodes. If you do specify a destination parameter, you must include the Link-Local address range (169.254.32.0/20).
  • Intra-VPC traffic: ensure that TrafficSelector resources don't include destination CIDRs of subnet ranges within the cluster's VPC network or another VPC network connected using VPC Network Peering. Private NAT only provides connectivity for NCC spokes or connectivity using hybrid NAT.
  • VPC route requirements: for each CIDR to be handled by public NAT, the cluster's VPC network must include a static route whose destination range includes the CIDR and whose next hop is the default internet gateway.

Limitations

  • Namespace-level granularity: you can apply GKE Granular NAT policies only at the Kubernetes namespace level. For the preview release, you cannot select individual Pods or Service Accounts by using label selectors within a namespace.
  • Gateway rule capacity: each Cloud NAT gateway supports up to 128 NAT rules, which lets you configure policies for up to 128 distinct GKE namespaces per gateway. If your cluster requires egress policies for more than 128 namespaces, you must provision additional gateways.
  • Cloud NAT limitations: review the standard Cloud NAT limitations, as they also apply to your Granular NAT egress traffic. For more information, see the limitations for Public NAT and Private NAT.

Enable GKE Granular NAT on a cluster

You can enable Granular NAT when you create a new cluster, or you can update an existing cluster.

Create a new cluster

Autopilot

To create a new cluster with Granular NAT and GKE Dataplane V2 enabled, run the following command:

gcloud container clusters create-auto "CLUSTER_NAME" \
    --LOCATION_FLAG="LOCATION" \
    --network="VPC_NETWORK_NAME" \
    --enable-granular-nat \
    --network-suite=STANDARD

Replace the following:

  • CLUSTER_NAME: the name of your new cluster.
  • LOCATION_FLAG: specify --region for a regional cluster.
  • LOCATION: the Compute Engine region or zone for your cluster (for example, us-central1 or us-central1-a).
  • VPC_NETWORK_NAME: the name of your VPC network.

Standard

To create a new cluster with Granular NAT and GKE Dataplane V2 enabled, run the following command:

gcloud container clusters create <var>CLUSTER_NAME</var> \
    --LOCATION_FLAG="LOCATION" \
    --network="VPC_NETWORK_NAME" \
    --enable-dataplane-v2 \
    --enable-granular-nat \
    --network-suite=STANDARD

Replace the following:

  • CLUSTER_NAME: the name of your new cluster.
  • LOCATION_FLAG: specify --region for a regional cluster or --zone for a zonal cluster.
  • LOCATION: the Compute Engine region or zone for your cluster (for example, us-central1 or us-central1-a).
  • VPC_NETWORK_NAME: the name of your VPC network.

Update an existing cluster

Autopilot

To enable Granular NAT on an existing cluster, run the following command:

gcloud container clusters update `CLUSTER_NAME` \
    --LOCATION_FLAG="LOCATION" \
    --enable-granular-nat

Replace the following:

  • CLUSTER_NAME: the name of your existing cluster.
  • LOCATION_FLAG: specify --region if your existing cluster is regional or --zone if it is zonal.
  • LOCATION: the Compute Engine region or zone where your cluster is located.

Standard

To enable Granular NAT on an existing Standard cluster, run the following command:

gcloud container clusters update `CLUSTER_NAME` \
    --LOCATION_FLAG="LOCATION" \
    --enable-granular-nat \
    --network-suite=STANDARD

Replace the following:

  • CLUSTER_NAME: the name of your existing cluster.
  • LOCATION_FLAG: specify --region if your existing cluster is regional or --zone if it is zonal.
  • LOCATION: the Compute Engine region or zone where your cluster is located.

Configure public Granular NAT with static external egress IP addresses

Configure public Granular NAT when workloads in separate namespaces must present distinct, static public IP addresses to external third-party services, such as partner APIs or payment gateways that enforce strict IP address allowlists.

  1. Create a regional Cloud Router for your Cloud NAT gateway. GKE does not automatically create the Cloud Router for you.

    gcloud compute routers create ROUTER_NAME \
        --network=VPC_NETWORK_NAME \
        --region=REGION
    

    Replace the following:

    • ROUTER_NAME: the name of your new regional Cloud Router.
    • VPC_NETWORK_NAME: the name of your VPC network.
    • REGION: the Compute Engine region where your cluster is located (for example, us-central1).
  2. Reserve static external IP addresses in the same region as your GKE cluster to allocate dedicated external egress IP addresses for your namespaces, as well as a default IP address for the gateway:

    gcloud compute addresses create nat-ip-default \
        --region=REGION
    gcloud compute addresses create nat-ip-1 \
        --region=REGION
    gcloud compute addresses create nat-ip-2 \
        --region=REGION
    

    Replace REGION with the Compute Engine region where your cluster is located (for example, us-central1).

  3. Save the following manifest as cloud-nat-public.yaml to define a managed regional Cloud NAT gateway:

    kind: CloudNATGateway
    apiVersion: networking.gke.io/v1
    metadata:
      name: cloud-nat-public-managed
    spec:
      type: Public
      cloudRouter:
        name: projects/PROJECT_ID/regions/REGION/routers/ROUTER_NAME
      publicNATOptions:
        defaultNatExternalIPs:
        - name: nat-ip-default
      connectionOptions:
        udpTimeoutSeconds: 30
        tcpEstablishedTimeoutSeconds: 1200
        tcpTransitoryTimeoutSeconds: 30
        tcpTimeWaitSeconds: 120
        icmpTimeoutSeconds: 30
      portOptions:
        minPortsPerVM: 32
        maxPortsPerVM: 65536
      logOptions:
        enable: true
        filter: ALL
    

    Replace the following:

    • PROJECT_ID: your Cloud de Confiance project ID.
    • REGION: the Compute Engine region where your cluster and Cloud Router are located.
    • ROUTER_NAME: the name of your Cloud Router.
  4. Save the following manifest as traffic-selectors-public.yaml to map each target namespace to its designated public NAT IP address:

    kind: TrafficSelector
    apiVersion: networking.gke.io/v2
    metadata:
      name: ns-red-public-route
      annotations:
        cloud.google.com/cloud-nat: '{"nat-external-ips":"nat-ip-1"}'
    spec:
      action:
        kind: CloudNATGateway
        name: cloud-nat-public-managed
      subject:
        pods:
          namespaceSelector:
            matchLabels:
              app: namespace-red-app
      egress:
        to:
          ipBlock:
            cidrs:
            - 0.0.0.0/0
    ---
    kind: TrafficSelector
    apiVersion: networking.gke.io/v2
    metadata:
      name: ns-green-public-route
      annotations:
        cloud.google.com/cloud-nat: '{"nat-external-ips":"nat-ip-2"}'
    spec:
      action:
        kind: CloudNATGateway
        name: cloud-nat-public-managed
      subject:
        pods:
          namespaceSelector:
            matchLabels:
              app: namespace-green-app
      egress:
        to:
          ipBlock:
            cidrs:
            - 0.0.0.0/0
    

    In these manifests:

    • The cloud.google.com/cloud-nat annotation specifies which reserved static external IP address translates egress traffic for the matched namespace.
    • The namespaceSelector.matchLabels field matches the labels applied to your target Kubernetes namespaces.
    • The egress.to.ipBlock.cidrs list containing 0.0.0.0/0 directs all outbound internet traffic through the designated Cloud NAT gateway.
  5. Apply both manifests to your cluster:

    kubectl apply -f cloud-nat-public.yaml -f traffic-selectors-public.yaml
    

GKE automatically provisions the Cloud NAT gateway, configures the translation rules based on your namespace workload selectors, and assigns the reserved external IP addresses.

Configure private Granular Cloud NAT for VPC or NCC connectivity

Use private Granular Cloud NAT to assign specific internal IP address ranges for workloads connecting to on-premises networks or to other VPC spokes on an NCC hub.

  1. Create dedicated subnets with the PRIVATE_NAT purpose in your VPC network:

    gcloud compute networks subnets create private-nat-subnet-1 \
        --region=REGION \
        --network=VPC_NETWORK_NAME \
        --range=10.0.0.0/29 \
        --purpose=PRIVATE_NAT
    
    gcloud compute networks subnets create private-nat-subnet-2 \
        --region=REGION \
        --network=VPC_NETWORK_NAME \
        --range=10.0.1.0/29 \
        --purpose=PRIVATE_NAT
    

    Replace the following:

    • REGION: the Compute Engine region where your cluster is located.
    • VPC_NETWORK_NAME: the name of your VPC network.
  2. Save the following manifest as cloud-nat-private.yaml to create a private CloudNATGateway resource:

    kind: CloudNATGateway
    apiVersion: networking.gke.io/v1
    metadata:
      name: cloud-nat-private-managed
    spec:
      type: Private
      privateNATOptions:
        # Optional: Specify hubLink only if you are routing traffic through Network Connectivity Center
        hubLink: //networkconnectivity.googleapis.com/projects/PROJECT_ID/locations/global/hubs/HUB_NAME
      cloudRouter:
        name: projects/PROJECT_ID/regions/REGION/routers/ROUTER_NAME
      connectionOptions:
        udpTimeoutSeconds: 30
        tcpEstablishedTimeoutSeconds: 1200
    

    Replace the following:

    • PROJECT_ID: your Cloud de Confiance project ID.
    • HUB_NAME: Optional. The name of your Network Connectivity Center Hub. Specify this only if you are routing traffic through Network Connectivity Center. If you are not using Network Connectivity Center, omit the privateNATOptions block entirely.
    • ROUTER_NAME: the name of your Cloud Router.
  3. Save the following manifest as traffic-selectors-private.yaml to create private TrafficSelector resources that map your namespaces to the private NAT gateway:

    kind: TrafficSelector
    apiVersion: networking.gke.io/v2
    metadata:
      name: ns-red-private-route
      annotations:
        cloud.google.com/cloud-nat: '{"nat-subnet":"private-nat-subnet-1"}'
    spec:
      action:
        kind: CloudNATGateway
        name: cloud-nat-private-managed
      subject:
        pods:
          namespaceSelector:
            matchLabels:
              app: namespace-red-app
      egress:
        to:
          ipBlock:
            cidrs:
            - 10.200.0.0/24
    ---
    kind: TrafficSelector
    apiVersion: networking.gke.io/v2
    metadata:
      name: ns-green-private-route
      annotations:
        cloud.google.com/cloud-nat: '{"nat-subnet":"private-nat-subnet-2"}'
    spec:
      action:
        kind: CloudNATGateway
        name: cloud-nat-private-managed
      subject:
        pods:
          namespaceSelector:
            matchLabels:
              app: namespace-green-app
      egress:
        to:
          ipBlock:
            cidrs:
            - 10.200.1.0/24
    
  4. Apply the private NAT configuration:

    kubectl apply -f cloud-nat-private.yaml -f traffic-selectors-private.yaml
    

Use an existing Cloud NAT gateway

If you manage multiple GKE clusters in the same VPC network or have clusters that share secondary Pod IP address ranges, you can configure Granular NAT to use an existing Cloud NAT gateway in the same region and VPC network. This configuration lets workloads across separate clusters present a unified pool of source external IP addresses when connecting to external endpoints.

  1. List the existing Cloud NAT gateways in your region to identify an existing gateway's name, associated Cloud Router, and VPC network. The region and VPC network must match those used by the GKE clusters:

    gcloud beta compute routers nats list \
        --router=ROUTER_NAME \
        --region=REGION \
        --format=yaml
    

    Replace the following:

    • ROUTER_NAME: the name of the Cloud Router managing the existing gateway.
    • REGION: the Compute Engine region where your cluster and existing gateway are located (for example, us-central1).
  2. Save the following manifest as cloud-nat-shared.yaml to link your cluster to the existing gateway:

    kind: CloudNATGateway
    apiVersion: networking.gke.io/v1
    metadata:
      name: cloud-nat-public-shared
    spec:
      type: Public # type is a required field even for shared gateways. Can be either Public or Private.
      gatewayName: SHARED_NAT_GATEWAY_NAME
      cloudRouter:
        name: projects/PROJECT_ID/regions/REGION/routers/ROUTER_NAME
    

    Replace the following:

    • SHARED_NAT_GATEWAY_NAME: the name of the existing Cloud NAT gateway.
    • PROJECT_ID: your Cloud de Confiance project ID.
    • REGION: the Compute Engine region where your cluster and existing gateway are located.
    • ROUTER_NAME: the name of the regional Cloud Router managing the existing gateway.
  3. Save the following manifest as traffic-selector-shared.yaml to route outbound traffic from your namespace through the shared gateway:

    kind: TrafficSelector
    apiVersion: networking.gke.io/v2
    metadata:
      name: ns-shared-public-route
      annotations:
        cloud.google.com/cloud-nat: '{"nat-external-ips":"NAT_IP_NAME"}'
    spec:
      action:
        kind: CloudNATGateway
        name: cloud-nat-public-shared
      subject:
        pods:
          namespaceSelector:
            matchLabels:
              app: NAMESPACE_APP_LABEL
      egress:
        to:
          ipBlock:
            cidrs:
            - 0.0.0.0/0
    

    Replace the following:

    • NAT_IP_NAME: the name of the reserved external static IP address configured on the shared gateway.
    • NAMESPACE_APP_LABEL: the label applied to your target Kubernetes namespace.
  4. Apply the manifests to each GKE cluster that needs to share the gateway:

    kubectl apply -f cloud-nat-shared.yaml -f traffic-selector-shared.yaml
    

    Repeat this step on each cluster where workloads in the selected namespace must egress through the shared gateway.

Clean up and deactivate Granular NAT

To avoid ongoing billing charges and prevent orphaned Cloud de Confiance by S3NS resources, follow a strict order of operations when you remove Granular NAT from your cluster.

To clean up Granular NAT resources, complete the following steps:

  1. Delete user-created TrafficSelector resources:

    Delete the TrafficSelector custom resources that you created for your namespaces. Don't use the --all flag, because deleting system-created selectors (such as gnat-intra-cluster or gnat-default-internet) can break cluster traffic.

    kubectl delete trafficselector SELECTOR_NAME
    

    Replace SELECTOR_NAME with the name of the TrafficSelector resource.

    The Granular NAT controllers coordinate with Cloud de Confiance by S3NS networking to delete the specific NAT rules and workload mappings associated with your namespaces.

    Verify that all TrafficSelector resources have completed termination before you proceed.

  2. Delete CloudNATGateway resources:

    Delete all CloudNATGateway custom resources in the cluster:

    kubectl delete cloudnatgateway --all
    
    • Managed gateways: GKE automatically deletes the underlying Cloud NAT gateway in Cloud de Confiance by S3NS after all translation rules are removed.
    • Shared gateways: GKE cleans up the relevant NAT rules associated with your namespaces. GKE does not remove your cluster's secondary Pod IP address associations, and the shared Cloud NAT gateway remains active for other clusters.
  3. Disable the feature on the cluster:

    After all Granular NAT custom resources are completely removed, disable the feature on your cluster:

    gcloud container clusters update CLUSTER_NAME \
        --location=LOCATION \
        --no-enable-granular-nat
    

    Replace the following:

    • CLUSTER_NAME: the name of your cluster.
    • LOCATION: the Compute Engine region or zone where your cluster is located (for example, us-central1 or us-central1-a).

Troubleshooting

If you experience connectivity issues, use the following methods to diagnose Granular NAT configuration and data plane failures.

Verify resource status and logs

  • Inspect custom resource status: check for error conditions on your CloudNATGateway or TrafficSelector custom resources:

    kubectl describe cloudnatgateway GATEWAY_NAME
    kubectl describe trafficselector SELECTOR_NAME
    

    Replace the following:

    • GATEWAY_NAME: the name of your CloudNATGateway resource.
    • SELECTOR_NAME: the name of your TrafficSelector` resource.
  • Review Cloud NAT rules: Verify that the GKE workload selector rules are active on the underlying Cloud NAT gateway:

    gcloud beta compute routers nats rules list \
        --router=ROUTER_NAME \
        --nat=NAT_NAME \
        --region=REGION \
        --format=yaml
    

    Replace the following:

    • ROUTER_NAME: the name of your regional Cloud Router.
    • NAT_NAME: the name of your Cloud NAT gateway.
    • REGION: the Compute Engine region where your resources are located.
  • Analyze Cloud NAT logs: if egress traffic is dropped or fails to translate, view the Cloud NAT log entries in Cloud Logging. Filter for the gke_workload_identity field to correlate connection events directly to specific GKE namespaces.

For more information about diagnosing general Cloud NAT errors, see Troubleshooting Cloud NAT.

What's next