VPC-native clusters

Autopilot Standard

---

This page provides a general overview of VPC-native clusters in Google Kubernetes Engine (GKE).

Overview

In GKE, clusters can be distinguished according to the way they route traffic from one Pod to another Pod. A cluster that uses alias IP address ranges is called a VPC-native cluster. A cluster that uses custom static routes in a VPC network is called a routes-based cluster.

Note: For GKE Autopilot clusters, VPC-native traffic routing is enabled by default.

Benefits of VPC-native clusters

VPC-native clusters have several benefits:

• Pod IP addresses are natively routable within the cluster's VPC network and other VPC networks connected to it by VPC Network Peering.

• Pod IP addresses are reserved in the VPC network before the Pods are created in your cluster. This prevents conflict with other resources in the VPC network and allows you to better plan IP address allocations.

• Pod IP address ranges do not depend on custom static routes. They do not consume the system-generated and custom static routes quota. Instead, automatically-generated subnet routes handle routing for VPC-native clusters.

• You can create firewall rules that apply to just Pod IP address ranges instead of any IP address on the cluster's nodes.

• Pod IP address ranges, and subnet secondary IP address ranges in general, are accessible from on-premises networks connected with Cloud VPN or Cloud Interconnect using Cloud Routers.

• Some features, such as network endpoint groups (NEGs), only work with VPC-native clusters.

Default cluster network mode

VPC-native is the default network mode for all clusters in GKE versions 1.21.0-gke.1500 and later. For earlier versions, the default cluster network mode depends on how you create the cluster.

The following table lists the default cluster network mode for GKE cluster versions and cluster creation methods.

GKE versions	Cluster creation method	Cluster network mode
All versions	The Google Cloud console	VPC-native
1.21.0-gke.1500 and later	Kubernetes Engine API or Google Cloud CLI	VPC-native
Earlier than 1.21.0-gke.1500	Kubernetes Engine API or Google Cloud CLI	Routes-based

You can also create a routes-based cluster by specifying the --no-enable-ip-alias flag when you create the cluster.

IP address ranges for VPC-native clusters

When you create a VPC-native cluster, you specify a subnet in a VPC network. The cluster uses the following subnet IP address ranges:

• It uses the subnet's primary IPv4 address range for all node IPv4 addresses.
• It uses one subnet secondary IPv4 address range for all Pod IPv4 addresses in the cluster. You can use additional subnet secondary IPv4 address ranges if you configure discontiguous multi-Pod CIDR.
• For IPv4 Service ranges, it uses another secondary IP address range for all Service (cluster IP) addresses. To learn how two or more clusters can use the same Services IPv4 range, see Sharing IP address ranges across GKE clusters.
• If your cluster uses dual-stack networking, the node's IPv6 address and all Pod IPv6 addresses come from the node's assigned /96 IPv6 address range. The node IP address is the first /128 (single IPv6 address) in that list. For more information, see Dual-stack networking.

The following table provides a summary of IP address ranges for nodes, Pods, and Services:

