Configuring Alias IP Ranges

This document contains instructions for configuring alias IP addresses and alias IP ranges using the Google Cloud Platform Console and gcloud command line tool. Please review the Alias IP overview page before executing these commands.

Limitations

  • Up to five secondary IP ranges are permitted per subnet.
  • Only one secondary range can be added to, or removed from, a subnet at a time.
  • Only one alias IP range can be assigned to an interface.
  • CIDR expansion is not supported for secondary ranges.
  • Alias IP ranges can be added or deleted, but they can't be updated.
  • Auto mode VPC networks cannot be deleted if secondary subnet ranges are present.
  • A VM instance virtual interface can have 1 alias IP range assigned to it.
  • Cloud DNS resolves a VM name to its primary IP. Additional names for alias IPs are not configured automatically, but may be added manually.
  • Firewall source tags are not supported for alias IP addresses. This means that when you configure source tags in firewall rules, the source tags match the VM primary IP address, but not the alias IP addresses. Use source ranges to allow or deny ingress traffic from alias IP addresses.
  • In a static route, the next-hop IP address must be the primary IP address of the VM. Alias IP addresses are not supported as next-hop IP addresses.
  • IPv6 addresses are not supported.
  • Alias IP ranges are only supported in VPC networks, not legacy networks. To determine your network type, list your networks. VPC networks have a mode of custom or auto. Legacy networks have a mode of legacy.

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 may 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 GCP from which subnet range to assign the alias IPs.

All ranges, both primary and secondary, must be unique across across all subnets in the VPC network and in any networks attached via VPC Network Peering, VPN, or 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. Once your subnet has the range you want to use, see the VM instance commands for instructions on assigning a range to a VM.

Creating a subnet with one or more secondary CIDR ranges

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

Using a secondary range for alias IP allocation makes it easier to create firewall rules that allow access to the services running on a VM, but not to the VM's primary IP address.

Using a secondary range for alias IP allocation allows you to separate the IP space for services hosted in the VM, making it easier to 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. Go to the VPC networks page in the Google Cloud Platform Console.
    Go to the VPC networks page
  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. (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. (Example: 10.9.0.0/24)
  10. To add additional secondary IP ranges, for each range click Add 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]=[RANGE_CIDR][,[RANGE_NAME]=[RANGE_CIDR]...]

where

  • [NETWORK_NAME] is the name of the network where you want to create the the subnet.
  • [REGION] the region where you are creating the subnet.
  • [RANGE_NAME]=[RANGE_CIDR] is the name of the secondary range from which to draw the alias IP range and the alias IP range itself. For example: range1=10.9.0.0/24.

See the gcloud documentation for complete syntax.

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

Using a secondary range for alias IP allocation makes it easier to create firewall rules that allow access to the services running on a VM, but not to the VM's primary IP address.

Console

Use the gcloud command.

gcloud

gcloud beta compute networks subnets update [SUBNET_NAME] \
    --region [REGION] \
    --add-secondary-ranges [RANGE_NAME]:[RANGE_CIDR],[[RANGE_NAME]:[RANGE_CIDR],...]

where

  • [SUBNET_NAME] is the name of the subnet you want to add the secondary ranges to.
  • [REGION] the region where you are creating the subnet.
  • [RANGE_NAME]=[RANGE_CIDR] is the name of the secondary range from which to draw the alias IP range and the alias IP range itself. For example: range1=10.9.0.0/24.

See the gcloud documentation for complete syntax.

Removing a secondary CIDR range from a subnet

Console

Use the gcloud command.

gcloud

gcloud beta compute networks subnets update [SUBNET_NAME] \
    --region [REGION] \
    --remove-secondary-ranges [RANGE_NAME],[[RANGE_NAME],...]

where

  • [SUBNET_NAME] is the name of the subnet that you want to remove the secondary ranges from.
  • [REGION] the region where you are creating the subnet.
  • [RANGE_NAME] is the name of the secondary range from which to draw the alias IP range and the alias IP range itself. For example: range1=10.9.0.0/24.

See the gcloud documentation for complete syntax.

VM instance commands

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.

Creating 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. Go to the VM instances page in the Google Cloud Platform Console.
    Go to the VM instances page
  2. Click Create instance.
  3. Enter a Name for the new instance.
  4. Specify a Zone.
  5. Click Management, disks, networking, SSH keys.
  6. Click the Networking tab.
  7. Click the edit (pencil icon) button next to the primary interface in the Network interfaces section.
  8. Click Show alias IP ranges.
  9. Leave Subnet range set to Primary.
  10. Enter an Alias IP range in CIDR notation. This range must be an unused subrange of the primary range.
  11. Click Create.

gcloud

