Adding Pod IPv4 address ranges

Autopilot Standard

This page shows you how to configure additional Pod IPv4 address ranges for a VPC-native cluster and how to specify custom Pod IPv4 address ranges for node pools of a VPC-native cluster.

Pod IPv4 address ranges in VPC-native clusters always come from subnet secondary IPv4 address ranges. When you create a new cluster, you assign the cluster a default Pod IPv4 address range.

For Autopilot and Standard clusters, you can configure a cluster to use additional Pod IPv4 address ranges. GKE uses these additional Pod IPv4 address ranges for Pod IPv4 addresses on nodes created in future node pools.
For Standard clusters, you can create node pools that each use a custom subnet secondary IPv4 address range for their Pod IPv4 addresses.

Before you begin

Before you start, make sure you have performed the following tasks:

Enable the Google Kubernetes Engine API.

Enable Google Kubernetes Engine API

If you want to use the Google Cloud CLI for this task, install and then initialize the gcloud CLI. If you previously installed the gcloud CLI, get the latest version by running gcloud components update.
Note: For existing gcloud CLI installations, make sure to set the compute/region and compute/zone properties. By setting default locations, you can avoid errors in gcloud CLI like the following: One of [--zone, --region] must be supplied: Please specify location.

Make sure that you have the Compute Network Admin Identity and Access Management (IAM) role for the project containing the cluster's subnet. This is required to create new subnet secondary IPv4 address ranges. When using Shared VPC, you'll need to coordinate with the Network Admin for the Shared VPC host project.
Make sure your GKE cluster is a VPC-native cluster. Routes-based clusters don't support additional Pod IPv4 address ranges or node pool custom Pod IPv4 address ranges.
Review the Follow-up steps section.

Create a new subnet secondary IPv4 address range

To create a new subnet secondary IPv4 address range, use either the Google Cloud console or the Google Cloud CLI. Each subnet supports up to 30 secondary IPv4 address ranges. For more information, see Edit secondary IPv4 ranges in the VPC documentation.

Console

Go to the VPC networks page in the Google Cloud console.

Go to VPC networks
In the VPC networks list, select the network that you want to expand.
In the Subnets list, select the subnet that you want.
Click Edit.
Click Add IP range.
For Subnet range name, enter the name of the new subnet secondary IPv4 address range. For example, pod-range-2.
For Secondary IP range, enter the IPv4 address range in CIDR format. For example, 10.2.204.0/22.
Click Save.

gcloud

gcloud compute networks subnets update SUBNET_NAME \
    --region=REGION \
    --add-secondary-ranges=SECONDARY_RANGE_NAME=SECONDARY_RANGE_CIDR

Replace the following:

SUBNET_NAME: The name of the cluster's subnet (the same subnet assigned to the cluster when it was created).
REGION: The region of the cluster's subnet subnet. The region of the cluster's subnet is the region that contains the GKE cluster.
SECONDARY_RANGE_NAME: The name of the new subnet secondary IPv4 address range to serve as an additional Pod IPv4 address range for the cluster. For example, pod-range-2.
SECONDARY_RANGE_CIDR: The CIDR to be used by the new subnet secondary IPv4 address range. For example, 10.2.204.0/22.

You can add two or more new subnet secondary IPv4 address ranges by specifying additional SECONDARY_RANGE_NAME=SECONDARY_RANGE_CIDR pairs, separated by commas, after the --add-secondary-ranges flag.

Assign additional Pod IPv4 ranges to a cluster

You can assign additional Pod IPv4 address ranges at the cluster level, applicable to new nodes created in new node pools you create in the cluster. To assign additional Pod IPv4 address ranges to a cluster, you must first create a new subnet secondary IPv4 address range.

Assigning additional Pod IPv4 address ranges to a cluster is supported by:

Autopilot clusters running GKE version 1.26 and later
Standard clusters

Console

Go to the Google Kubernetes Engine page in the Google Cloud console.

Go to Google Kubernetes Engine
Next to the cluster you want to edit, click Actions, then click Edit.
In the Networking section, next to Cluster Pod IPv4 ranges (additional), click Edit.
In the Edit additional Cluster Pod IPv4 ranges dialog, click Pod secondary CIDR ranges and select the name(s) of one or more existing subnet secondary IPv4 address ranges in the cluster's subnet. If no additional subnet secondary IPv4 address ranges are available, first Create a new subnet secondary IPv4 address range then repeat these steps.
Click Save Changes.

gcloud

Update your cluster using the --additional-pod-ipv4-ranges flag:
```
gcloud container clusters update CLUSTER_NAME \
    --additional-pod-ipv4-ranges=SECONDARY_RANGE_NAME \
    --location=ZONE_OR_REGION
```
Replace the following:
- CLUSTER_NAME: The name of the cluster.
- SECONDARY_RANGE_NAME: The name of one or more existing subnet secondary IPv4 address range(s) in the cluster's subnet, separated by commas. If no subnet secondary IPv4 address ranges are available, Create a new subnet secondary IPv4 address range first.
- ZONE_OR_REGION: For zonal clusters, the Compute Engine zone where the cluster is located. For regional clusters, the Compute Engine region where the cluster is located. For a list of zones and regions, see Regions and zones in the Compute Engine documentation.