Range	Explanation	Example
Nodes	Node IP addresses are assigned from the primary IP address range of the subnet associated with your cluster. Both node IP addresses and the size of the subnet's secondary IP address range for Pods limit the number of nodes that a cluster can support. Refer to node limiting ranges for more information.	If you plan to create a 900-node cluster, the primary IP address range of the cluster's subnet must be at least a /22 (2^(32-22) = 2^10 = 1,024 addresses). Of those 1,024 addresses, 1,020 are usable because four IP addresses are reserved in every primary IP address range. Refer to Subnet primary IP address range and Subnet secondary IP address range for Pods for more information.
Pods	Pod IP addresses are taken from the cluster subnet's secondary IP address range for Pods. Unless you set a different maximum number of Pods per node, GKE allocates a /24 alias IP range (256 addresses) to each node for the Pods running on it. On each node, those 256 alias IP addresses are used to support up to 110 Pods.	For a 900-node cluster supporting up to 110 Pods per node, you need 900 × 256 = 230,400 IP addresses for Pods. (Each node is allocated an alias IP range whose netmask's size is /24.) This cluster requires a subnet whose secondary IP range for Pods has a subnet mask no larger than /14. This secondary IP range provides 2^(32-14) = 2^18 = 262,144 IP addresses for Pods. Refer to Subnet secondary IP address range for Pods for more information.
Services	Service (cluster IP) addresses are taken from the cluster's subnet's secondary IP address range for Services. You must ensure this range is large enough to provide addresses for all the Kubernetes Services you host in your cluster. In new Autopilot clusters running GKE version 1.27 and later, GKE assigns IP addresses for GKE Services from a Google-managed range: 34.118.224.0/20 by default. This eliminates the need for you to specify your own IP address range for Services. For details, see Subnet secondary IP address range for Services.	For a cluster that runs up to 3000 Services, you need 3000 cluster IP addresses. You need a secondary range of size /20 or larger. A /20 range of IP addresses results in 2^(32-20) = 2^12 = 4,096 IP addresses. Refer to Subnet secondary IP address range for Services for more information.

Internal IP addresses

The IP addresses you use for your VPC-native cluster's subnets must come from a valid subnet range. The valid ranges include private IP addresses (RFC 1918 and others) and privately used public IP addresses. See Valid ranges and Restricted ranges in the VPC documentation for more information about valid subnet ranges.

See Using non-RFC 1918 private IP address ranges for instructions on enabling the use of these ranges.

See Enable privately used public IP address ranges for instructions on the use of these ranges in private clusters.

Secondary range assignment methods

You can assign Pod IP address ranges and Service (ClusterIP) address ranges to a VPC-native cluster. These IP address ranges can be managed by GKE or user-managed.

Managed by GKE (default)

GKE can create and manage the subnet's secondary ranges for you. When you create the cluster, you specify either a complete CIDR range or the size of a netmask for both the Pods and Services. For example, you can specify 10.1.0.0/16 for Pods and 10.2.0.0/20 for Services, or you can specify /16 for Pods and /20 for Services.

If you create the cluster and subnet simultaneously Pod and Service IP address ranges are managed by GKE.

Caution: If you specify a Pod address range smaller than a /21 range, you risk running out of Pod IP addresses as your cluster grows, depending on the number of maximum pods per node you have configured. The Google Cloud CLI will not prevent you from specifying a range smaller than a /21 range.

In new Autopilot clusters running GKE version 1.27 and later, GKE assigns IP addresses for Services from a Google-managed range by default: 34.118.224.0/20. This IP address assignment eliminates the need for you to specify your own range for Services. The following considerations apply:

• You can optionally specify custom ranges for Services by using the --services-ipv4-cidr flag.
• If you specify only a range size using the --services-ipv4-cidr flag (for example, /22), GKE still uses the Google-managed range to obtain the sub-range of addresses.
• GKE doesn't create a separate secondary IP address range for Services when the Google-managed range is used.

User-managed

You can create the subnet's secondary IP address ranges, then create a cluster that uses those ranges. If you manually create the secondary ranges, you must manage them yourself.

Caution: User-managed ranges lets you use smaller subnet secondary ranges than is possible when using ranges managed by GKE. Use caution when creating Pod address ranges smaller than a /21 as you could run out of Pod IP addresses as your cluster grows.

The smallest IP address range you can create without using discontiguous multi-Pod CIDR is /28, but that range would only let you create 1 node with a maximum of 8 Pods. You should use a range that is large enough for the maximum number of nodes that you need. The minimum usable range also depends on the maximum number of Pods per Node.

Refer to the table in Optimizing IP address allocation for the minimum usable CIDR range for different values of Maximum Pods per Node.

If you exhaust your IP address range for Pods, you must do one of the following:

• Create a new cluster with a larger Pod address range
• Re-create your node pools after decreasing the --max-pods-per-node for the node pools
• Expand the secondary Pod IP address range using discontiguous multi-Pod CIDR

