This page describes how to create additional subnets in your organization's internal Virtual Private Cloud (VPC), or Default VPC, to support your internal networking requirements. You must create a VPC subnet to make sure your internal workloads, such as virtual machines (VM) and containers, have a sufficient number of IP addresses to support their networking requirements within your organization.
There are several tasks outlined on this page, which are not intended to be completed in order:
- Create a zonal branch subnet for workloads: This task is useful to further organize or allocate your zone's existing internal IP addresses to workloads.
- Create a leaf subnet for an individual workload: This task is useful when you have a new workload that doesn't yet have an IP address to use.
- Allocate zonal subnet from global IP address range: This task is useful when your zone no longer has sufficient internal IP address space.
- Divide root global subnet without zone allocation: This task is useful to further organize the internal IP addresses in the global API server before allocating them to a zone.
- Add new network root range global subnet: This task is useful when your Default VPC no longer has sufficient global internal IP address space to allocate to your zones.
For an overview of subnets and their concepts before you complete the tasks in this page, see Subnets and IP addresses.
This page is for network administrators within the platform administrator group and application developers within the application operator group, who are responsible for managing network traffic for their organization. For more information, see Audiences for GDC air-gapped documentation.
Before you begin
To get the permission that you need to create subnets, ask your Organization IAM
Admin to grant you the Subnet Organization Admin (subnet-org-admin
)
IAM role. This role is not bound to a namespace.
Create a zonal branch subnet for workloads
You can create a zonal internal subnet from the zone's existing zonal root
subnet to further subdivide IP addresses in your zonal Default VPC. You must
create this subnet type in the platform
namespace. If the parent zonal root
subnet does not have enough IP addresses available, you must
allocate another zonal subnet from the global IP address range
before you continue.
In a terminal window, create the new zonal subnet in the management API server:
kubectl -kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG apply -f - <<EOF apiVersion: ipam.gdc.goog/v1 kind: Subnet metadata: labels: ipam.gdc.goog/vpc: default-vpc name: SUBNET_NAME namespace: platform spec: ipv4Request: prefixLength: CIDR_PREFIX_LENGTH networkSpec: enableGateway: true enableVLANID: false parentReference: name: PARENT_SUBNET_NAME namespace: platform type: Branch EOF
Replace the following:
MANAGEMENT_API_SERVER_KUBECONFIG
: the path to the kubeconfig file of your management API server. For more information, see Zonal management API server resources.SUBNET_NAME
: the name of your new network subnet.CIDR_PREFIX_LENGTH
: the CIDR prefix length of the new subnet that is dynamically allocated, such as20
. To statically set the CIDR, replace theprefixLength
field with thecidr
field, and then set the CIDR block, such as10.0.10.0/27
.PARENT_SUBNET_NAME
: the name of the parent subnet, such asdefault-vpc-zone0-cidr
. The parent subnet is typically a zonal root subnet in the Default VPC.
See the API reference documentation for the
Subnet
resource for more information.You can continue to subdivide your zonal subnets, or create a leaf subnet to allocate an individual IP address directly to an internal workload.
Create a leaf subnet for an individual workload
You must create a leaf subnet to allocate a single IP address for your workload.
This leaf subnet must have the field value type: Leaf
and must reside in the
same project namespace as your workload resource, such as a VM or container.
Your leaf subnet must be configured with a prefixLength
value of 32
, as it's
intended to allocate a single IP address. The parentReference
value references
a previously allocated subnet, such as the parent zonal subnet you created in
Create a zonal branch subnet for workloads.
In a terminal window, create the leaf subnet in the management API server:
kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG apply -f - <<EOF apiVersion: ipam.gdc.goog/v1 kind: Subnet metadata: labels: ipam.gdc.goog/allocation-preference: default ipam.gdc.goog/vpc: default-vpc name: SUBNET_NAME namespace: PROJECT_NAMESPACE spec: ipv4Request: prefixLength: 32 parentReference: name: PARENT_SUBNET namespace: platform type: Leaf EOF
Replace the following:
MANAGEMENT_API_SERVER_KUBECONFIG
: the path to the kubeconfig file of your management API server. For more information, see Zonal management API server resources.SUBNET_NAME
: the name for the leaf subnet.PROJECT_NAMESPACE
: the project namespace corresponding to your project where your workloads are located.PARENT_SUBNET
: the name of the parent subnet that this leaf subnet will source its IP address from.
Your individual IP address is now available to be used by your internal workloads, such as VMs and containers. For more information on how to configure the IP address for your workloads, see Deploy virtual machine workloads or Deploy container workloads.
Allocate zonal subnet from global IP address range
If your zone does not provide sufficient IP addresses for your workloads from the existing zonal root subnet IP address range, you can allocate additional IP addresses from the global IP address root range.
Complete the following steps for the Default VPC network in the platform
namespace:
In a terminal window, describe all of the Default VPC's root subnets and check their available CIDRs:
kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG describe subnets --namespace platform \ --label ipam.gdc.goog/vpc=default-vpc,ipam.gdc.goog/usage=network-root-range
Replace
GLOBAL_API_SERVER_KUBECONFIG
with the path to the kubeconfig file of the global API server. For more information, see Global API server resources. The labels are constant and must remain the same.The output is similar to the following:
Name: default-vpc-root-cidr Namespace: platform Labels: ipam.gdc.goog/allocation-preference=default ipam.gdc.goog/subnet-group=default-vpc-root-group ipam.gdc.goog/usage=network-root-range ipam.gdc.goog/vpc=default-vpc Annotations: <none> API Version: ipam.global.gdc.goog/v1 Kind: Subnet Metadata: Creation Timestamp: 2025-06-18T23:05:38Z Finalizers: global-subnet-finalizer Generation: 1 Resource Version: 439434 UID: 5ed1c51a-b5ee-473e-a185-8e065a87ae8f Spec: ipv4Request: Cidr: 10.252.0.0/14 Propagation Strategy: None Type: Root Status: Children Refs: Name: default-vpc-zone1-root-cidr Namespace: platform Type: SingleSubnet Conditions: Last Transition Time: 2025-06-18T23:05:38Z Message: IP allocation finished successfully Observed Generation: 1 Reason: AllocationSucceeded Status: True Type: Ready ipv4Allocation: Available CIDRs: 10.254.0.0/15 10.253.0.0/16 Cidr: 10.252.0.0/14 Events: <none>
Note the
Status.ipv4Allocation.Available CIDRs
values as the available CIDRs, which will be referenced in the next step. In the previous output, the CIDR ranges10.254.0.0/15
and10.253.0.0/16
are available. There can be multiple subnets in your output depending on the number of root subnets you have, so note all the available CIDRs, and note from which subnet the available CIDR is from.Compare the largest available CIDR you noted from the previous step with the size of the CIDR you need to allocate to your zone. If the largest available CIDR is not large enough to allocate your new subnet, add a new network root range global subnet before you continue. Note the parent subnet from which you decide to get the CIDR for your new subnet.
For example, if you require a
/13
CIDR, but the available CIDRs only include/15
and/16
, you must add a new network root range global subnet. If you require a/15
subnet, you can allocate a new zonal subnet from the existing/15
CIDR.Create the new subnet in the global API server:
kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG apply -f - <<EOF apiVersion: ipam.global.gdc.goog/v1 kind: Subnet metadata: labels: ipam.gdc.goog/vpc: default-vpc ipam.gdc.goog/usage: zone-network-root-range name: SUBNET_NAME namespace: platform spec: ipv4Request: prefixLength: CIDR_PREFIX_LENGTH zone: ZONE_NAME propagationStrategy: SingleZone type: Branch parentReference: name: PARENT_SUBNET_NAME namespace: ORG_NAME EOF
Replace the following:
GLOBAL_API_SERVER_KUBECONFIG
: the path to the kubeconfig file of the global API server. For more information, see Global API server resources.SUBNET_NAME
: the name of the new subnet.CIDR_PREFIX_LENGTH
: the CIDR prefix length of the new subnet that is dynamically allocated, such as20
. To statically set the CIDR, replace theprefixLength
field with thecidr
field, and then set the CIDR block, such as10.0.10.0/27
.ZONE_NAME
: the zone for which to allocate the subnet, such aszone1
.PARENT_SUBNET_NAME
: the name of the parent subnet, such asdefault-vpc-root-cidr
, or the new network root range global subnet you created.ORG_NAME
: the name of the organization.
See the API reference documentation for the global
Subnet
resource for more information.Verify the subnet is ready and available in the global API server by checking that its status
Ready
type istrue
:kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG get subnet --namespace platform \ SUBNET_NAME --output jsonpath='{.status.conditions[?(@.type=="Ready")].status}'
The output is similar to the following:
status: conditions: - lastTransitionTime: "2025-06-06T07:28:48Z" message: IP allocation finished successfully observedGeneration: 1 reason: AllocationSucceeded status: "True" type: Ready
Verify the zonal subnet is created in the zonal management API server, and its status
Ready
type istrue
:kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG get subnet --namespace platform \ SUBNET_NAME --output jsonpath='{.status.conditions[?(@.type=="Ready")].status}'
Replace
MANAGEMENT_API_SERVER_KUBECONFIG
with the path to the kubeconfig file of your management API server. For more information, see Zonal management API server resources.The output is similar to the following:
status: conditions: - lastTransitionTime: "2025-06-06T07:29:34Z" message: IP allocation finished successfully observedGeneration: 1 reason: AllocationSucceeded status: "True" type: Ready
From this new zonal subnet, you can create more zonal child subnets or allocate an individual IP address directly to an internal workload.
Divide root global subnet without zone allocation
To further divide a global subnet without allocating it to a zone for your
workloads to use, create a global subnet and don't define a propagation strategy
in the Subnet
custom resource. This approach is useful if you want to continue
organizing your globally accessible IP address range from the global root subnet
without allocating the IP addresses to a zone.
Complete the following steps in the platform
namespace to divide your global
root subnet within the global scope only:
In a terminal window, describe all of the Default VPC's root subnets and check their available CIDRs:
kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG describe subnets --namespace platform \ --label ipam.gdc.goog/vpc=default-vpc,ipam.gdc.goog/usage=network-root-range
Replace
GLOBAL_API_SERVER_KUBECONFIG
with the path to the kubeconfig file of the global API server. For more information, see Global API server resources. The labels are constant and must remain the same.The output is similar to the following:
Name: default-vpc-root-cidr Namespace: platform Labels: ipam.gdc.goog/allocation-preference=default ipam.gdc.goog/subnet-group=default-vpc-root-group ipam.gdc.goog/usage=network-root-range ipam.gdc.goog/vpc=default-vpc Annotations: <none> API Version: ipam.global.gdc.goog/v1 Kind: Subnet Metadata: Creation Timestamp: 2025-06-18T23:05:38Z Finalizers: global-subnet-finalizer Generation: 1 Resource Version: 439434 UID: 5ed1c51a-b5ee-473e-a185-8e065a87ae8f Spec: ipv4Request: Cidr: 10.252.0.0/14 Propagation Strategy: None Type: Root Status: Children Refs: Name: default-vpc-zone1-root-cidr Namespace: platform Type: SingleSubnet Conditions: Last Transition Time: 2025-06-18T23:05:38Z Message: IP allocation finished successfully Observed Generation: 1 Reason: AllocationSucceeded Status: True Type: Ready ipv4Allocation: Available CIDRs: 10.254.0.0/15 10.253.0.0/16 Cidr: 10.252.0.0/14 Events: <none>
Note the
Status.ipv4Allocation.Available CIDRs
values as the available CIDRs, which will be referenced in the next step. In the previous output, the CIDR ranges10.254.0.0/15
and10.253.0.0/16
are available. There can be multiple subnets in your output depending on the number of root subnets you have, so note all the available CIDRs, and note from which subnet the available CIDR is from.Compare the largest available CIDR you noted from the previous step with the size of the CIDR you need to allocate to your new global subnet. If the largest available CIDR is not large enough to allocate your new subnet, add a new network root range global subnet before you continue. Note the parent subnet from which you decide to get the CIDR for your new subnet.
For example, if you require a
/13
CIDR, but the available CIDRs only include/15
and/16
, you must create a new network root range global subnet. If you require a/15
subnet, you can allocate the new global subnet from the existing/15
CIDR.Create the new subnet in the global API server:
kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG apply -f - <<EOF apiVersion: ipam.global.gdc.goog/v1 kind: Subnet metadata: labels: ipam.gdc.goog/vpc: default-vpc ipam.gdc.goog/usage: zone-network-root-range name: SUBNET_NAME namespace: platform spec: ipv4Request: prefixLength: CIDR_PREFIX_LENGTH propagationStrategy: None type: Branch parentReference: name: PARENT_SUBNET_NAME namespace: ORG_NAME EOF
Replace the following:
GLOBAL_API_SERVER_KUBECONFIG
: the path to the kubeconfig file of the global API server. For more information, see Global API server resources.SUBNET_NAME
: the name of the new subnet.CIDR_PREFIX_LENGTH
: the CIDR prefix length of the new subnet that is dynamically allocated, such as20
. To statically set the CIDR, replace theprefixLength
field with thecidr
field, and then set the CIDR block, such as10.0.10.0/27
.PARENT_SUBNET_NAME
: the name of the parent subnet, such asdefault-vpc-root-cidr
, or the new network root range global subnet you created.ORG_NAME
: the name of the organization.
See the API reference documentation for the global
Subnet
resource for more information.Verify the subnet is ready and available in the global API server by checking that its status
Ready
type istrue
:kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG get subnet --namespace platform \ SUBNET_NAME --output jsonpath='{.status.conditions[?(@.type=="Ready")].status}'
The output is similar to the following:
status: conditions: - lastTransitionTime: "2025-06-06T07:28:48Z" message: IP allocation finished successfully observedGeneration: 1 reason: AllocationSucceeded status: "True" type: Ready
The new global subnet for your organization in the Default VPC is available. You can create a subnet for a particular zone from this new global parent subnet.
Add new network root range global subnet
Global subnets with the ipam.gdc.goog/usage: network-root-range
label host the
CIDR for all the zones of the network. If the CIDR is used up, you must create a
new network root range subnet in the global API server. You can create
multiple root global subnets, if needed.
To create a new network root range subnet, complete the following:
In a terminal window, create the new network root range global subnet for the Default VPC in the
platform
namespace:kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG apply -f - <<EOF apiVersion: ipam.global.gdc.goog/v1 kind: Subnet metadata: labels: ipam.gdc.goog/vpc: default-vpc ipam.gdc.goog/usage: network-root-range name: SUBNET_NAME namespace: platform spec: ipv4Request: cidr: NEW_CIDR type: Root EOF
Replace the following:
GLOBAL_API_SERVER_KUBECONFIG
: the path to the kubeconfig file of the global API server. For more information, see Global API server resources.SUBNET_NAME
: the name of the new subnet.NEW_CIDR
: the new CIDR for the subnet. This CIDR cannot overlap with any CIDR in all the existing subnets with theipam.gdc.goog/usage: network-root-range
label in the same global API server.
This new global root range subnet can be subdivided within the global API server or allocated to a specific zone.
What's next
- Subnets and IP addresses
- Networking overview
- Deploy a highly available VM application
- Deploy a highly available container application