gcloud compute instances create vm1 \
    --zone [ZONE] \
    --network-interface "subnet=[SUBNET_NAME],aliases=[RANGE_CIDR][;[RANGE_CIDR];...]"

where

  • [ZONE] the zone that will contain the instance.
  • [SUBNET_NAME] is the name of the subnet that you want to remove the secondary ranges from.
  • [RANGE_CIDR] is the IP range from the primary subnet to 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 net mask in CIDR format (/24). If the IP range is specified by netmask only, the IP allocator chooses an available range with the specified netmask and allocates it to the network interface. To specify more than one range, separate the ranges with semicolons (;).

See the gcloud documentation for complete syntax.

Creating 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. Keeping the alias IP ranges separate from the primary range of the subnet makes it easier 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. Go to the VM instances page in the Google Cloud Platform Console.
    Go to the VM instances page
  2. Click Create instance.
  3. Enter a Name for the new instance.
  4. Specify a Zone.
  5. Click Management, disks, networking, SSH keys.
  6. Click the Networking tab.
  7. Click the edit (pencil icon) button next to the primary interface in the Network interfaces section.
  8. Click Show alias IP ranges.
  9. Select the Subnetwork that has the secondary range.
  10. Under Subnet range, select the Secondary IP range you wish to use.
  11. Enter an Alias IP range in CIDR notation. This range must be an unused range of the secondary IP range.
  12. Click Create.

gcloud

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

where

  • [ZONE] is the zone that will contain the instance.
  • [SUBNET_NAME] is the name of the subnet that will contain the instance.
  • [RANGE_NAME] the name of the subnet secondary range from which to draw the alias IP range.
  • [RANGE_CIDR] is the IP range to 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 net mask in CIDR format (/24). If the IP range is specified by netmask only, the IP allocator chooses an available range with the specified netmask and allocates it to the network interface.

See the gcloud documentation for complete syntax.

Adding alias IP ranges to an existing instance

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

Console

Use the gcloud command.

gcloud

gcloud beta compute instances network-interfaces update [INSTANCE_NAME] \
    --ZONE [ZONE] \
    [--network-interface [NETWORK_INTERFACE]; default="nic0"]
    --alias "[RANGE_NAME]:[RANGE_CIDR];[[RANGE_NAME]:[RANGE_CIDR],...]"

  • [ZONE] the zone that contains the instance.
  • [RANGE_NAME] the name of the subnet secondary range from which to draw the alias IP range. If you are assigning ranges from the subnet's primary range, omit this value.
  • [RANGE_CIDR] is the IP range to 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 net mask in CIDR format (/24). If the IP range is specified by netmask only, the IP allocator chooses an available range with the specified netmask and allocates it to the network interface.

See the gcloud documentation for complete syntax.

Modifying alias IP ranges for an existing instance

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

  • To add ranges, run the command and specify all the existing and all the new alias IP ranges. Pairs are separated by semicolons. Example: --alias "[CURRENT_RANGE_NAME]:[CURRRENT_RANGE_CIDR];[NEW_RANGE_NAME]:[NEW_RANGE_CIDR]"

  • To remove ranges, run the command and specify only the alias IP ranges 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). Example: --alias "[RANGE_NAME]:[RANGE_CIDR];[RANGE_CIDR]"

  • To remove all ranges, run the command and specify the --alias flag, but use quotes to provide a blank input. Example: --alias ""

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

Console

Use the gcloud command.

gcloud

gcloud beta compute instances network-interfaces update [INSTANCE_NAME] \
    --ZONE [ZONE] \
    --alias "[RANGES_TO_RETAIN];[[NEW_RANGE_NAME]:[NEW_RANGE_CIDR];...]"

  • [ZONE] the zone that contains the instance.
  • [RANGES_TO_RETAIN] the existing ranges, in [CURRENT_RANGE_NAME]:[CURRRENT_RANGE_CIDR] format, that you want to retain. If you are adding ranges to an instance that doesn't have any, these values will be blank. If you are removing all ranges from the instance, the entire --alias field will be blank.
  • [NEW_RANGE_NAME] is the name of the subnet secondary range from which to draw any new alias IP ranges. If you are assigning ranges from the subnet's primary range, omit this value.
  • [NEW_RANGE_CIDR] is the IP range to 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 net mask in CIDR format (/24). If the IP range is specified by netmask only, the IP allocator chooses an available range with the specified netmask and allocates it to the network interface.

See the gcloud documentation for complete syntax.

Troubleshooting