Differences with routes-based clusters

The allocation scheme for Pod and Service (ClusterIP) addresses is different than the scheme used by a routes-based cluster. Instead of specifying a single CIDR for Pods and Services together, you must choose or create two secondary IP address ranges in cluster's subnet: one for Pods and another for Services.

Shared VPC considerations

When creating a VPC-native cluster in a Shared VPC environment, a project owner, editor, or Identity and Access Management (IAM) principal with the Network Admin role in the Shared VPC host project must create the cluster's subnet and secondary IP address ranges manually. A service project admin who creates a cluster must at least have subnet-level permissions to the subnet in the Shared VPC network's host project.

In a Shared VPC environment, secondary IP address ranges cannot be managed by GKE. A Network Admin in the Shared VPC host project must create the subnet and secondary IP address ranges before you can create the cluster. For an example showing how to set up a VPC-native cluster in a Shared VPC network, refer to Setting up clusters with Shared VPC.

IP address range planning

Use the information in the following sections to help you calculate sizes for primary and secondary IP address ranges of the subnet used by your cluster.

Subnet primary IP address range

Every subnet must have a primary IP address range. This is the IP address range that GKE uses to allocate IP addresses for internal load balancers and nodes.

You cannot shrink or change a subnet's primary IP address range after the subnet has been created.

The first two and last two IP addresses of a primary IP address range are reserved by Google Cloud.

The following table shows the maximum number of nodes you can create in all clusters that use the subnet, given the size of the subnet's primary IP address range.

Subnet primary IP range	Maximum nodes
/29 Minimum size for a subnet's primary IP range	4 nodes
/28	12 nodes
/27	28 nodes
/26	60 nodes
/25	124 nodes
/24	252 nodes
/23	508 nodes
/22	1,020 nodes
/21	2,044 nodes
/20 Default size of a subnet's primary IP range in auto mode networks	4,092 nodes
/19	8,188 nodes
/8 Maximum size for a subnet's primary IP range	16,777,212 nodes

Expand the primary IP address range

If you run out of IP addresses in the primary IP address range, you can expand the primary IP address range at any time, even when Google Cloud resources, such as load balancers and network endpoint groups, use the subnet.

Before you expand the primary IP address range, consider the following:

• There must be no overlapping IP address ranges in the subnet.
• GKE uses the primary IP address range to allocate IP addresses for internal load balancers and nodes.

Useful formulas

You can use the following formulas to:

• Calculate the maximum number of nodes, N, that a given netmask can support. Use S for the size of the netmask, whose valid range is between 8 and 29, inclusive.

  N = 2^{(32 -S)} - 4

• Calculate the size of the netmask, S, required to support a maximum of N nodes:

  S = 32 - ⌈log₂(N + 4)⌉

  ⌈⌉ is the ceiling (least integer) function, meaning round up to the next integer. The valid range for the size of the netmask, S, is between 8 and 29, inclusive.

Subnet secondary IP address range for Pods

Carefully plan your secondary IP address range for Pods.

The following table shows the maximum number of nodes and Pods you can create in all clusters that use the subnet, given the size of the subnet's secondary IP address range used by Pods. This table assumes the maximum number of Pods per node is 110, which is the default Pod density.

