Add subnets to clusters

This page shows you how to assign additional subnets to a VPC-native cluster. Additional subnets assigned to a cluster let you create new node pools where IPv4 addresses for both nodes and Pods come from the additional subnet ranges.

This page is for Networking specialists who design and architect the network for their organization. To learn more about common roles and example tasks that we reference in Google Cloud content, see Common GKE Enterprise user roles and tasks.

Overview

When you create a new VPC-native GKE cluster, you select a default subnet for the cluster. The cluster's default subnet provides IPv4 addresses for nodes, Pods, and Services as described in IP address ranges for VPC-native clusters.

You can assign up to eight additional subnets to a VPC-native cluster, allowing for significant cluster growth. Each newly assigned additional subnet is called a non-default subnet.

Before you begin

Before you start, make sure that 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.

Requirements and limitations

This section describes the requirements and limitations that apply when you assign and use additional subnets to a cluster. You must meet all the requirements before you assign additional subnets.

  • Make sure that your GKE cluster is a VPC-native cluster that runs GKE version 1.30.3-gke.1211000 or later. Routes-based clusters and clusters on legacy networks don't support additional subnets.
  • You can assign up to eight additional subnets per cluster.
  • The additional subnets provide only IPv4 addresses for nodes and Pods. Additional subnets can't be used to provide IPv6 addresses for nodes or Pods.
  • Only new node pools can use the additional subnets, not existing node pools. When you create a new node pool and multiple non-default subnets are available, GKE selects the best subnet for the node pool based on the requirements for IP addresses and the availability of IP addresses in all cluster subnets.
  • Subnet secondary IPv4 address ranges in a non-default subnet can only be used by a single cluster.
  • If you use multi-network support for Pods, the primary and Pod IPv4 address ranges of an additional subnet must not overlap with any CIDR ranges that are configured within your multi-network setup. Additional subnets that you configure apply only to the default network. This limitation means that any additional network interfaces on your nodes and Pods can't use the IP addresses provided by these additional subnets.
  • If the pool of IP addresses in the default subnet is depleted, you can't autoscale your cluster even if you use additional subnets.

Load balancer requirements for clusters with additional subnets

This section describes the load balancer requirements that apply when you use additional subnets on your cluster. These requirements apply each time you create an external Ingress or external LoadBalancer Service.

  • To use an external Ingress or external LoadBalancer Service in a cluster with additional subnets, your cluster must run GKE version 1.33.2-gke.4780 or later.
  • External Ingress objects using the GKE Ingress controller must use container-native load balancing.
  • Enable GKE subsetting for internal LoadBalancer Services. GKE subsetting affects only new internal LoadBalancer Services. Therefore, you must delete and recreate any existing Services in your cluster after you enable GKE subsetting.

  • To create a backend service-based external passthrough Network Load Balancer, new external LoadBalancer Services must include the cloud.google.com/l4-rbs: "enabled" annotation. This annotation affects only new external LoadBalancer Services and doesn't apply to existing external LoadBalancer Services. Delete and recreate all external LoadBalancer Services that were created without the cloud.google.com/l4-rbs: "enabled" annotation.

    The backend type that's used (GCE_VM_IP NEG backends or instance group backends) depends on the GKE version when you create the external LoadBalancer Service. For more information, see Node grouping.

Add a new subnet with one Pod IPv4 address range

  1. Create a new subnet and add a new subnet secondary IPv4 address range. The subnet must in the same region and VPC network as the cluster:

       gcloud compute networks subnets create SUBNET_NAME \
     --network=NETWORK \
     --region=REGION \
     --range=PRIMARY_RANGE \
     --add-secondary-ranges=POD_RANGE_NAME=SECONDARY_RANGE

    Replace the following:

    • SUBNET_NAME: the name of the new subnet.
    • NETWORK: the name of the VPC network that contains the new subnet.
    • REGION: the region in which the subnet is located.
    • PRIMARY_RANGE: the primary IPv4 range for the new subnet, in CIDR notation. For more information, see IPv4 subnet ranges.
    • POD_RANGE_NAME: a name for the secondary range.
    • SECONDARY_RANGE: the secondary IPv4 range in CIDR notation. For valid ranges, see IPv4 subnet ranges.

    For more information, see Work with subnets.

  2. Update your cluster to use the additional subnet by using the gcloud CLI:

       gcloud container clusters update CLUSTER_NAME \
     --additional-ip-ranges=subnetwork=SUBNET_NAME,pod-ipv4-range=POD_RANGE_NAME

    Replace the following:

    • CLUSTER_NAME: the name of your existing cluster.
    • SUBNET_NAME: the name of the new subnet that you created.
    • POD_RANGE_NAME: the name of the subnet secondary IPv4 address range that you want to use for the Pod IPv4 address range.

