Configure alias IP ranges (original) (raw)

Skip to main content

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

Limitations

Subnet

VM instance

VPC network

Subnet commands

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

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

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

This section shows you how to create a subnet with a secondary range, add a secondary range to an existing subnet, or remove a secondary range from a subnet. After your subnet has the range you want to use, see theWork with VM instances section for information about assigning 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 you do not, create one.

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

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

Console

  1. In the Google Cloud console, go to the VPC networks page.
    Go to VPC networks
  2. Click the name of an existing network.
  3. Click Add 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. Click Create 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. Click Add.

gcloud

gcloud compute networks subnets create s1
--network NETWORK_NAME
--region REGION
--range 10.65.61.0/24
--secondary-range RANGE_NAME_1=RANGE_CIDR_1,RANGE_NAME_2=RANGE_CIDR_2,...

Replace the following:

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:

For more information, see thesubnetworks.insert method.

Terraform

You can use the Terraform resourceto create a subnet with one or more secondary ranges.

The Terraform arguments have example values that you can change.

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 to add one or more secondary ranges.

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

Console

  1. In the Google Cloud console, go to the VPC networks page.
    Go to VPC networks
  2. Click the name of a subnet to modify to view its details page.
  3. Click Edit.
  4. In the Secondary IP ranges section, click Add IP range.
  5. Enter a name for Subnet range name.
  6. Enter a range for Secondary 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. Click Save.

gcloud

gcloud compute networks subnets update SUBNET_NAME
--region REGION
--add-secondary-ranges RANGE_NAME_1=RANGE_CIDR_1,RANGE_NAME_2=RANGE_CIDR_2,...

Replace the following:

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:

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 that are associated with a subnet, see Describe a subnet.

Console

  1. In the Google Cloud console, go to the VPC networks page.
    Go to VPC networks
  2. Click the name of a subnet to modify to view its details page.
  3. Click Edit.
  4. In the Secondary IP ranges section, click X next to the secondary range to remove.
  5. Click Save.

gcloud

gcloud compute networks subnets update SUBNET_NAME
--region REGION
--remove-secondary-ranges RANGE_NAME_1,RANGE_NAME_2,...

Replace the following:

For the complete syntax, see thegcloud documentation.

API

Exclude secondary ranges to remove them. The following example removes all secondary 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:

For more information, see thesubnetworks.patch method.

Work with VM instances

These commands show how to create an instance with an alias IP range, add one or more alias IP ranges to an existing VM instance, or remove one or more ranges 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 the primary 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 IP addresses to be in the same range.

Console

  1. In the Google Cloud console, go to the VM instances page.
    Go to VM instances
  2. Click Create instance.
  3. Enter a name for the new instance.
  4. Specify a zone.
  5. Click Networking.
  6. In the Network interfaces section, expand the default network interface.
  7. In Alias IP ranges, clickAdd IP range.
  8. Leave Subnet range 1 set to Primary.
  9. In Alias IP range, enter an IP range in CIDR notation. This range must be an unused subrange of the primary range.
  10. Click Create.

gcloud

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

Replace the following:

For the complete syntax, see thegcloud documentation.

API

Create an instance with an alias IP address from the primary IP address range 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:

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 a secondary range of the subnet. We recommend keeping the alias IP ranges separate from the primary range of the subnet to create firewall rules that allow access to the services running on a VM, but not to the VM's primary IP address.

Console

  1. In the Google Cloud console, go to the VM instances page.
    Go to VM instances
  2. Click Create instance.
  3. Enter a name for the new instance.
  4. Specify a zone.
  5. Click Networking.
  6. In the Network interfaces section, expand the default network interface.
  7. In Alias IP ranges, clickAdd IP range.
  8. In Subnet range, select the secondary IP range to use.
  9. For Alias IP range, enter an IP range in CIDR notation. This range must be an unused range of the secondary IP range.
  10. Click Create.

gcloud

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

Replace the following:

For the complete syntax , see thegcloud documentation.

API

Create an instance with an alias IP address from the secondary IP address range 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:

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 with interfaces in both networks. If you already have two VPC networks, 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 the VPC networks page.
    Go to VPC networks
  2. Click Create VPC network.
  3. For Name, enter my-network1.
  4. Set Subnet creation mode to Custom, then specify a subnet name of my-subnet1.
  5. Specify a region.
  6. Set IP address range to 172.16.1.0/24.
  7. Click Create secondary IP range.
  8. Set Subnet range name to range1.
  9. Set Secondary IP range to 10.1.0.0/16.
  10. Click Done.
  11. Click Create.