Subnet secondary IP range for Pods	Maximum Pod IP addresses	Maximum nodes	Maximum Pods
/24 Smallest possible Pod IP range when the secondary range assignment method is user-managed	256 addresses	1 node	110 Pods
/23 Only possible when the secondary range assignment method is user-managed	512 addresses	2 nodes	220 Pods
/22 Only possible when the secondary range assignment method is user-managed	1,024 addresses	4 nodes	440 Pods
/21 Smallest possible Pod IP range when the secondary range assignment method is managed by GKE	2,048 addresses	8 nodes	880 Pods
/20	4,096 addresses	16 nodes	1,760 Pods
/19	8,192 addresses	32 nodes	3,520 Pods
/18	16,384 addresses	64 nodes	7,040 Pods
/17	32,768 addresses	128 nodes	14,080 Pods
/16	65,536 addresses	256 nodes	28,160 Pods
/15	131,072 addresses	512 nodes	56,320 Pods
/14 Default size for the subnet's secondary IP range for Pods when the secondary range assignment method is managed by GKE	262,144 addresses	1,024 nodes	112,640 Pods
/13	524,288 addresses	2,048 nodes	225,280 Pods
/12	1,048,576 addresses	4,096 nodes	450,560 Pods
/11	2,097,152 addresses	8,192 nodes	901,120 Pods
/10	4,194,304 addresses	16,384 nodes	1,802,240 Pods
/9 Largest possible Pod address range	8,388,608 addresses	32,768 nodes	3,604,480 Pods

If you have changed the maximum number of Pods per node, you can use the following formulas to calculate the maximum number of nodes and Pods that a subnet's secondary IP address range for Pods can support:

1. Calculate the size of the netmask of each node's Pod range, M.
   M = 31 - ⌈log2(Q)⌉ where:

   • Q is the number of Pods per node
   • ⌈⌉ is the ceiling (least integer) function, meaning round up to the next integer
   • For example, if Q is 110, then M = 24

2. Calculate the maximum number of nodes, N, that the subnet's secondary IP address range for Pods can support:
   N = 2(M - S) where:

   • M is the size of the netmask of each node's alias IP address range for Pods, calculated in the first step
   • S is the size of the subnet mask of the subnet's secondary IP address range
   • For example, if M is 24, and S is 20, then N = 16

3. Calculate the maximum number of Pods, P, that the subnet's secondary IP address range for Pods can support:
   P = N × Q where:

   • N is the maximum number of nodes, calculated in the previous step
   • Q is the number of Pods per node
   • For example, if N is 16, and Q is 110, then P = 1760

You can add more IP addresses for Pods by using discontiguous multi-Pod CIDR.

Subnet secondary IP address range for Services

Carefully plan your secondary IP address range for Services. Because this is also a subnet secondary IP address range, this range cannot be changed once the cluster is created.

If you use multi-cluster services, the ServiceImport object uses IP addresses from the secondary IP range for Services.

In new Autopilot clusters running GKE version 1.27 and later, GKE assigns IP addresses for Services from a Google-managed range by default: 34.118.224.0/20. This eliminates the need for you to specify your own IP address range for Services. The following considerations apply:

• You can optionally specify custom ranges for Services by using the --services-ipv4-cidr flag or the --services-secondary-range-name flag.
• If you specify only a range size using the --services-ipv4-cidr flag (for example, /22), GKE still uses the Google-managed range to obtain the sub-range of addresses.
• GKE doesn't create a separate secondary IP address range for Services when the Google-managed range is used. The Google-managed range doesn't use the secondary IP address range quota for your subnet.

The following table shows the maximum number of Services you can create in a single cluster using the subnet, given the size of the subnet's secondary IP address range for Services.

Secondary IP range for Services	Maximum number of Services
/28 Smallest possible Service address range when the secondary range assignment method is user-managed	16 Services
/27 Smallest possible Service address range when the secondary range assignment method is managed by GKE	32 Services
/26	64 Services
/25	128 Services
/24	256 Services
/23	512 Services
/22	1,024 Services
/21	2,048 Services
/20 Default size for the subnet's secondary IP range for Services when the secondary range assignment method is managed by GKE	4,096 Services
/19	8,192 Services
/18	16,384 Services
/17	32,768 Services
/16 Largest possible Service address range	65,536 Services

Sharing IP address ranges across GKE clusters

You can share the primary range, secondary IP address range for Pods, and secondary IP address range for Services between clusters in the same subnetwork. This behavior is available for both Standard and Autopilot clusters.

