If you need to meet upstream source IP address requirements, you can use Google Kubernetes Engine (GKE) Granular NAT to control outbound traffic and egress source IP addresses at the Kubernetes namespace level. Instead of applying a single NAT policy to your entire GKE cluster, you can use specific source external IP addresses for Public NAT or a special subnet IP address range for Private NAT on a per-namespace basis. This lets you provide deterministic source IP addresses for external partners or on-premises systems without the overhead of managing custom proxy instances.
This document is for Cloud architects, Networking specialists, and Operators who enforce corporate security policies for applications connecting to external partners or on-premises systems. To learn more about common roles and example tasks, see Common GKE user roles and tasks.
Benefits
GKE Granular NAT lets you provide sets of source IP addresses for egress traffic on a per-namespace basis, along with the following benefits:
- Meet external and on-premises source IP address requirements: assign deterministic, static source IP addresses to specific namespaces. This allows upstream external partner firewalls, payment gateways, or on-premises edge security devices to allowlist traffic from individual services rather than your entire GKE cluster.
- Manage egress policies declaratively in Kubernetes: define and update
your egress routing logic directly through
kubectlby using familiar custom resource definitions (TrafficSelector and CloudNATGateway), without leaving your standard Kubernetes workflow. - Eliminate proxy and VM maintenance: avoid the operational overhead of deploying, patching, and scaling intermediate proxy Pods or custom NAT routing appliances. GKE automatically provisions and synchronizes the underlying regional Cloud NAT gateways and translation rules for you.
- Delegate responsibilities across teams: maintain clear boundaries between infrastructure and application teams. Network administrators can allocate the source IP addresses used by Cloud NAT gateways and manage gateway lifecycles, while cluster operators independently map application namespaces to those gateways by using label selectors.
Common use cases
You can use GKE Granular NAT in scenarios such as the following:
- Allowlist specific workloads with external partners: when you run multiple applications in a shared cluster but only specific services (such as a billing microservice) connect to external partner APIs, you can assign dedicated static external IP addresses to that namespace. This configuration lets your partners configure strict ingress source IP address allowlists for only that service without needing to allowlist your entire cluster.
- Connect to on-premises networks without IP address conflicts: when
workloads need to access on-premises networks or databases through
Cloud Interconnect or Network Connectivity Center in a hub-and-spoke model, you can
route egress traffic through dedicated private NAT subnet ranges (such as a
/29CIDR). This routing helps ensure workloads use predictable private IP addresses, preventing overlapping IP addresses and avoiding IP address exhaustion. - Share egress IP address pools across multiple clusters: when you manage multiple GKE clusters within the same VPC network and region that share secondary Pod IP address ranges, you can link namespaces across those clusters to a shared Cloud NAT gateway. For example, with public NAT, this integration lets workloads across multiple clusters egress through a unified pool of external IP addresses, simplifying external allowlists and compliance audits.
How GKE Granular NAT works
You configure GKE Granular NAT by declaring your routing policies. GKE uses those resources to configure a Cloud NAT gateway to route outbound traffic from selected namespaces through dedicated source IP addresses.
Custom resources
You manage Granular NAT by using two custom resources:
- CloudNATGateway (cluster scope): use this resource to define, provision,
or use an existing Cloud NAT gateway in your VPC
network. You specify whether the gateway provides
PublicorPrivateNAT, associate the gateway with a Cloud Router, and configure settings such as connection timeouts, logging, and IP address pools. - TrafficSelector (cluster scope): use this resource to define your egress
routing policies. You use a
namespaceSelectorto match source Pods, specify destination CIDR blocks (0.0.0.0/0for the internet or specific CIDR ranges for on-premises), and set theactionfield to your CloudNATGateway.
Outbound packet flow
When a Pod in a configured namespace sends traffic to an external destination, GKE and Cloud NAT route and translate the connection through the following stages:
- Workload identification: within each node, GKE Dataplane V2 associates
Pod traffic with a key-value workload selector (for example,
namespace=NAMESPACE). This association is always present, whether you use Granular NAT or not. - Node-level translation (Link-Local SNAT): on each node,
GKE Dataplane V2 evaluates outbound packets against your TrafficSelector
rules. If the packet matches your namespace and destination CIDR, eBPF
programs on the node change the source IP address from the Pod IP address
to a Link-Local IP address (in the
169.254.32.0/20range) assigned to that namespace. - Gateway policy matching: when the packet leaves the node and enters your VPC network, Cloud NAT evaluates the Link-Local source IP address against its programmed NAT rules.
Final translation and egress: Cloud NAT changes the source Link-Local IP address to an IP address associated with a rule on the Cloud NAT gateway:
For public NAT, the source IP address is changed to an external IP address assigned to the Cloud NAT gateway.
For private NAT, the source IP address is changed to an internal IP address from a private NAT subnet that's associated with the Cloud NAT gateway.