Look up cluster Pod IPv4 ranges

To look up the default Pod IPv4 address range of a cluster and any additional Pod IPv4 address ranges that have been assigned to the cluster, use the following command:

gcloud container clusters describe CLUSTER_NAME \
  --location=ZONE_OR_REGION

Replace the following:

CLUSTER_NAME: The name of the cluster.
ZONE_OR_REGION: For zonal clusters, the Compute Engine zone where the cluster is located. For regional clusters, the Compute Engine region where the cluster is located.

The output is similar to the following, which includes the cluster's IPAllocationPolicy:

ipAllocationPolicy:
  clusterSecondaryRangeName: cluster-pods
  clusterIpv4CidrBlock: 10.10.0.0/23
  additionalPodRangesConfig:
    podRangeNames:
      - pod-range-1
      - pod-range-2

where:

clusterSecondaryRangeName: The name of the subnet secondary IPv4 address range used as the default Pod IPv4 address range of the cluster, defined when the cluster was created.
clusterIpv4CidrBlock: The CIDR of the subnet secondary IPv4 address range for Pod IPv4 addresses, defined when the cluster was created.
additionalPodRangesConfig.podRangeNames: A list of any additional assigned subnet secondary IPv4 address range for Pod IPv4 addresses.

Node pool custom Pod IPv4 address ranges

For Standard clusters running GKE 1.20.4-gke.500 or later, you can assign a custom Pod IPv4 range to a new node pool using one of following methods:

Node pool custom Pod IPv4 address range managed by GKE: With this option, you create a new node pool and provide GKE with the information necessary to create a new subnet secondary IPv4 address range in the cluster's subnet. Each new node created in the new node pool is assigned an alias IP address range for its Pod IPv4 addresses, and each alias IP address range comes from the new subnet secondary IPv4 address range that GKE creates. This option can only be used if both the cluster and the VPC network containing the cluster's subnet are in the same project.
User-managed node pool custom Pod IPv4 address range: With this option, you create a new node pool where GKE uses an existing subnet secondary IPv4 address range. Each new node created in the new node pool is assigned an alias IP address range for its Pod IPv4 addresses, and each alias IP address range comes from the subnet secondary IPv4 address range that you instruct GKE to use. If your cluster is located in a Shared VPC service project, and if your cluster's subnet is located in the host project's Shared VPC network, you must use this option.

A node pool's custom Pod IPv4 address range overrides all Pod IPv4 address ranges defined at the cluster level, including additional Pod IPv4 address ranges assigned to the cluster. Custom Pod IPv4 address ranges assigned to node pools are also called discontiguous multi-Pod CIDR.

Node pool custom Pod IPv4 address range example

The following diagram shows a VPC-native cluster with user-managed Pod IPv4 address ranges:

Adding a node pool to a cluster with an exhausted secondary Pod IP
address range using discontiguous multi-Pod CIDR — **Diagram:** Node pool custom Pod IPv4 address range example

In the preceding diagram:

The maximum number of Pods per node for each node pool in the cluster has been set to 64. To accommodate a maximum of 64 Pods per node, GKE creates each node with a /25 alias IP address range, providing 128 Pod IPv4 addresses per node.
The cluster's default Pod IPv4 address range is a /24. Because each node requires a /25 for Pod IPv4 addresses, the cluster's default Pod IPv4 address range only supports two nodes.
To support additional nodes, a cluster administrator has created an additional node pool, maintaining the 64 maximum Pods per node. The additional node pool uses a custom /20 Pod IPv4 address range, which supports 32 additional nodes.

Node pool custom Pod IPv4 address range managed by GKE

To create a node pool with a custom Pod IPv4 address range managed by GKE, use gcloud CLI or GKE API as follows:

gcloud

gcloud container node-pools create POOL_NAME \
  --cluster=CLUSTER_NAME \
  --location=ZONE_OR_REGION \
  --create-pod-ipv4-range=name=SECONDARY_RANGE_NAME,range=CIDR_OR_NETMASK

Replace the following:

POOL_NAME: The name of the new node pool.
CLUSTER_NAME: The name of the cluster.
ZONE_OR_REGION: For zonal clusters, the Compute Engine zone where the cluster is located. For regional clusters, the Compute Engine region where the cluster is located. For a list of zones and regions, see Regions and zones.
SECONDARY_RANGE_NAME: The name of the subnet secondary IPv4 address range that GKE creates. If you omit name=SECONDARY_RANGE_NAME, GKE generates the name of the new subnet secondary IPv4 address range automatically.
CIDR_OR_NETMASK: The Pod IPv4 address range expressed in either CIDR format (for example, 10.12.4.0/20) or as a subnet mask (for example, /20).
- If you provide only a subnet mask, GKE attempts to create a new subnet secondary IPv4 address range that doesn't conflict with existing subnet IPv4 address ranges in the VPC network that contains the cluster's subnet.
- If you omit range=CIDR_OR_NETMASK, GKE attempts to create a new /14 subnet secondary IPv4 address range that doesn't conflict with existing subnet IPv4 address ranges in the VPC network that contains the cluster's subnet.