You might want to share IP address ranges if you have a centralized team that is managing the infrastructure for clusters. You can reduce overhead by creating three ranges, for Pods, Services and nodes, and reusing or sharing them, especially in a Shared VPC model. It can also make it easier for network administrators to manage IP addresses by not requiring them to create specific subnets for each cluster.

Sharing the primary IP address range for nodes

If you create more than one cluster in the subnet, the primary IP address range for nodes is shared by default.

Sharing the primary IP address for nodes has the following limitations:

• If you share the primary IP address range for nodes with two or more VPC-native clusters, one cluster can use a large portion of the shared IP address range, leaving the other clusters without enough IP addresses to expand.

Sharing the secondary IP address range for Pods

When you share the secondary range for Pods, each Pod still gets a unique IP address.

Note: Among the different types of secondary ranges, the additional Pod ranges are not shareable across clusters.

Sharing the secondary IP address range for Pods has the following limitations:

• If you share the secondary IP address range for Pods with two or more VPC-native clusters, one cluster can use a large portion of the shared IP address range, leaving the other clusters without enough IP addresses to expand.

• Among the different types of secondary ranges, both the GKE-managed and additional Pod ranges are not shareable across clusters.

• To share a secondary IP range, pass it on the command line with --cluster-secondary-range you cannot use a shared secondary range when creating clusters in the UI

Sharing the secondary IP address range for Services

Two or more clusters can simultaneously use the same subnet secondary IPv4 address range for Services when you use user-managed secondary ranges.

To configure two or more clusters to share a common subnet secondary IPv4 address range for Services, use the same subnet secondary IPv4 address range when you create each cluster. There is no separate configuration flag required to share a common IPv4 address range for Services.

When sharing a common IPv4 address range for Services, each cluster uses the entire subnet secondary IPv4 address range for Services internally. The IP addresses for Services are programmed within each cluster's node, but they are not assigned to the network interface of any node. Service IP addresses are not routable within the cluster's VPC network. Service IP addresses are only usable by client Pods within the same cluster as the Service.

When a Pod sends a packet to a Service IP address, the iptables or eBPF configuration on the node performs destination Network Address Translation (NAT), changing the destination IP address of the packet from the Service IP address to a serving Pod IP address. The packet is routed based on the destination Pod IP address.

Sharing the secondary IP address range for Services provides the following benefits:

• Reduce the number of unique secondary IP address ranges for Services created on a subnet
• Use fewer IP addresses

Sharing the secondary IP address range for Services has the following limitations:

• Sharing the secondary IP address range for Services is not supported with VPC scope Cloud DNS for GKE.

• You can't share ranges that match the following regex:

  ^gke-.*-services-[abcdef0-9]{8}
  

• To share a secondary IP range for services, pass it on the command line with --cluster-secondary-range you cannot use a shared secondary range for services when creating clusters in the UI.

Node limiting ranges

The maximum number of Pods and Services for a given GKE cluster is limited by the size of the cluster's secondary ranges. The maximum number of nodes in the cluster is limited by the size of the cluster's subnet's primary IP address range and the cluster's Pod address range.

