Configure alias IP ranges

This document contains instructions for configuring alias IP addresses and aliasIP ranges by using the Google Cloud console and the Google Cloud CLI.Before executing these commands, reviewAlias IP ranges.

Limitations

Subnet

  • The per networklimits describe the maximumnumber of secondary ranges that you can define for each subnet.
  • You cannot addand remove secondary ranges at the same time. Adding andremoving must be done as separate steps.
  • CIDR expansion isn't supported for secondary ranges.

VM instance

  • Alias IP ranges are supported on all virtual machine (VM) network interfaces.Routing isconfigured automatically for alias IP ranges on the primary networkinterface but not on secondary interfaces. If you havemultiple network interfaces,you must configure policy routing for the additional interfaces. For anexample of how to do this, see the following tutorial:Configure routing for an additional network interface.
  • Alias IP ranges can be added or deleted, but they can't be updated.
  • If you remove an alias IP range from one VM and assign it to another VM, itmight take up to a minute for the transfer to complete.
  • Firewall source tags aren't supported for alias IP addresses. This meansthat when you configure source tags in firewall rules, the source tagsmatch the VM primary IP address but not the alias IP addresses.Use source ranges to allow or deny ingress traffic from alias IP addresses.
  • Internal DNS resolves a VM name to its primary IP. Additional names foralias IPs aren't configured automatically but might be added manually.

VPC network

  • Adding or removing a large number of alias IP ranges at the same timecan take a long time. For example, it might take up to 10 minutes to add ordelete 7,000 alias IP ranges.
  • Auto mode Virtual Private Cloud (VPC) networks can't be deleted if secondarysubnet ranges are present.
  • In a static route, the next-hop IP address must be the primary IP addressof the VM. Alias IP addresses aren't supported as next-hop IP addresses.
  • IPv6 addresses aren't supported.
  • Alias IP ranges are only supported in VPC networks, not legacynetworks. Todetermine your network type, list your networks. VPC networks have a modeofcustom orauto. Legacy networks have a mode oflegacy.

Subnet commands

VM alias IP ranges must be assigned from a range owned by the subnet thatthe VM is in. All subnets have a primary range, which is the standardrange of internal IP addresses that defines the subnet. A subnet can alsohave one or more secondary IP ranges of internal IP addresses. You canassign alias IP ranges from either the primary or secondary ranges of thesubnet.

You must give each secondary range a name that is unique for the subnet. Whenassigning an alias IP range to a VM, the secondary range name tellsGoogle Cloud from which subnet range to assign the alias IPs.

All ranges, both primary and secondary, must be unique across all subnets in theVPC network and in any networks attached by usingVPC Network Peering, Cloud VPN, or Cloud Interconnect.

This section shows you how to create a subnet with a secondary range, add asecondary range to an existing subnet, or remove a secondary range from asubnet. After your subnet has the range you want to use, see theWork with VM instances section for information aboutassigning a range to a VM.

Create a subnet with one or more secondary CIDR ranges

This command assumes you have a VPC network already. If youdonot,create one.

This command is the same whether you are creating a subnet for the VM's primaryinterface or one of thesecondary interfaces.

Using a secondary range for alias IP allocation lets you separate theIP space for services hosted in the VM, which helps you createfirewall rules that allow access only to the services running on the VMand block access to the VM's primary IP address.

Console

  1. In the Google Cloud console, go to theVPC networks page.

    Go to VPC networks

  2. Click the name of an existing network.

  3. ClickAdd subnet.

  4. Enter a name for the new subnet.

  5. Specify the region.

  6. Enter an IP address range in CIDR notation—for example,10.65.61.0/24.

  7. ClickCreate secondary IP range.

  8. Enter a subnet range name.

  9. Enter a secondary IP range in CIDR notation—for example,10.9.0.0/24.

  10. To add secondary IP ranges, for each range, clickAdd IP range, then provide a name and range.

  11. ClickAdd.

gcloud

gcloud compute networks subnets create s1 \    --networkNETWORK_NAME \    --regionREGION \    --range 10.65.61.0/24 \    --secondary-rangeRANGE_NAME_1=RANGE_CIDR_1,RANGE_NAME_2=RANGE_CIDR_2,...

Replace the following:

  • NETWORK_NAME: the name of the network where youwant to create the subnet.
  • REGION: the region where you are creating thesubnet.
  • RANGE_NAME_1=RANGE_CIDR_1andRANGE_NAME_2=RANGE_CIDR_2:the names of the secondary ranges from which to draw the alias IP ranges andthe alias IP range itself—for example,range1=10.9.0.0/24.

For the complete syntax, see thegcloud documentation.

API

Create a subnet with one or more secondary ranges.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/subnetworks{  "ipCidrRange": "PRIMARY_IP_RANGE",  "network": "NETWORK_URL",  "name": "SUBNET_NAME",  "secondaryIpRanges": [  {    "rangeName": "SECONDARY_RANGE_NAME_1",    "ipCidrRange": "SECONDARY_IP_RANGE_1"  },  {    "rangeName": "SECONDARY_RANGE_NAME_2",    "ipCidrRange": "SECONDARY_IP_RANGE_2"  },  ...]}

