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.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.
- Verify that you have the Kubernetes Engine Admin
(
- 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/20range. 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).
- 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
(
- 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--regionfor a regional cluster.LOCATION: the Compute Engine region or zone for your cluster (for example,us-central1orus-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--regionfor a regional cluster or--zonefor a zonal cluster.LOCATION: the Compute Engine region or zone for your cluster (for example,us-central1orus-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--regionif your existing cluster is regional or--zoneif 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--regionif your existing cluster is regional or--zoneif 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.
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=REGIONReplace 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).
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=REGIONReplace
REGIONwith the Compute Engine region where your cluster is located (for example,us-central1).Save the following manifest as
cloud-nat-public.yamlto 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: ALLReplace the following:
PROJECT_ID: your Google Cloud project ID.REGION: the Compute Engine region where your cluster and Cloud Router are located.ROUTER_NAME: the name of your Cloud Router.
Save the following manifest as
traffic-selectors-public.yamlto 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/0In these manifests:
- The
cloud.google.com/cloud-natannotation specifies which reserved static external IP address translates egress traffic for the matched namespace. - The
namespaceSelector.matchLabelsfield matches the labels applied to your target Kubernetes namespaces. - The
egress.to.ipBlock.cidrslist containing0.0.0.0/0directs all outbound internet traffic through the designated Cloud NAT gateway.
- The
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.
Create dedicated subnets with the
PRIVATE_NATpurpose 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_NATReplace the following:
REGION: the Compute Engine region where your cluster is located.VPC_NETWORK_NAME: the name of your VPC network.
Save the following manifest as
cloud-nat-private.yamlto 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: 1200Replace the following:
PROJECT_ID: your Google Cloud 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 theprivateNATOptionsblock entirely.ROUTER_NAME: the name of your Cloud Router.
Save the following manifest as
traffic-selectors-private.yamlto 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/24Apply 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.
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=yamlReplace 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).
Save the following manifest as
cloud-nat-shared.yamlto 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_NAMEReplace the following:
SHARED_NAT_GATEWAY_NAME: the name of the existing Cloud NAT gateway.PROJECT_ID: your Google Cloud 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.
Save the following manifest as
traffic-selector-shared.yamlto 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/0Replace 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.
Apply the manifests to each GKE cluster that needs to share the gateway:
kubectl apply -f cloud-nat-shared.yaml -f traffic-selector-shared.yamlRepeat 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 Google Cloud 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:
Delete user-created TrafficSelector resources:
Delete the TrafficSelector custom resources that you created for your namespaces. Don't use the
--allflag, because deleting system-created selectors (such asgnat-intra-clusterorgnat-default-internet) can break cluster traffic.kubectl delete trafficselector SELECTOR_NAMEReplace
SELECTOR_NAMEwith the name of the TrafficSelector resource.The Granular NAT controllers coordinate with Google Cloud 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.
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 Google Cloud 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.
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-natReplace the following:
CLUSTER_NAME: the name of your cluster.LOCATION: the Compute Engine region or zone where your cluster is located (for example,us-central1orus-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_NAMEReplace 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=yamlReplace 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_identityfield 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
- Learn more about Cloud NAT overview.
- Refer to GKE Dataplane V2.