Cannot create VM instance with alias IP

  1. Verify that the VM has only one network interface. Alias IPs are not supported on VMs with multiple network interfaces.
        gcloud compute instances describe [INSTANCE_NAME] --zone=[ZONE]
    Only a single network interface should be listed under the networkInterfaces field in the output.
  2. Verify that the network is a VPC network. Alias IPs are not supported on legacy networks.
        gcloud compute networks list --filter="name=[NETWORK_NAME]"
    The network MODE should be "auto" or "custom".
  3. If a subnet range name is specified, verify the following:

        gcloud beta 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.
  4. If subnet range name is not 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.

    a. List all firewall-rules:

        gcloud beta compute firewall-rules list --format=json
        

    b. Verify that traffic to and from alias IP is allowed.

    c. If necessary, add firewall rules to allow pinging alias IP:

        gcloud beta compute firewall-rules create [FIREWALL_NAME1] \
        --network [NETWORK_NAME] --priority 0 --source-ranges [ALIAS_IP] \
        --allow icmp
        
        gcloud beta 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.

    a. Connect to the instance and run this command:

      ip route show table local
      

    The output should contain the following:

      local [ALIAS_IP_RANGE] dev eth0  proto 66  scope host
      

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

      ip route add to local [ALIAS_IP_RANGE] dev eth0 proto 66
      

My secondary IP range is not listed

Secondary IP ranges are not listed as regular subnets. In order to show that the subnet secondary IP range has been created, use the gcloud 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
        
        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
        
        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
        
        ...
        ipCidrRange: 10.9.0.0/16
        ...
        secondaryIpRanges:
    • ipCidrRange: 172.16.0.0/12 rangeName: secondaryrange1 ...

The specified subnet secondary range does not exist

When creating a VM, if you get an error saying that the secondary range does not exist, ensure the following:

  • That the subnet has a secondary range with the specified name.
  • That you are creating your VM within the subnet that has the secondary 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
        
        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 the default network rather than in the newly created subnet.
        gcloud compute instances create instance-1 --zone us-central1-a
        
        Created [https://www.googleapis.com/compute/beta/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 will fail because the secondary range is in a different subnet than the instance.
        gcloud beta compute instances network-interfaces update instance-1 \
            --zone us-central1-a \
            --aliases secondaryrange1:172.16.0.10/32
        
        ERROR: (gcloud.beta.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 beta compute instances create instance-2 \
            --zone us-central1-a \
            --network-interface subnet=my-subnet
        
        Created [https://www.googleapis.com/compute/beta/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 beta compute instances network-interfaces update instance-2 \
            --zone us-central1-a \
            --aliases secondaryrange1:172.16.0.10/32
        
        Updating network interface [nic0] of instance [instance-2]...done.
        

Cannot add and remove secondary IP ranges in the same request.

Adding and removing subnetwork secondary IP ranges in the same command is not currently supported. The gcloud commands to add and remove secondary ranges will preserve the existing ranges that are not modified.

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

gcloud beta compute networks subnets update [SUBNET_NAME] \
    --add-secondary-ranges [RANGE_NAME]=[RANGE_CIDR],[[RANGE_NAME]=[RANGE_CIDR],...]
gcloud beta compute networks subnets update  [SUBNET_NAME] \
    --remove-secondary-ranges [RANGE_NAME],[[RANGE_NAME],...]

To see more details for this command, use gcloud beta compute networks subnets update --help.

Cannot create or add new alias IP ranges

The maximum number of alias IP ranges per network interface is 1. Trying to add an additional range results in an error.

gcloud beta compute instances create vm2 --zone us-west1-a --network-interface "subnet=vpc1,aliases=r1:172.16.0.32/27;secondaryRange1:172.16.1.1/32"
ERROR: (gcloud.beta.compute.instances.create) Could not fetch resource:
 - Invalid value for field 'resource.networkInterfaces[0].aliasIpRanges[0]': ''. 2 alias IP ranges were specified, but maximum is 1.

Cannot simultaneously add and remove alias IP ranges

Adding and removing VM alias IP ranges in the same request is currently not supported.

The gcloud 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 alias range 10.9.27.0/24 and the new requested range is /24, running the command to request the /24 will be rejected as it is interpreted as removing 10.9.27.0/24 and adding /24. The existing range must be explicitly removed before you can add the new range.

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 beta compute instances network-interfaces update vm --aliases "/24"
        ERROR: (gcloud.beta.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 beta compute instances network-interfaces update vm --aliases ""
        Updating network interface [nic0] of instance [vm]...done.
        
  4. Add the new alias IP range.
        gcloud beta compute instances network-interfaces update vm --aliases "/24"
        Updating network interface [nic0] of instance [vm]...done.
        

To see more details for this command, use gcloud beta 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 do not apply to alias IPs of matching instances. So, a firewall rule based on source tags will not affect traffic from an instance alias IP address. Alias IP addresses can be added to firewall rules as source or destination ranges.

What's next

Send feedback about...