Replace the following:

  • PROJECT_ID: the ID of the project that containsthe VPC network where the subnet is to be created.
  • REGION: the region where the subnet is to belocated.
  • PRIMARY_IP_RANGE: the primary IP address rangefor the subnet.
  • NETWORK_URL: the URL or the VPCnetwork where the subnet is to be created.
  • SUBNET_NAME: a name for the subnet.
  • SECONDARY_RANGE_NAME_1 andSECONDARY_RANGE_NAME_2:the names to use for the secondary ranges.
  • SECONDARY_IP_RANGE_1 andSECONDARY_IP_RANGE_2:the IP address ranges to use for the secondary ranges.

For more information, see thesubnetworks.insert method.

Terraform

You can use theTerraformresourceto create a subnet with one or more secondary ranges.

The Terraform arguments have example values that you can change.

resource "google_compute_subnetwork" "network-with-private-secondary-ip-ranges" {  project       = var.project_id # Replace this with your project ID in quotes  name          = "test-subnetwork"  ip_cidr_range = "10.2.0.0/16"  region        = "us-central1"  network       = "test-vpc-network"  secondary_ip_range {    range_name    = "tf-test-secondary-range-update1"    ip_cidr_range = "192.168.10.0/24"  }}

To learn how to apply or remove a Terraform configuration, seeBasic Terraform commands.

Add secondary CIDR ranges to an existing subnet

This procedure assumes you have a subnet that you want to use, but you need toadd one or more secondary ranges.

We recommend using a secondary range for alias IP allocation to createfirewall rules that allow access to the services running on a VM, but not tothe VM's primary IP address.

Console

  1. In the Google Cloud console, go to theVPC networks page.

    Go to VPC networks

  2. Click the name of a subnet to modify to view its details page.

  3. ClickEdit.

  4. In theSecondary IP ranges section, clickAdd IP range.

  5. Enter a name forSubnet range name.

  6. Enter a range forSecondary IP range in CIDR notation—for example,10.9.0.0/24.

  7. To add secondary IP ranges, for each range, clickAdd IP range, then provide a name and range.

  8. ClickSave.

gcloud

gcloud compute networks subnets updateSUBNET_NAME \    --regionREGION \    --add-secondary-rangesRANGE_NAME_1=RANGE_CIDR_1,RANGE_NAME_2=RANGE_CIDR_2,...

Replace the following:

  • SUBNET_NAME: the name of the subnet that you wantto add the secondary ranges to.
  • REGION: the region where you are creating thesubnet.
  • RANGE_NAME_1=RANGE_CIDR_1andRANGE_NAME_2=RANGE_CIDR_2:the names of the secondary ranges from which to draw the alias IP rangesand the alias IP range itself—for example,range1=10.9.0.0/24.

For the complete syntax, see thegcloud documentation.

API

Add a secondary range to an existing subnet.

PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME{  "secondaryIpRanges": [  {    "rangeName": "SECONDARY_RANGE_NAME_1",    "ipCidrRange": "SECONDARY_IP_RANGE_1"  },  {    "rangeName": "SECONDARY_RANGE_NAME_2",    "ipCidrRange": "SECONDARY_IP_RANGE_2"  },  ...],  "fingerprint": "SUBNET_FINGERPRINT"}

Replace the following:

  • PROJECT_ID: the ID of the project that containsthe subnet to modify.
  • REGION: the region where the subnet is located.
  • SUBNET_NAME: the name of the subnet to modify.
  • SECONDARY_RANGE_NAME_1 andSECONDARY_RANGE_NAME_2: the names to use forthe secondary ranges.
  • SECONDARY_IP_RANGE_1 andSECONDARY_IP_RANGE_2: the IP address rangesto use for the secondary ranges.
  • SUBNET_FINGERPRINT: the fingerprint ID forthe existing subnet, which is provided when youdescribe asubnet.

For more information, see thesubnetworks.patch method.

Remove a secondary CIDR range from a subnet

You can remove existing secondary ranges from a subnet. To view the ranges thatare associated with a subnet, seeDescribe asubnet.

Console

  1. In the Google Cloud console, go to theVPC networks page.

    Go to VPC networks

  2. Click the name of a subnet to modify to view its details page.

  3. ClickEdit.

  4. In theSecondary IP ranges section, clickX next to the secondaryrange to remove.

  5. ClickSave.

gcloud

gcloud compute networks subnets updateSUBNET_NAME \    --regionREGION \    --remove-secondary-rangesRANGE_NAME_1,RANGE_NAME_2,...

Replace the following:

  • SUBNET_NAME: the name of the subnet that you wantto remove the secondary ranges from.
  • REGION: the region where you are creating thesubnet.
  • RANGE_NAME_1 andRANGE_NAME_2: the names of the secondary rangesto be removed from the target subnetSUBNET_NAME—for example,range1=10.9.0.0/24.

For the complete syntax, see thegcloud documentation.

API

Exclude secondary ranges to remove them. The following example removes allsecondary ranges from an existing subnet:

PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME{  "fingerprint": "SUBNET_FINGERPRINT",  "secondaryIpRanges": [  ]}

Replace the following:

  • PROJECT_ID: the ID of the project that containsthe subnet to modify.
  • REGION: the region where the subnet is located.
  • SUBNET_NAME: the name of the subnet to modify.
  • SUBNET_FINGERPRINT: the fingerprint ID for theexisting subnet, which is provided when youdescribe asubnet.

For more information, see thesubnetworks.patch method.

Work with VM instances

These commands show how to create an instance with an alias IP range, addone or more alias IP ranges to an existing VM instance, or remove one or moreranges from an existing VM instance.

Create a VM with an alias IP range in the primary CIDR range

Use this procedure if you want to assign an alias IP range from theprimary range of the subnet. The range you choose must not already be in use,even in part, by any other resource on the VPC network.

Use this procedure if you want the instance's primary interface and alias IPaddresses to be in the same range.

Console

  1. In the Google Cloud console, go to theVM instances page.

    Go to VM instances

  2. ClickCreate instance.

  3. Enter a name for the new instance.

  4. Specify a zone.

  5. ClickNetworking.

  6. In theNetwork interfaces section, expand the default networkinterface.

  7. InAlias IP ranges, clickAdd IP range.

  8. LeaveSubnet range 1 set toPrimary.

  9. InAlias IP range, enter an IP range in CIDR notation. This rangemust be an unused subrange of the primary range.

  10. ClickCreate.

gcloud

gcloud compute instances create vm1 \    --zoneZONE \    --network-interface "subnet=SUBNET_NAME,aliases=RANGE_CIDR_1;RANGE_CIDR_2,..."

Replace the following:

  • ZONE: the zone to contain the instance.
  • SUBNET_NAME: the name of the subnet to containthe instance.
  • RANGE_CIDR_1 andRANGE_CIDR_2: the IP ranges from the primarysubnet to assign to the interface. The ranges can be a specific range(192.168.100.0/24), a single IP address (192.168.100.1), or a netmaskin CIDR format (/24). If the IP range is specified by netmask only,the IP allocator chooses an available range with the specified netmaskand allocates it to the network interface. To specify more than one range,separate the ranges with semicolons (;).

For the complete syntax, see thegcloud documentation.

API

Create an instance with an alias IP address from the primary IP addressrange of the instance's subnet.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances{  "networkInterfaces": [    {      "aliasIpRanges": [        {          "ipCidrRange": "CIDR_RANGE"        }      ]    },    ...  ],  ...}

Replace the following:

  • PROJECT_ID: the ID of the project where youcreate the instance.
  • ZONE: the Google Cloud zone where theinstance is to be created.
  • CIDR_RANGE: the IP range from the primary subnetto assign to the interface. The range can be a specific range(192.168.100.0/24), a single IP address (192.168.100.1), or a netmaskin CIDR format (/24). If you specify the IP range by netmask only, theIP address allocator chooses an available range with the specified netmaskand assigns it to the network interface.

For more information, see theinstances.insert method.

Create a VM with an alias IP range in a secondary CIDR range

Use this procedure if you want to assign an alias IP range taken from asecondary range of the subnet. We recommend keeping the alias IP ranges separatefrom the primary range of the subnet to create firewall rulesthat allow access to the services running on a VM, but not to the VM'sprimary IP address.

Console

  1. In the Google Cloud console, go to theVM instances page.

    Go to VM instances

  2. ClickCreate instance.

  3. Enter a name for the new instance.

  4. Specify a zone.

  5. ClickNetworking.

  6. In theNetwork interfaces section, expand the default networkinterface.

  7. InAlias IP ranges, clickAdd IP range.

  8. InSubnet range, select the secondary IP range to use.

  9. ForAlias IP range, enter an IP range in CIDR notation. This rangemust be an unused range of the secondary IP range.

  10. ClickCreate.

gcloud

gcloud compute instances create vm3 \    --zoneZONE \    --network-interface subnet=SUBNET_NAME,aliases=RANGE_NAME:RANGE_CIDR

Replace the following:

  • ZONE: the zone to contain the instance.
  • SUBNET_NAME: the name of the subnet to containthe instance.
  • RANGE_NAME: the name of the subnet secondaryrange from which to draw the alias IP range.
  • RANGE_CIDR: the IP range to assign to theinterface. The range can be a specific range (192.168.100.0/24), asingle IP address (192.168.100.1), or a netmask in CIDR format(/24). If the IP range is specified by netmask only, the IP allocatorchooses an available range with the specified netmask and allocates itto the network interface.

For the complete syntax , see thegcloud documentation.

API

Create an instance with an alias IP address from the secondary IP addressrange of the instance's subnet.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances{  "networkInterfaces": [    {      "aliasIpRanges": [        {          "ipCidrRange": "SECONDARY_CIDR_RANGE",          "subnetworkRangeName": "SECONDARY_RANGE_NAME"        }      ]    },    ...  ],  ...}

Replace the following:

  • PROJECT_ID: the ID of the project where youcreate the instance.
  • ZONE: the Google Cloud zone where youcreate the instance.
  • SECONDARY_CIDR_RANGE: the IP range to assign tothe interface. The range can be a specific range (192.168.100.0/24),a single IP address (192.168.100.1), or a netmask in CIDR format(/24`). If you specify the IP range by netmask only, the IP addressallocator chooses an available range with the specified netmask andassigns it to the network interface.
  • SECONDARY_RANGE_NAME: the name of the subnetsecondary range from which to draw the alias IP range.

For more information, see theinstances.insert method.

Create a VM with multiple interfaces and alias IP addresses

This example creates two networks, each with one subnet, and a VM withinterfaces in both networks. If you already have two VPCnetworks, you can skip to the "Create a VM with interfaces in both networks"step.

Console

Create the first network and subnet:

  1. In the Google Cloud console, go to theVPC networks page.

    Go to VPC networks

  2. ClickCreate VPC network.

  3. ForName, entermy-network1.

  4. SetSubnet creation mode toCustom, then specify a subnet nameofmy-subnet1.

  5. Specify a region.

  6. SetIP address range to172.16.1.0/24.

  7. ClickCreate secondary IP range.

  8. SetSubnet range name torange1.

  9. SetSecondary IP range to10.1.0.0/16.

  10. ClickDone.

  11. ClickCreate.

Create the second network and subnet:

  1. In the Google Cloud console, go to theVPC networks page.

    Go to VPC networks

  2. ClickCreate VPC network.

  3. ForName, entermy-network2.

  4. SetSubnet creation mode toCustom, then specify a subnet nameofmy-subnet2.

  5. ForRegion, specify the same region as you did for the firstnetwork and subnet.

  6. SetIP address range to172.16.2.0/24.

  7. ClickCreate secondary IP range.

  8. SetSubnet range name torange2.

  9. SetSecondary IP range to10.2.0.0/16.

  10. ClickDone.

  11. ClickCreate.

Create a VM with interfaces in both networks:

  1. In the Google Cloud console, go to theVM instances page.

    Go to VM instances

  2. ClickCreate instance.

  3. Set the zone to the region where you created the subnets.

  4. ClickNetworking.

  5. Click the first network interface.

    1. SetNetwork tomy-network1.
    2. SetSubnetwork tomy-subnet1.
    3. ClickAlias IP ranges.
    4. ClickAdd IP range.
    5. SetSubnet range toPrimary.
    6. SetAlias IP range to/32.
    7. ClickAdd IP range.
    8. SetSubnet range torange1.
    9. SetAlias IP range to/24.
    10. ClickDone.

  6. ClickAdd network interface.

    1. Selectmy-network2.
    2. SetSubnetwork tomy-subnet2.
    3. ClickAlias IP ranges.
    4. ClickAdd IP range.
    5. SetSubnet range toPrimary.
    6. SetAlias IP range to/32.
    7. ClickAdd IP range.
    8. SetSubnet range torange2.
    9. SetAlias IP range to/24.
    10. ClickDone.

  7. ClickCreate.

gcloud

  1. Create the first network:

    gcloud compute networks create my-network1 --subnet-mode CUSTOM

  2. Add a subnet:

    gcloud compute networks subnets create my-subnet1 \    --network my-network1 \    --range 172.16.1.0/24 \    --secondary-range range1=10.1.0.0/16

  3. Create a second network:

    gcloud compute networks create my-network2 --subnet-mode CUSTOM

  4. Add a subnet:

    gcloud compute networks subnets create my-subnet2 \    --network my-network2 \    --range 172.16.2.0/24 \    --secondary-range range2=10.2.0.0/16

  5. Create a VM with interfaces in both networks. The first networkinterface listed, the one inmy-subnet1, is the primary interface:

    gcloud compute instances create multi-nic-alias-vm \    --machine-type f1-micro \    --network-interface "subnet=my-subnet1,aliases=/32;range1:/24" \    --network-interface "subnet=my-subnet2,aliases=/32;range2:/24"

  6. Use the display command to see the interfaces and their addresses:

    gcloud compute instances describe multi-nic-alias-vm
    ...networkInterfaces:- ...  aliasIpRanges:  - ipCidrRange: 172.16.1.2/32  - ipCidrRange: 10.1.0.0/24    subnetworkRangeName: range1  name: nic0  network: .../networks/my-network1  networkIP: 172.16.1.3  subnetwork: .../subnetworks/my-subnet1  ...- ...  aliasIpRanges:  - ipCidrRange: 172.16.2.2/32  - ipCidrRange: 10.2.0.0/24    subnetworkRangeName: range2  name: nic1  network: .../networks/my-network2  networkIP: 172.16.2.3  subnetwork: .../subnetworks/my-subnet2

API

  1. Create two custom mode VPC networks namedmy-network1andmy-network2. For more information, seeCreate a custom mode VPCnetwork with only IPv4 subnets.

  2. Add subnets to the VPC networks. For more information,seeAdd an IPv4-only subnet.

    1. Add a subnet namedmy-subnet1 tomy-network1. Specify172.16.1.0/24 for the primary range and10.1.0.0/16 for thesecondary range with the namerange1.

    2. Add a subnet namedmy-subnet2 tomy-network2. Specify172.16.2.0/24 for the primary range and10.2.0.0/16 for thesecondary range with the namerange2.

  3. Create a VM instance with interfaces in both networks.

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances{  "networkInterfaces": [    {      "subnetwork": "projects/PROJECT_ID/regions/REGION/subnetworks/my-subnet1",      "aliasIpRanges": [        {          "ipCidrRange": "/32",        },        {          "subnetworkRangeName": "range1",          "ipCidrRange": "/24"        }      ]    },    {      "subnetwork": "projects/PROJECT_ID/regions/REGION/subnetworks/my-subnet2",      "aliasIpRanges": [        {          "ipCidrRange": "/32",        },        {          "subnetworkRangeName": "range2",          "ipCidrRange": "/24"        }      ]    }  ],  ...}

    Replace the following:

    • PROJECT_ID: the ID of the project where youcreate the instance.
    • ZONE: the Google Cloud zone where theinstance is to be created.
    • REGION: the Google Cloud region wherethe subnet is located. The subnets must be in the same region as the instance.

    For more information, see theinstances.insert method.

Add alias IP ranges to an existing instance

You can add an alias IP range to a running instance.

The new addresses might not be available immediately, even after the API callhas finished. New addresses are available only after the guest OS has added theaddresses and routes.

Console

  1. In the Google Cloud console, go to theVM instances page.

    Go to VM instances

  2. Click the name of an existing instance.

  3. ClickEdit.

  4. InNetwork interfaces, click the network interface to which to addan alias IP range (nic0 for this example).

  5. ClickAlias IP ranges.

  6. ClickAdd IP range.

  7. Select aSubnet range.

  8. Enter an alias IP range.

  9. ClickDone.

  10. ClickSave.

gcloud

gcloud compute instances network-interfaces updateINSTANCE_NAME \    --zoneZONE \    [--network-interfaceNETWORK_INTERFACE; default="nic0"] \    --aliases "RANGE_NAME_1:RANGE_CIDR_1; \RANGE_NAME_2:RANGE_CIDR_2;..."

Replace the following:

  • INSTANCE_NAME: the name of the instance tomodify.
  • ZONE: the zone that contains the instance.
  • NETWORK_INTERFACE: the name of the networkinterface to which to add an alias IP address range.
  • RANGE_NAME_1 andRANGE_NAME_2:the names of the subnet secondary ranges from which to draw the aliasIP range. If you are assigning ranges from the subnet's primary range,omit this value.
  • RANGE_CIDR_1 andRANGE_CIDR_2: the IP ranges to assign to theinterface. The ranges can be a specific range (192.168.100.0/24), asingle IP address (192.168.100.1), or a netmask in CIDR format(/24). If the IP range is specified by netmask only, the IP allocatorchooses an available range with the specified netmask and allocates itto the network interface.

For the complete syntax, see thegcloud documentation.

API

Add alias IP ranges to an existing instance.

PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME/updateNetworkInterface?networkInterface=NETWORK_INTERFACE_NAME{  "aliasIpRanges": [    {      "ipCidrRange": "SECONDARY_IP_RANGE",      "subnetworkRangeName": "SECONDARY_RANGE_NAME"    },    existing ranges...  ],  "fingerprint": "INTERFACE_FINGERPRINT"}

Replace the following:

  • PROJECT_ID: the ID of the project that containsthe instance to modify.
  • ZONE: the Google Cloud zonein which to create the instance.
  • INSTANCE_NAME: the name of the instance tomodify.
  • NETWORK_INTERFACE_NAME: the name of theinstance's network interface to modify.
  • SECONDARY_IP_RANGE: the IP range to assign tothe interface. The range can be a specific range (192.168.100.0/24), asingle IP address (192.168.100.1), or a netmask in CIDR format (/24).If you specify the IP range by netmask only, the IP address allocatorchooses an available range with the specified netmask and assigns it tothe network interface.
  • SECONDARY_RANGE_NAME: the name of the subnetsecondary range from which to draw the alias IP range. If you areassigning ranges from the subnet's primary range, omit this field.
  • INTERFACE_FINGERPRINT: the fingerprint ID forthe existing network interface, which is provided when you describe aninstance.

For more information, see theinstances.updateNetworkInterface method.

Modify alias IP ranges for an existing instance

You can add more alias IP ranges to an existing instance or remove one or moreranges.

The address changes might not be visible immediately. The API call must finishand the guest OS must modify the addresses and routes.

Console

  1. In the Google Cloud console, go to theVM instances page.

    Go to VM instances

  2. Click the name of an existing instance.

  3. ClickEdit.

  4. InNetwork interfaces, click the network interface to which to addan alias IP range (nic0 for this example).

  5. ClickAlias IP ranges.

  6. To add an alias IP range, clickAdd Alias IP range.

  7. To remove an alias IP range, click theX next to the alias IPrange.

  8. ClickDone.

  9. ClickSave.

gcloud

gcloud compute instances network-interfaces updateINSTANCE_NAME \    --zoneZONE \    [--network-interfaceNETWORK_INTERFACE; default="nic0"] \    --aliases "RANGES_TO_RETAIN;NEW_RANGE_NAME:NEW_RANGE_CIDR;..."

Replace the following:

  • INSTANCE_NAME: the name of the instance tomodify.
  • ZONE: the zone that contains the instance.
  • NETWORK_INTERFACE: the name of the networkinterface to modify.
  • RANGES_TO_RETAIN: the existing ranges, inCURRENT_RANGE_NAME:CURRENT_RANGE_CIDR format, that you want tokeep. If you are adding ranges to an instance that doesn'thave any, these values are blank. If you are removing all ranges fromthe instance, the entire--aliases field is blank.
  • NEW_RANGE_NAME: the name of the subnet secondaryrange from which to draw any new alias IP ranges. If you are assigningranges from the subnet's primary range, omit this value.
  • NEW_RANGE_CIDR: the IP address range to assignto the interface. This range can be a specific range(192.168.100.0/24), a single IP address (192.168.100.1), or anetmask in CIDR format (/24). If the IP address range is specified bynetmask only, the IP allocator chooses an available rangewith the specified netmask and allocates it to the network interface.

To add ranges, run the command and specify all the existing and all the newalias IP ranges. Pairs are separated by semicolons—for example:--aliases"CURRENT_RANGE_NAME:CURRENT_RANGE_CIDR;NEW_RANGE_NAME:NEW_RANGE_CIDR".

To remove ranges, run the command and specify only the alias IP ranges thatyou want to keep. If you are keeping ranges from a secondary range, you mustspecify the name of the secondary range. A CIDR range can be a specificrange (192.168.100.0/24) or a single IP address(192.168.100.1)—for example:--aliases "RANGE_NAME:RANGE_CIDR;RANGE_CIDR".

To remove all ranges, run the command and specify the--aliases flag, butuse quotes to provide a blank input—for example:--aliases "".

You cannot add and remove ranges in the samegcloud command. Toremove some ranges and add others with the gcloud CLI,first run the command to remove unneeded ranges, and then run it again toadd needed ranges.

For the complete syntax, see thegcloud documentation.

API

For a network interface of an existing instance, add or remove alias IPaddress ranges.

PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME/updateNetworkInterface?networkInterface=NETWORK_INTERFACE_NAME{  "aliasIpRanges": [    include new and existing ranges to add them...    exclude existing ranges to remove them...  ],  "fingerprint": "INTERFACE_FINGERPRINT"}

Replace the following:

  • PROJECT_ID: the ID of the project that containsthe instance to modify.
  • ZONE: the zone that contains the instance.
  • INSTANCE_NAME: the name of the instance tomodify.
  • NETWORK_INTERFACE_NAME: the name of theinstance's network interface to modify.
  • INTERFACE_FINGERPRINT: the fingerprint ID forthe existing network interface, which is provided when you describe aninstance.

For more information, see theinstances.updateNetworkInterface method.

Troubleshooting

This section lists various issues that you might encounter when configuringalias IP ranges.

Cannot create VM instance with alias IP

  1. Verify that the network is a VPC network. Alias IPs aren'tsupported on legacy networks.

    gcloud compute networks list --filter="name=NETWORK_NAME"

    The networkMODE must beauto orcustom.

  2. If a subnet range name is specified, verify the following:

    gcloud compute networks subnets describeSUBNET_NAME --region=REGION
    • The subnet has a secondary range with the corresponding name.
    • The requested alias IP range is inside this secondary range or,if using netmask, is smaller than the primary range.

  3. If subnet range name isn't specified, verify that the requested alias IPrange is inside the primary subnet range or, if using netmask, is smallerthan the primary range.

Cannot connect to alias IP

  1. Verify firewall rules.

    1. List all firewall-rules:

      gcloud compute firewall-rules list --format=json

    2. Verify that traffic to and from an alias IP range is allowed.

      Note: Source service account and source tags only expand toprimary network IP addresses of matching instances.

    3. If necessary, add firewall rules to allow pinging an alias IP range:

      gcloud compute firewall-rules createFIREWALL_NAME1 \    --networkNETWORK_NAME \    --priority 0 \    --source-rangesALIAS_IP \    --allow icmp
      gcloud compute firewall-rules createFIREWALL_NAME2 \    --networkNETWORK_NAME \    --priority 0 \    --direction out \    --destination-rangesALIAS_IP \    --allow icmp

  2. Ensure that the VM recognizes the IP alias ranges as being local. On Linuxdistributions such as Debian, this can typically be done as follows.

    1. Connect to the instanceand run this command:

      ip route show table local

      The output is similar to the following:

      localALIAS_IP_RANGE dev eth0  proto 66  scope host

    2. In/etc/default/instance_configs.cfg, ensure that theip_aliasessetting is set totrue. If you need to change this, you must also restart the guest agent:

      systemctl restart google-guest-agent

    3. If the local route is not present, configure it using this command:

      ip route add to localALIAS_IP_RANGE dev eth0 proto 66

Auto-starting service doesn't bind to alias IP address

On supported Linux distributions, alias IP addresses are automatically set aslocal addresses by the preinstalled guest agent. This means that noOS-level configuration is needed.

However, this also means that the OS doesn't recognize the alias IP addresses aslocal addresses before the guest agent is running. If you have auto-startingservices on your VM and they start before the guest agent, they can'tbind to the alias IP addresses.

For example, an Apache HTTP server might exit with the following error:

could not bind to addressALIAS_IP:80

To solve this issue, configure your service to start after the guestagent. On distributions that usesystemctl, use the following steps.

  1. As a privileged user, run the following command to add a drop-in snippet forthe service that is not working correctly—for example, an Apache HTTPServer on Debian would beapache2:

    systemctl editYOUR_SERVICE

  2. In the text editor, add the following lines. Make sure that you add the linesabove the line readingLines below this comment will be discarded.

    [Unit]After=google-guest-agent.service

My secondary IP range isn't listed

Secondary IP ranges aren't listed as regular subnets. Toverify that the subnet secondary IP range is created, use thegcloud compute networks subnets describe command.

  1. Create a subnet.

    gcloud compute networks subnets create my-subnet \    --region us-central1 \    --network my-network \    --range 10.9.0.0/16 \    --secondary-range secondaryrange1=172.16.0.0/12

    The output is similar to the following:

    Created [https://www.googleapis.com/compute/v1/projects/google.com:my-project/regions/us-central1/subnetworks/my-subnet].NAME       REGION       NETWORK     RANGEmy-subnet  us-central1  my-network  10.9.0.0/16

  2. List your subnets.

    gcloud compute networks subnets list

    The output is similar to the following:

    NAME       REGION       NETWORK     RANGEmy-subnet  us-central1  my-network  10.9.0.0/16

  3. Get details on a subnet to see the secondary ranges.

    gcloud compute networks subnets describe my-subnet --region us-central1

    The output is similar to the following:

    ...ipCidrRange: 10.9.0.0/16...secondaryIpRanges:- ipCidrRange: 172.16.0.0/12  rangeName: secondaryrange1...

The specified subnet secondary range doesn't exist

When creating a VM, if you get an error saying that the secondary rangedoesn't exist, ensure the following:

  • The subnet has a secondary range with the specified name.
  • You are creating your VM within the subnet that has thesecondary range.

You can see this error by running the following commands:

  1. Create a subnet with a secondary range.

    gcloud compute networks subnets create my-subnet \    --region us-central1 \    --network my-network \    --range 10.9.0.0/16 \    --secondary-range secondaryrange1=172.16.0.0/12

    The output is similar to the following:

    Created [https://www.googleapis.com/compute/v1/projects/google.com:my-project/regions/us-central1/subnetworks/my-subnet].NAME       REGION       NETWORK     RANGEmy-subnet  us-central1  my-network  10.9.0.0/16

  2. Create an instance in another network, such as the default network, ratherthan in the newly created subnet.

    gcloud compute instances create instance-1 \    --zone us-central1-a \    --network default

    The output is similar to the following:

    Created [https://www.googleapis.com/compute/v1/projects/google.com:my-project/zones/us-central1-a/instances/instance-1].NAME        ZONE           MACHINE_TYPE   PREEMPTIBLE  INTERNAL_IP  EXTERNAL_IP    STATUSinstance-1  us-central1-a  n1-standard-1               10.128.0.2     47.82.96.9  RUNNING

  3. Try to assign an alias IP range from the subnet created in step 1. Thecommand fails because the secondary range is in a different subnetfrom the instance.

    gcloud compute instances network-interfaces update instance-1 \    --zone us-central1-a \    --aliases secondaryrange1:172.16.0.10/32

    The output is similar to the following:

    ERROR: (gcloud.compute.instances.network-interfaces.update) HTTPError 400: Invalid value for field 'resource.aliasIpRanges[0].subnetworkRangeName': 'secondaryrange'. The specified subnetwork secondary range does not exist.

  4. Create another instance, this one with its interface in the subnet createdin step 1.

    gcloud compute instances create instance-2 \    --zone us-central1-a \    --network-interface subnet=my-subnet

    The output is similar to the following:

    Created [https://www.googleapis.com/compute/v1/projects/google.com:my-project/zones/us-central1-a/instances/instance-2].NAME        ZONE           MACHINE_TYPE   PREEMPTIBLE  INTERNAL_IP  EXTERNAL_IP    STATUSinstance-2  us-central1-a  n1-standard-1               10.9.0.2     38.74.204.89  RUNNING

  5. Add an alias IP range to the interface. This time, the command succeedsbecause the interface and the secondary range are in the same subnet.

    gcloud compute instances network-interfaces update instance-2 \    --zone us-central1-a \    --aliases secondaryrange1:172.16.0.10/32

    The output is similar to the following:

    Updating network interface [nic0] of instance [instance-2]...done.

Can't add and remove secondary IP ranges in the same request

Adding and removing subnetwork secondary IP ranges in the same command isn'tsupported. The gcloud CLI commands to add and remove secondaryranges preserve the existing ranges that aren't modified.

To add and remove ranges, run the two commands separately.

gcloud compute networks subnets updateSUBNET_NAME \    --add-secondary-rangesRANGE_NAME_1=RANGE_CIDR_1,RANGE_NAME_2=RANGE_CIDR_2,...
gcloud compute networks subnets updateSUBNET_NAME \    --remove-secondary-rangesRANGE_NAME_1,RANGE_NAME_2,...

For more information about this command, usegcloud compute networks subnets update --help.

Can't simultaneously add and remove alias IP ranges

Adding and removing VM alias IP ranges in the same request isn't supported.The existing range must be explicitly removed before you can add the new range.

The gcloud CLI command to update alias IP ranges doesnotpreserve the existing ranges, so omitting a range is treated as a request to delete that range.

For example, if the current VM has an alias range10.9.27.0/24 and the newrequested range is/24, the command to request the/24 isrejected because it is interpreted as removing10.9.27.0/24 and adding/24.

Example:

  1. Create alias IP range.

    gcloud compute instances create vm --network-interface "subnet=s1,aliases=10.9.27.0/24"

  2. Try to add/24 without specifying the existing range. An error results.

    gcloud compute instances network-interfaces update vm --aliases "/24"ERROR: (gcloud.compute.instances.network-interfaces.update) HTTPError 400: Invalid value for field 'resource.aliasIpRanges': ''. Cannot simultaneously add and remove alias IP ranges.

  3. Update the VM to have no alias IP range.

    gcloud compute instances network-interfaces update vm --aliases ""Updating network interface [nic0] of instance [vm]...done.

  4. Add the new alias IP range.

    gcloud compute instances network-interfaces update vm --aliases "/24"Updating network interface [nic0] of instance [vm]...done.

For more information about this command, usegcloud compute instances network-interfaces update --help.

Firewall rule source tags and source service accounts

Firewall source service account and source tags only expand to primary networkIPs of matching instances and don't apply to alias IPs of matching instances.So, a firewall rule based on source tags doesn't affect traffic from aninstance alias IP address. Alias IP addresses can be added to firewall rulesas source or destination ranges.

Issues with VMs with multiple interfaces and alias IP ranges

SeeTroubleshoot VMs with multiple network interfaces.

Enabling IP alias on Google Cloud images disablescbr0 bridge on self-managed Kubernetes clusters

On images provided by Google, theGoogle guestagent creates local routesfor alias IP address ranges. For self-managed Kubernetes clusters, you mustconfigure the Google guest agent so that it doesn't create local routes foralias IP ranges. This step isn't required for GKE clustersbecause GKE disables the creation of local routes for alias IPranges on its node images.

Symptoms:

  • Kubernetes Pods lose network access if the local route created by the Guestagent removes the alias IP range from thecbr0 interface.

  • A packet capture on the Linux bridge device (tcpdump -ni cbr arp) showsa lack of ARP responses from thecbr0 interface even though that interfaceis up.

  • Inspecting the local route table (ip route show table local) reveals thatthe alias IP address range is assigned to the primary network interface (forexample,eth0 orens4) instead of the container bridge interface(cbr0).

Fix:

  1. Run the appropriate command listed inInstalled packages for the guest environment todetermine whether the node VM is running theGoogle guestagent oran earlier Compute Enginepackage.

  2. If your node VM isn't running the Google guest agent,install the guestagentor use a more recent image supplied by Google.

  3. Configure the Google guest agent to skip creating local routes for alias IPranges and forwarding rules.

    1. Edit/etc/default/instance_configs.cfg, settingip_forwarding=false inthe[NetworkInterfaces] section. You can create the[NetworkInterfaces]section if it's not already present in theinstance_configs.cfg file.

    2. Do one of the following tasks:

      • Restart thenode VM.

      • Restart thegoogle-guest-agent.service service, and edit the localroute table.

        To restart thegoogle-guest-agent.service service, runsudo systemctlrestart google-guest-agent.service. Then edit the local route table toremove any entries for the alias IP address ranges—for example:

        sudo ip route del localALIAS_IP_RANGE devDEVICE_IDENTIFIER

        Replace the following:

        • ALIAS_IP_RANGE: the alias IP address range.
        • DEVICE_IDENTIFIER: the identifier of the networkinterface—for example,ens4 oreth0.

    For more information, seeConfiguration in the Google guestagent documentation.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.