The Google Cloud console shows error messages like the following to indicate that either the subnet's primary IP address range or the cluster's Pod IP address range (the subnet's secondary IP address range for Pods) has been exhausted:

Instance [node name] creation failed: IP space of [cluster subnet] is
exhausted

You can add more IP addresses for nodes by expanding the primary subnet, or add new IP addresses for Pods using discontiguous multi-Pod CIDR. For more information, see Not enough free IP space for Pods.

IPv4/IPv6 dual-stack networking

With IPv4/IPv6 dual-stack networking, you can define how GKE allocates IP addresses (ipFamilies) to the following objects:

• For Pods and nodes, GKE allocates both IPv4 and IPv6 addresses.
• For Services, GKE allocates either single-stack (IPv4 only or IPv6 only), or dual-stack addresses.

In GKE version 1.24 or later, you can enable dual-stack networking for new GKE clusters on standalone and Shared VPC networks. You can also apply network policies with dual-stack networking enabled.

Note: If you see validation errors when enabling dual-stack networking on GKE clusters that have been upgraded from versions 1.24 to versions 1.25 or 1.26, contact the Google Cloud support team.

Benefits

Dual-stack networking provides the following benefits:

• Enables end-to-end IPv6 communication.
• Enables better performance compared to network address translation (NAT) or IP tunneling. This is achieved because there is no IPv6 to IPv4 translation.

Availability

Dual-stack networking with GKE has the following restrictions:

• Dual-stack networking is only available for VPC-native clusters clusters with GKE Dataplane V2 enabled.
• Dual-stack networking is only supported on subnets in custom mode VPCs. For more information, see Google Cloud types of VPC networks.
• Single-stack IPv6 addresses for Pods or nodes are not supported.
• Dual-stack clusters consume additional memory per node to support both IPv4 and IPv6 compared to IPv4 only clusters. Consider this characteristic when setting up large-scale clusters.
• Dual-stack clusters don't support Private Google Access over IPv6.
• GKE versions 1.26.0-gke.2200 and later supports IPv6 (AAAA records) with Cloud DNS for cluster-internal operations and external DNS queries.
• Dual-stack Services are supported for ClusterIP and NodePort Services. GKE supports dual-stack Services of type LoadBalancer during Preview which carries no SLA or technical support.
• IPv6 is not supported for Windows nodes.

Consider the preceding restrictions before creating a cluster with dual-stack networking. For more information, learn how to create a VPC-native cluster with dual-stack networking.

Public and Private IPv6 address assignment

The following table provides a summary of public and private IPv6 addresses with dual-stack networking behavior and configurations:

ipv6-access-type flag	IP address assignment	Subnet range
EXTERNAL	GKE assigns external IPv6 addresses that are routable to the internet.	From 2600:1900/28
INTERNAL	GKE assigns internal IPv6 addresses that are not routable to the internet. Clusters with INTERNAL IPv6 access type cannot access the internet over IPv6 addresses. Cloud NAT does not support IPv6 addresses.	From fd20::/20 (which is a subset of the overall ULA range: fc00::/7).

To learn more, see how to use a dual-stack network for a VPC-native cluster.

Architecture

A cluster, in Autopilot or Standard, with IPv4/IPv6 dual-stack networking has the following ranges allocated:

• A /64 range to each subnet as a primary range.
• A /96 per-node range from the primary range to use as a primary node IP address range.

• A /112 per-node range from the primary node IP address range to use as a Pod IP address range for that node. With dual-stack networking, Pods get their IPv6 addresses from the overall Pod IP address range (similar to nodes), and not from secondary range for Pods reserved to IPv4 addresses.

  The overall pod IP address range is comprised of non-overlapping ranges from the primary node IP range. Therefore, this Pod IP range is discontiguous.

• A /112 range to use for Services. This range comes from a /64 range from the Google private address range which has been reserved for GKE's secondary Services IP address range.

The following diagram shows how Google Cloud and GKE allocate IPv6 addresses:

In the diagram, the primary range of the VPC subnet is 2600:1900:0:1::/64 and the reserved range for GKE Services is 2600:2D00:0:4::0:0/64. Each node in the cluster has a /96 range for the primary node IP address range and a /112 range for the Pod IP address range. The cluster also has a /112 secondary Services IP address range.

Note: GKE automatically selects the IPv6 IP address range for the Pod IP address range and the secondary Services IP address range.

Services

You can create an IPv6 Service of type ClusterIP or NodePort. GKE supports dual-stack Services of type LoadBalancer during Preview which carries no SLA or technical support.

You can expose a Deployment with a Service of type ClusterIP, NodePort, or LoadBalancer. For each of these Service types, you can define ipFamilies and ipFamilyPolicy fields as either IPv4, IPv6, or a dual-stack Service. For more information, see an example of how to set up a Deployment.

What's next

• Learn more about VPC Network Peering.
• Learn how to create a VPC-native cluster.
• Learn about GKE IP address utilization insights.