Bring your own IP addresses with external subnets

This page describes how to create additional subnets in your organization's Data Network Segment to support your external networking requirements. You must add subnets to make sure your external services, such as egress network address translation (NAT) and external load balancers, have a sufficient number of IP addresses to support their networking requirements for connecting to external networks outside 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 external services: This task is useful to further organize or allocate your zone's existing external IP addresses to services.
• Create a leaf subnet for an individual service: This task is useful when you have a new service 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 external IP address space.
• Divide root global subnet without zone allocation: This task is useful to further organize the external 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 Data Network Segment no longer has sufficient global external 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 external services

You can create a zonal external subnet from the zone's existing zonal root subnet to further subdivide IP addresses in your zonal Data Network Segment. You must create this subnet type in the platform namespace. If the parent zonal root subnet does not have enough IP addresses available, allocate another zonal subnet from the global IP address range first and then return to this procedure.

• In a terminal window, create the new external subnet in the zonal management API server:

  kubectl -kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG apply -f - <<EOF
  apiVersion: ipam.gdc.goog/v1
  kind: Subnet
  metadata:
    labels:
      ipam.gdc.goog/network-segment: data
    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 as 20. To statically set the CIDR, replace the prefixLength field with the cidr field, and then set the CIDR block, such as 10.0.10.0/27.

  • PARENT_SUBNET_NAME: the name of the parent subnet, such as data-external-zone0-cidr. The parent subnet is typically a zonal root subnet in the Data Network Segment.

  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 external service.

Create a leaf subnet for an individual service

You must create a leaf subnet to allocate a single IP address for your service. This leaf subnet must have the field value type: Leaf and must reside in the same project namespace as your external service, such as an external load balancer or egress NAT.

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/network-segment: data
    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 services 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 external service. For more information on how to configure the IP address for your service, see the corresponding service documentation, such as Configure external load balancers.

Allocate zonal subnet from global IP address range

If your zone does not provide sufficient IP addresses for your external services 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 Data Network Segment in the platform namespace:

1. In a terminal window, describe all of the Data Network Segment's root subnets and check their available CIDRs:

   kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG describe subnets --namespace platform \
       --label ipam.gdc.goog/network-segment=data,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:         data-external-root-cidr
   Namespace:    platform
   Labels:       ipam.gdc.goog/allocation-preference=default
                 ipam.gdc.goog/subnet-group=data-external-root-group
                 ipam.gdc.goog/usage=network-root-range
                 ipam.gdc.goog/network-segment=data
   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:       data-external-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 ranges 10.254.0.0/15 and 10.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.

2. 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 create 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.

3. 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/network-segment: data
       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 as 20. To statically set the CIDR, replace the prefixLength field with the cidr field, and then set the CIDR block, such as 10.0.10.0/27.
   • ZONE_NAME: the zone for which to allocate the subnet, such as zone1.
   • PARENT_SUBNET_NAME: the name of the parent subnet, such as data-external-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.

4. Verify the subnet is ready and available in the global API server by checking that its status Ready type is true:

   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
   

5. Verify the zonal subnet is created in the zonal management API server, and its status Ready type is true:

   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 external service.

Divide root global subnet without zone allocation

If you want to continue organizing your globally accessible IP address range from the global root subnet without allocating the IP addresses to your zonal external services, create a global subnet and don't define a propagation strategy in the Subnet custom resource.

Complete the following steps in the platform namespace to divide your global root subnet within the global scope only:

1. In a terminal window, describe all of the Data Network Segment's root subnets and check their available CIDRs:

   kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG describe subnets --namespace platform \
       --label ipam.gdc.goog/network-segment=data,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:         data-external-root-cidr
   Namespace:    platform
   Labels:       ipam.gdc.goog/allocation-preference=default
                 ipam.gdc.goog/subnet-group=data-external-root-group
                 ipam.gdc.goog/usage=network-root-range
                 ipam.gdc.goog/network-segment=data
   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:       data-external-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 ranges 10.254.0.0/15 and 10.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.

2. 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.

3. 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/network-segment: data
       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 as 20. To statically set the CIDR, replace the prefixLength field with the cidr field, and then set the CIDR block, such as 10.0.10.0/27.
   • PARENT_SUBNET_NAME: the name of the parent subnet, such as data-external-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.

4. Verify the subnet is ready and available in the global API server by checking that its status Ready type is true:

   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 Data Network Segment 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 Data Network Segment 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/network-segment: data
      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 the ipam.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
• Configure external load balancers