Create and use internal ranges

This document describes how to create, use, and delete internal ranges.

Internal ranges help you manage a unified IP address space across Virtual Private Cloud (VPC) networks by letting you allocate blocks of internal IP addresses and specify how those blocks can be used.

Before you begin

To use the command-line examples in this guide, install or update to the latest version of the Google Cloud CLI.
You must enable the Network Connectivity API in your project.
Identify or create a VPC network.

Required roles

To get the permissions that you need to work with internal ranges, ask your administrator to grant you the Compute Network Admin (roles/compute.networkAdmin) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Reserve internal ranges

You specify at least two things when creating an internal range: the IP addresses to allocate and the network to allocate the addresses in. You can create an IPv4 or IPv6 internal range with a specific CIDR block, or you can have Google Cloud allocate an IPv4 block automatically. You can't create an IPv6 internal range with an automatically allocated address block.

When you request an automatically allocated IPv4 CIDR block, you provide a prefix length and one or more optional target IPv4 CIDR blocks. If you don't specify a target CIDR block, Google Cloud uses the following default target ranges:

For custom mode VPC networks, the default ranges are 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16.
For auto mode VPC networks, the default ranges are 10.0.0.0/9, 172.16.0.0/12, and 192.168.0.0/16.

Google Cloud accounts for existing IP address allocations and allocates the internal range a free CIDR block of the chosen size from within the target CIDR blocks. You can further refine this allocation by providing an optional list of CIDR blocks to exclude. Google Cloud allocates an IP address block to the internal range that doesn't overlap with any excluded block. The list of excluded blocks can't be updated after you create an internal range.

To control the method that Google Cloud uses to automatically select a free block, you can specify an allocation strategy. If you don't specify an allocation strategy, Google Cloud randomly allocates a free IP address range from within the target CIDR blocks (or the default range, if no target CIDR blocks are specified).

IPv6 internal ranges let you prevent the automatic assignment of IP addresses to new IPv6-only or dual-stack subnets. IPv6 internal ranges must have the usage type EXTERNAL_TO_VPC and the peering type FOR_SELF. You must include a specific IPv6 CIDR block, and the overlaps field must be empty or unspecified.

To prevent users from updating an internal range's CIDR block or overlap configuration, you can create an immutable internal range. Immutable internal ranges prevent changes to these properties, but you can still update the description. Immutability can't be changed after the internal range is created.

By default, Google Cloud blocks the creation of internal ranges or resources if they share overlapping IP addresses in the same VPC network. You can configure an IPv4 internal range to allow overlap with the address ranges of existing subnets, new and existing routes, or both. You can't create Google Cloud resources that use IP addresses from an existing internal range, unless you explicitly associate the resource with the internal range (for subnets) or configure overlapping (for routes).

Console

In the Google Cloud console, go to the Internal ranges page.

Go to Internal ranges
Click Reserve internal range.
Enter a name.
Optional: Enter a description.
Select an IP version.
- If you select IPv4, do the following:
  1. Specify whether the internal range is immutable.
  2. Select a reservation method.
    - If you select Automatic, do the following:
      1. Select an allocation algorithm.
      2. Select a prefix length.
      3. Enter a target IP address range. You can add multiple target ranges.
      4. Optional: Click Add a range to exclude, and then enter an IP address range to exclude. You can add multiple excluded ranges.
        
        Google Cloud allocates an IP address block to the internal range that doesn't overlap with any excluded range. This list can't be updated after the internal range is created.
    - If you select Let me specify, enter an IP range in CIDR notation.
  3. Select a network.
  4. Select a peering type.
  5. Select a usage type.
  6. Optional: In the Allowed overlaps section, specify whether the internal range can overlap with existing subnets, new and existing routes, or both.
- If you select IPv6, do the following:
  1. Specify whether the internal range is immutable.
  2. Select Let me specify, and then enter an IPv6 or IPv4-mapped IPv6 CIDR block.
  3. Select a network.
  4. Click Peering, and then select For self.
  5. Click Usage, and then select External to VPC.
Click Reserve.

gcloud

To reserve an internal range for a specific IPv4 or IPv6 CIDR block, use the gcloud network-connectivity internal-ranges create command.
```
gcloud network-connectivity internal-ranges create RANGE_NAME \
    --ip-cidr-range=CIDR_RANGE \
    --network=NETWORK_NAME \
    --description="DESCRIPTION" \
    --peering=PEERING_TYPE \
    --usage=USAGE_TYPE
```
Replace the following:
- RANGE_NAME: the name of the new internal range
- CIDR_RANGE: the IPv4, IPv6, or IPv4-mapped IPv6 CIDR block to allocate to the new internal range
  - If you specify an IPv6 block, you must do the following:
    - Set the peering type to FOR_SELF.
    - Set the usage type to EXTERNAL_TO_VPC.