Create the second network and subnet:

  1. In the Google Cloud console, go to the VPC networks page.
    Go to VPC networks
  2. Click Create VPC network.
  3. For Name, enter my-network2.
  4. Set Subnet creation mode to Custom, then specify a subnet name of my-subnet2.
  5. For Region, specify the same region as you did for the first network and subnet.
  6. Set IP address range to 172.16.2.0/24.
  7. Click Create secondary IP range.
  8. Set Subnet range name torange2.
  9. Set Secondary IP range to 10.2.0.0/16.
  10. Click Done.
  11. Click Create.

Create a VM with interfaces in both networks:

  1. In the Google Cloud console, go to the VM instances page.
    Go to VM instances
  2. Click Create instance.
  3. Set the zone to the region where you created the subnets.
  4. Click Networking.
  5. Click the first network interface.
    1. Set Network to my-network1.
    2. Set Subnetwork to my-subnet1.
    3. Click Alias IP ranges.
    4. Click Add IP range.
    5. Set Subnet range to Primary.
    6. Set Alias IP range to /32.
    7. Click Add IP range.
    8. Set Subnet range to range1.
    9. Set Alias IP range to /24.
    10. Click Done.
  6. Click Add network interface.
    1. Select my-network2.
    2. Set Subnetwork to my-subnet2.
    3. Click Alias IP ranges.
    4. Click Add IP range.
    5. Set Subnet range to Primary.
    6. Set Alias IP range to /32.
    7. Click Add IP range.
    8. Set Subnet range to range2.
    9. Set Alias IP range to /24.
    10. Click Done.
  7. Click Create.

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 network interface listed, the one in my-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:

API

  1. Create two custom mode VPC networks named my-network1and my-network2. For more information, see Create a custom mode VPC network with only IPv4 subnets.
  2. Add subnets to the VPC networks. For more information, see Add an IPv4-only subnet.
    1. Add a subnet named my-subnet1 to my-network1. Specify172.16.1.0/24 for the primary range and 10.1.0.0/16 for the secondary range with the name range1.
    2. Add a subnet named my-subnet2 to my-network2. Specify172.16.2.0/24 for the primary range and 10.2.0.0/16 for the secondary range with the name range2.
  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 you create the instance.
    • ZONE: the Google Cloud zone where the instance is to be created.
    • REGION: the Google Cloud region where the 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 call has finished. New addresses are available only after the guest OS has added the addresses and routes.

Console

  1. In the Google Cloud console, go to the VM instances page.
    Go to VM instances
  2. Click the name of an existing instance.
  3. Click Edit.
  4. In Network interfaces, click the network interface to which to add an alias IP range (nic0 for this example).
  5. Click Alias IP ranges.
  6. Click Add IP range.
  7. Select a Subnet range.
  8. Enter an alias IP range.
  9. Click Done.
  10. Click Save.

gcloud

gcloud compute instances network-interfaces update INSTANCE_NAME
--zone ZONE
[--network-interface NETWORK_INTERFACE; default="nic0"]
--aliases "RANGE_NAME_1:RANGE_CIDR_1;
RANGE_NAME_2:RANGE_CIDR_2;..."

Replace the following:

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:

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 more ranges.

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

Console

  1. In the Google Cloud console, go to the VM instances page.
    Go to VM instances
  2. Click the name of an existing instance.
  3. Click Edit.
  4. In Network interfaces, click the network interface to which to add an alias IP range (nic0 for this example).
  5. Click Alias IP ranges.
  6. To add an alias IP range, click Add Alias IP range.
  7. To remove an alias IP range, click the X next to the alias IP range.
  8. Click Done.
  9. Click Save.

gcloud

gcloud compute instances network-interfaces update INSTANCE_NAME
--zone ZONE
[--network-interface NETWORK_INTERFACE; default="nic0"]
--aliases "RANGES_TO_RETAIN;NEW_RANGE_NAME:NEW_RANGE_CIDR;..."

Replace the following:

To add ranges, run the command and specify all the existing and all the new alias 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 that you want to keep. If you are keeping ranges from a secondary range, you must specify the name of the secondary range. A CIDR range can be a specific range (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, but use quotes to provide a blank input—for example:--aliases "".

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

For the complete syntax, see thegcloud documentation.

API

For a network interface of an existing instance, add or remove alias IP address 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:

For more information, see theinstances.updateNetworkInterface method.

Troubleshooting

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

Cannot create VM instance with alias IP

  1. Verify that the network is a VPC network. Alias IPs aren't supported on legacy networks.
    gcloud compute networks list --filter="name=NETWORK_NAME"
    The network MODE must be auto or custom.
  2. If a subnet range name is specified, verify the following:
    gcloud compute networks subnets describe SUBNET_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 IP range is inside the primary subnet range or, if using netmask, is smaller than 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.
    3. If necessary, add firewall rules to allow pinging an alias IP range:
      gcloud compute firewall-rules create FIREWALL_NAME1 \
      --network NETWORK_NAME \
      --priority 0 \
      --source-ranges ALIAS_IP \
      --allow icmp
      gcloud compute firewall-rules create FIREWALL_NAME2 \
      --network NETWORK_NAME \
      --priority 0 \
      --direction out \
      --destination-ranges ALIAS_IP \
      --allow icmp
  2. Ensure that the VM recognizes the IP alias ranges as being local. On Linux distributions 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:
      local ALIAS_IP_RANGE dev eth0 proto 66 scope host
    2. In /etc/default/instance_configs.cfg, ensure that the ip_aliasessetting is set to true. 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 local ALIAS_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 as local addresses by the preinstalled guest agent. This means that no OS-level configuration is needed.

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

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

could not bind to address ALIAS_IP:80

To solve this issue, configure your service to start after the guest agent. On distributions that use systemctl, use the following steps.

  1. As a privileged user, run the following command to add a drop-in snippet for the service that is not working correctly—for example, an Apache HTTP Server on Debian would be apache2:
    systemctl edit YOUR_SERVICE
  2. In the text editor, add the following lines. Make sure that you add the lines above the line reading Lines 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. To verify 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 RANGE
    my-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 RANGE
    my-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:

The specified subnet secondary range doesn't exist

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

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 RANGE
    my-subnet us-central1 my-network 10.9.0.0/16
  2. Create an instance in another network, such as the default network, rather than 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 STATUS
    instance-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. The command fails because the secondary range is in a different subnet from 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 created in 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 STATUS
    instance-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 succeeds because 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't supported. The gcloud CLI commands to add and remove secondary ranges preserve the existing ranges that aren't modified.

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

gcloud compute networks subnets update SUBNET_NAME
--add-secondary-ranges RANGE_NAME_1=RANGE_CIDR_1,RANGE_NAME_2=RANGE_CIDR_2,...

gcloud compute networks subnets update SUBNET_NAME
--remove-secondary-ranges RANGE_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 does _not_preserve 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 range 10.9.27.0/24 and the new requested range is /24, the command to request the /24 is rejected because it is interpreted as removing 10.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 network IPs 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 an instance alias IP address. Alias IP addresses can be added to firewall rules as source or destination ranges.

Issues with VMs with multiple interfaces and alias IP ranges

See Troubleshoot VMs with multiple network interfaces.

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

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

Symptoms:

Fix:

  1. Run the appropriate command listed in Installed packages for the guest environment to determine whether the node VM is running the Google guest agentor an earlier Compute Engine package.
  2. If your node VM isn't running the Google guest agent, install the guest agentor use a more recent image supplied by Google.
  3. Configure the Google guest agent to skip creating local routes for alias IP ranges and forwarding rules.
    1. Edit /etc/default/instance_configs.cfg, setting ip_forwarding=false in the [NetworkInterfaces] section. You can create the [NetworkInterfaces]section if it's not already present in the instance_configs.cfg file.
    2. Do one of the following tasks:
      • Restart the node VM.
      • Restart the google-guest-agent.service service, and edit the local route table.
        To restart the google-guest-agent.service service, run sudo systemctl restart google-guest-agent.service. Then edit the local route table to remove any entries for the alias IP address ranges—for example:
        sudo ip route del local ALIAS_IP_RANGE dev DEVICE_IDENTIFIER
        Replace the following:
        * ALIAS_IP_RANGE: the alias IP address range.
        * DEVICE_IDENTIFIER: the identifier of the network interface—for example, ens4 or eth0.

For more information, see Configuration in the Google guest agent documentation.

What's next

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

Last updated 2026-06-15 UTC.