API

"nodePool": {
  "name": "POOL_NAME",
  ...
  "networkConfig": {
    "createPodRange": true,
    "podRange": "SECONDARY_RANGE_NAME",
    "podIpv4CidrBlock": "CIDR_OR_NETMASK"
    }
}

Replace the following:

POOL_NAME: The name of the new node pool.
SECONDARY_RANGE_NAME: Optional—the name of the subnet secondary IPv4 address range that GKE creates. If you use "" as the value for networkConfig.podRange or if you omit the podRange parameter in the request, GKE generates the name of the new subnet secondary IPv4 address range automatically.
CIDR_OR_NETMASK: The Pod IPv4 address range expressed in either CIDR format (for example, 10.12.4.0/20) or as a subnet mask (for example, /20).
- If you provide only a subnet mask, GKE attempts to create a new subnet secondary IPv4 address range that doesn't conflict with existing subnet IPv4 address ranges in the VPC network that contains the cluster's subnet.
- If you use "" as the value for networkConfig.podIpv4CidrBlock, GKE attempts create a new /14 subnet secondary IPv4 address range that doesn't conflict with existing subnet IPv4 address ranges in the VPC network that contains the cluster's subnet.

User-managed node pool custom Pod IPv4 address range

To create a node pool with a user-managed custom Pod IPv4 address range, use gcloud CLI or GKE API as follows:

gcloud

gcloud container node-pools create POOL_NAME \
  --cluster=CLUSTER_NAME \
  --location=ZONE_OR_REGION \
  --pod-ipv4-range SECONDARY_RANGE_NAME

Replace the following:

POOL_NAME: The name of the new node pool.
CLUSTER_NAME: The name of the cluster.
ZONE_OR_REGION: For zonal clusters, the Compute Engine zone where the cluster is located. For regional clusters, the Compute Engine region where the cluster is located. For a list of zones and regions, see Regions and zones in the Compute Engine documentation.
SECONDARY_RANGE_NAME: The name of an existing subnet secondary IPv4 address range in the cluster's subnet. If necessary, create a new subnet secondary IPv4 address range first.

API

"nodePool": {
  "name": "POOL_NAME",
  ...
  "networkConfig": {
    "createPodRange": false,
    "podRange": "SECONDARY_RANGE_NAME"
    }
}

Replace the following:

POOL_NAME: The name of the new node pool.
SECONDARY_RANGE_NAME: The name of an existing subnet secondary IPv4 address range in the cluster's subnet. If necessary, create a new subnet secondary IPv4 address range first.

Look up node pool Pod IPv4 ranges

To look up the Pod IPv4 address range of a node pool, use the following command:

gcloud container node-pools describe POOL_NAME \
  --cluster=CLUSTER_NAME \
  --location=ZONE_OR_REGION

Replace the following:

POOL_NAME: The name of the node pool.
CLUSTER_NAME: The name of the cluster.
ZONE_OR_REGION: For zonal clusters, the Compute Engine zone where the cluster is located. For regional clusters, the Compute Engine region where the cluster is located.

The output is similar to the following, which includes the node pool's NodeNetworkConfig:

  networkConfig:
    podRange: podrange
    podIpv4CidrBlock: 192.168.0.0/18

where:

podRange: The name of the subnet secondary IPv4 address range for the node pool's Pod IPv4 addresses.
podIpv4CidrBlock: The CIDR of the subnet secondary IPv4 address range for the node pool's Pod IPv4 addresses.

If the node pool is using a custom Pod IPv4 address range, the podRange and podIpv4CidrBlock values are different from the cluster's default Pod IPv4 address range.

Follow-up steps

After you have assigned additional Pod IPv4 address ranges to a cluster or configured node pool custom Pod IPv4 address ranges, GKE updates the automatically-created gke-[cluster-name]-[cluster-hash]-all VPC firewall rule so that its source range includes all Pod IPv4 addresses.

You might also need to:

Update your cluster's IP masquerade agent configuration. The effective set of non-masquerade CIDRs must include all Pod IPv4 address ranges used by your cluster (and its node pools). For more information, see Checking ip-masq-agent status and Configuring and deploying the ip-masq-agent.
Review your cluster's NetworkPolicy configuration. You might need to update ipBlock attributes that reference Pod IPv4 address ranges.
Troubleshoot connectivity issues using VPC Flow Logs and Firewall Rules Logging.

What's next

Learn more about VPC-native clusters.
Read the GKE network overview.
Learn more about Optimizing IP address allocation.
Learn about GKE IP address utilization insights.