- NETWORK_NAME: the name of the network to create the internal range in
- DESCRIPTION: an optional description of the internal range
- PEERING_TYPE: the peering type of the internal range
  
  Options are FOR_SELF, FOR_PEER, and NOT_SHARED. FOR_SELF is the default.
- USAGE_TYPE: the usage type of the internal range
  
  Options are FOR_VPC, EXTERNAL_TO_VPC, and FOR_MIGRATION. The default value is FOR_VPC.
  - If you use the FOR_MIGRATION option, you must also specify source and target subnets. For an example, see Reserve IPv4 internal ranges for subnet migration.
To reserve an IPv4 internal range with an automatically allocated CIDR block, use the following command:
```
gcloud network-connectivity internal-ranges create RANGE_NAME \
    --network=NETWORK_NAME \
    --prefix-length=PREFIX_LENGTH \
    --target-cidr-range=TARGET_CIDR_RANGE \
    --peering=PEERING_TYPE \
    --usage=USAGE_TYPE \
    --description="DESCRIPTION" \
    --allocation-strategy=ALLOCATION_STRATEGY
    [--first-available-ranges-lookup-size=FIRST_N_LOOKUP_SIZE]
```
Replace the following:
- PREFIX_LENGTH: the prefix length of the allocated IP addresses
- TARGET_CIDR_RANGE: the target CIDR block from which to allocate an IPv4 address block
  - For custom mode VPC networks, the default CIDR blocks are 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16.
  - For auto mode VPC networks, the default CIDR blocks are 10.0.0.0/9, 172.16.0.0/12, and 192.168.0.0/16.
  You can enter multiple CIDR blocks in a comma-separated list.
- ALLOCATION_STRATEGY: the allocation strategy that you want to use for this internal range's CIDR block
  
  Options are RANDOM, FIRST_AVAILABLE, RANDOM_FIRST_N_AVAILABLE, and FIRST_SMALLEST_FITTING. The default is RANDOM.
- FIRST_N_LOOKUP_SIZE: for the RANDOM_FIRST_N_AVAILABLE allocation strategy, the number of free CIDR blocks to find before randomly determining one
  
  Only include this flag if you choose the RANDOM_FIRST_N_AVAILABLE allocation strategy.
If you want to exclude IP address ranges when reserving an IPv4 internal range with an automatically allocated CIDR block, use the following command:
```
gcloud alpha network-connectivity internal-ranges create RANGE_NAME \
    --network=NETWORK_NAME \
    --prefix-length=PREFIX_LENGTH \
    --target-cidr-range=TARGET_CIDR_RANGE \
    --peering=PEERING_TYPE \
    --usage=USAGE_TYPE \
    --description="DESCRIPTION" \
    --exclude-cidr-ranges=EXCLUDED_RANGES
```
Replace EXCLUDED_RANGES with a comma-separated list of one or more IPv4 CIDR blocks to exclude. Google Cloud allocates an IP address block to the internal range that doesn't overlap with any excluded block. The list can't be updated after the internal range is created.

To reserve an IPv4 internal range with overlap, use the following command:

gcloud network-connectivity internal-ranges create RANGE_NAME \
    --ip-cidr-range=CIDR_RANGE \
    --network=NETWORK_NAME \
    --description="DESCRIPTION" \
    --peering=PEERING_TYPE \
    --usage=USAGE_TYPE \
    --overlaps=OVERLAPS

Replace OVERLAPS with the type of overlap to allow. Options are OVERLAP_EXISTING_SUBNET_RANGE and OVERLAP_ROUTE_RANGE. You can include both values in a comma-separated list.

To reserve an immutable internal range, use the following command:

gcloud network-connectivity internal-ranges create RANGE_NAME \
    --ip-cidr-range=CIDR_RANGE \
    --network=NETWORK_NAME \
    --description="DESCRIPTION" \
    --peering=PEERING_TYPE \
    --usage=USAGE_TYPE \
    --immutable

API

To reserve an internal range for a specific IPv4 or IPv6 CIDR block, make a POST request to the projects.locations.internalRanges.create method.
```
POST https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/global/internalRanges?internalRangeId=RANGE_NAME
{
  "ipCidrRange": "CIDR_RANGE",
  "network": "NETWORK_NAME",
  "description": "DESCRIPTION",
  "peering": "PEERING_TYPE",
  "usage": "USAGE_TYPE"
}
```
Replace the following:
- PROJECT_ID: the ID of the parent project for the internal range
- RANGE_NAME: the name of the internal range
- CIDR_RANGE: the IPv4, IPv6, or IPv4-mapped IPv6 CIDR block to allocate to the internal range
  - If you specify an IPv6 block, you must do the following:
    - Set the peering type to FOR_SELF.
    - Set the usage type to EXTERNAL_TO_VPC.