Add a new subnet with multiple Pod IPv4 address ranges

  1. Create a new subnet in the same region and VPC network as the cluster. Set the subnet primary IPv4 address range to an additional IPv4 address range for nodes.

  2. For each additional Pod IPv4 address range you need, add a new subnet secondary IPv4 address range to the subnet you created in the previous step.

  3. Update your cluster to use the additional subnet by using the gcloud CLI. The following example adds one subnet that has two subnet secondary IPv4 address ranges for Pods.

       gcloud container clusters update CLUSTER_NAME \
     --additional-ip-ranges=subnetwork=SUBNET_NAME,pod-ipv4-range=POD_RANGE_NAME_1 \
     --additional-ip-ranges=subnetwork=SUBNET_NAME,pod-ipv4-range=POD_RANGE_NAME_2

    Replace the following:

    • CLUSTER_NAME: the name of your existing cluster.
    • SUBNET_NAME: the name of the new subnet that you created.
    • POD_RANGE_NAME_1 and POD_RANGE_NAME_2: the names of the subnet secondary IPv4 address ranges that you want to use for Pod IPv4 address ranges.

Verify the subnets

By cluster: To see the details of all subnets associated with a cluster, run the following command:

   gcloud container clusters describe CLUSTER_NAME

Replace CLUSTER_NAME with the name of your cluster.

The output is similar to the following:

ipAllocationPolicy:
  additionalIPRangesConfig:
  - podIpv4RangeNames:
    - pod-range-1
    subnetwork: projects/user-gke-dev-2/regions/us-central1/subnetworks/shared-msc-subnets

By node pool: To see the details of all subnets associated with a node pool, run the following command:

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

Replace the following:

  • POOL_NAME: the name of the node pool.
  • CLUSTER_NAME: the name of the cluster.

The output is similar to the following:

name: pool-1
networkConfig:
  podRange: pod-range-1
  subnetwork: projects/user-gke-dev-2/regions/us-central1/subnetworks/shared-msc-subnets

Remove a non-default subnet

Removing a non-default subnet from a cluster instructs the cluster to no longer use the subnet's ranges in any of the cluster's node pools. Removal has the following effects:

  • The non-default subnet's primary IPv4 address range can't be used for node IPv4 address ranges.
  • The subnet secondary IPv4 ranges in the non-default subnet can't be used for Pod IPv4 ranges.

Before you remove a non-default subnet, you must delete all node pools that use this subnet.

To remove a non-default subnet from the cluster, run the following command:

   gcloud container clusters update CLUSTER_NAME \
     --remove-additional-ip-ranges= subnetwork=SUBNET_NAME

Replace the following:

  • CLUSTER_NAME: the name of your cluster.
  • SUBNET_NAME: the name of the subnet that you want to remove from the cluster.

After removing a non-default subnet from the cluster, you can delete the non-default subnet.

Remove a non-default subnet secondary IPv4 range

When you remove a non-default subnet secondary IPv4 range from a cluster, GKE instructs the cluster to not use that range for Pod IPv4 ranges in any node pool. If the non-default subnet secondary IPv4 range that you remove is the only range of the non-default subnet that's used by this cluster, GKE also instructs the cluster to stop using this subnet's primary IPv4 address for node IPv4 addresses.

Before you remove a non-default subnet secondary IPv4 range, you must delete all node pools that use the range for Pod IPv4 addresses.

To remove a non-default subnet secondary IPv4 range from the cluster, run the following command:

   gcloud container clusters update CLUSTER_NAME \
     --remove-additional-ip-ranges=\
       subnetwork=SUBNET_NAME,pod-ipv4-range=POD_RANGE_NAME

Replace the following:

  • CLUSTER_NAME: the name of the cluster.
  • SUBNET_NAME: the name of the non-default subnet.
  • POD_RANGE_NAME: the name of the non-default subnet secondary IPv4 range that you want to remove from the cluster.

After removing a non-default subnet secondary IPv4 range from the cluster, you can delete the non-default subnet secondary IPv4 range.

What's next