- NETWORK_NAME: the name of the network to create the internal range in
- DESCRIPTION: an optional description of the new internal range
- PEERING_TYPE: the peering type of the internal range
  
  Options are FOR_SELF, FOR_PEER, and NOT_SHARED. FOR_SELF is the default.
- USAGE_TYPE: the usage type of the internal range
  
  Options are FOR_VPC, EXTERNAL_TO_VPC, and FOR_MIGRATION. The default value is FOR_VPC.
  - If you use the FOR_MIGRATION option, you must also specify source and target subnets. For an example, see Reserve IPv4 internal ranges for subnet migration.
To reserve an IPv4 internal range with an automatically allocated CIDR block, make the following request:
```
POST https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/global/internalRanges?internalRangeId=RANGE_NAME
{
  "prefixLength": PREFIX_LENGTH,
  "targetCidrRange": "TARGET_CIDR_RANGE",
  "network": "NETWORK_NAME",
  "description": "DESCRIPTION",
  "peering": "PEERING_TYPE",
  "usage": "USAGE_TYPE",
  "allocationOptions": {
    "allocationStrategy": "ALLOCATION_STRATEGY",
    ["firstAvailableRangesLookupSize": FIRST_N_LOOKUP_SIZE]
  }
}
```
Replace the following:
- PREFIX_LENGTH: the CIDR prefix length for the range's IP address block
- TARGET_CIDR_RANGE: the target CIDR block from which to allocate an IPv4 address block
  - For custom mode VPC networks, the default CIDR blocks are 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16.
  - For auto mode VPC networks, the default CIDR blocks are 10.0.0.0/9, 172.16.0.0/12, and 192.168.0.0/16.
  You can specify multiple CIDR blocks in a JSON array.
- ALLOCATION_STRATEGY: the allocation strategy that you want to use for this internal range's CIDR block
  
  Options are RANDOM, FIRST_AVAILABLE, RANDOM_FIRST_N_AVAILABLE, and FIRST_SMALLEST_FITTING. The default is RANDOM.
- FIRST_N_LOOKUP_SIZE: For the RANDOM_FIRST_N_AVAILABLE allocation strategy, the number of free CIDR blocks to find before randomly determining one
  
  Only include this field if you choose the RANDOM_FIRST_N_AVAILABLE allocation strategy.
If you want to exclude IP address ranges when reserving an IPv4 internal range with an automatically allocated CIDR block, make the following request:
```
POST https://networkconnectivity.googleapis.com/v1alpha1/projects/PROJECT_ID/locations/global/internalRanges?internalRangeId=RANGE_NAME
{
  "prefixLength": PREFIX_LENGTH,
  "targetCidrRange": "TARGET_CIDR_RANGE",
  "network": "NETWORK_NAME",
  "description": "DESCRIPTION",
  "peering": "PEERING_TYPE",
  "usage": "USAGE_TYPE",
  "excludeCidrRanges": ["EXCLUDED_RANGE_1","EXCLUDED_RANGE_2"]
}
```
Replace EXCLUDED_RANGE_1 and EXCLUDED_RANGE_2 with one or more IPv4 CIDR blocks to exclude. Google Cloud allocates an IP address block to the internal range that doesn't overlap with any excluded block. The list can't be updated after the internal range is created.

To reserve an IPv4 internal range with overlap, make the following request:

POST https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/global/internalRanges?internalRangeId=RANGE_NAME
{
  "ipCidrRange": "CIDR_RANGE",
  "network": "NETWORK_NAME",
  "description": "DESCRIPTION",
  "peering": "PEERING_TYPE",
  "usage": "USAGE_TYPE",
  "overlaps": ["OVERLAPS"]
}

Replace OVERLAPS with the type of overlap to allow. Options are OVERLAP_EXISTING_SUBNET_RANGE and OVERLAP_ROUTE_RANGE. You can include both values in a JSON array.

To reserve an immutable internal range, make the following request:

POST https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/global/internalRanges?internalRangeId=RANGE_NAME
{
  "ipCidrRange": "CIDR_RANGE",
  "network": "NETWORK_NAME",
  "description": "DESCRIPTION",
  "peering": "PEERING_TYPE",
  "usage": "USAGE_TYPE",
  "immutable": true
}

Reserve IPv4 internal ranges for subnet migration

You can use an internal range to migrate a CIDR range from one subnet to another. For more information, see Migrating IPv4 subnet ranges.