Reserving a Static Internal IP Address

This page explains how to configure and manage static primary internal IP addresses for your resources, including:

• Reserving and assigning a static internal IP address
• Promoting an ephemeral internal IP address to a static internal IP address

To learn how to manage secondary internal IP addresses, read about Alias IP Ranges.

In Compute Engine, each VM instance can have multiple network interfaces. Each interface can have one external IP address, one primary internal IP address, and one or more secondary internal IP addresses. Forwarding rules can have external IP addresses for external load balancing or internal addresses for internal load balancing. To learn about IP addresses, read the IP Addresses documentation.

Static internal IPs provide the ability to reserve internal IP addresses from the private RFC1918 IP range configured in the subnet, then assign those reserved internal addresses to resources as needed. Reserving an internal IP address takes that address out of the dynamic allocation pool and prevents it from being used for automatic allocations. Reserving static internal IP addresses requires specific IAM permissions so that only authorized users can reserve a static internal IP address.

With the ability to reserve static internal IP addresses, you can always use the same IP address for the same resource even if you have to delete and recreate the resource.

This document does not explain how to reserve and manage external IP addresses. To reserve a static external IP address, read Reserving a Static External Address.

Before you begin

• If you want to use the command-line examples in this guide:
  1. Install the gcloud command-line tool.
  2. Set a default region and zone.
• If you want to use the API examples in this guide, set up API access.
• Read the IP Addresses.

Permissions

To reserve and manage static internal IP addresses, you need to be granted the compute.networkAdmin role. To learn more about roles, read Compute Engine IAM Roles.

Restrictions

• You cannot change the internal IP address of an existing resource. For example, you cannot assign a new static internal IP address to a running VM instance. You can, however, promote the ephemeral internal IP address of a resource to a static internal IP so that the address remains reserved even after the resource is deleted.

• You can only reserve up to 200 static internal IP addresses per project by default.

• Only one resource at a time can use a static internal IP address.

• There is no way to tell whether an IP address is static or ephemeral after it has been assigned to a resource, except to compare the IP address against the list of static internal IP addresses reserved to that project. Use the addresses list sub-command to see a list of static external IP addresses available to the project.

• Reserving a static internal IP address is currently unavailable in the Google Cloud Platform Console.

• Reserving a static internal IP address is only supported for VPC networks. It is not supported for legacy mode networks.

How to reserve a static internal IP address

You can reserve a static internal IP address before creating the associated resource or you can create the resource with an ephemeral internal IP address and then promote that ephemeral IP address to a static internal IP address.

Reserve a specific address and then associate it with a specific resource

In this scenario, you separately reserve a static internal IP address and then assign it to a resource. In summary:

1. You reserve an internal IP address from the subnet IP range. This step creates an internal IP address resource containing that specific internal IP address.

2. Once reserved, use the reserved internal IP address by associating it with a VM instance or an internal load balancer at creation time.

Specify an ephemeral internal IP address for a resource and then promote the address

In this scenario, you promote an ephemeral internal IP address that is still attached to a resource to a static internal IP address.

1. Create a VM instance or an internal load balancer with either an automatically allocated ephemeral IP address or a specifically chosen IP address.
2. Promote the internal IP address to a static internal IP address.

The two methods are outlined in the diagram below.

Reserving a new static internal IP address

To reserve a new static internal IP address, either automatically allocated or an unused address from an existing subnet, you can use the gcloud compute addresses create command or the addresses.insert method in the Compute Engine API.

gcloud

Using the gcloud tool, run the compute addresses create command:

gcloud compute addresses create [ADDRESS_NAME] [[ADDRESS_NAME]..] \
    --region [REGION] --subnet [SUBNETWORK] \
    --addresses [IP_ADDRESS]

where:

• [ADDRESS_NAME] is desired names of one or more addresses to create.
• [REGION] is the region for this request.
• [SUBNETWORK] is the subnet for this internal IP address.
• [IP_ADDRESS] is the IP address to reserve, which must be within the subnet's IP range. If unspecified, one will be automatically allocated from the subnet.

For example, to reserve an automatically allocated internal IP address from a subnet:

gcloud compute addresses create example-address-1 \
    --region us-central1 --subnet subnet-1

To reserve a specific internal IP address from a subnet:

gcloud compute addresses create example-address-1 \
    --region us-central1 --subnet subnet-1 --addresses 10.128.0.12

You can create multiple addresses by passing in more than one address name. However, all the addresses will be reserved in the same subnet. For example:

gcloud compute addresses create example-address-1 example-address-2 \
    --region us-central1 --subnet subnet-1 \
    --addresses 10.128.0.12,10.128.0.13

API

In the API, make a POST request to the following URL:

POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/regions/[REGION]/addresses

The body of the request must include the addressType which should be INTERNAL, the name of the address, and the subnetwork the IP address belongs to. You can let the system automatically allocate an IP address in the subnet for you, or specify the address for a specific IP address:

{
    "addressType": "INTERNAL",
    "name": "[ADDRESS_NAME]",
    "subnetwork": "regions/[REGION]/subnetworks/[SUBNET]",
    "address": "[IP_ADDRESS]"
}

For example:

POST https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1/addresses

{
 "name": "example-address-1",
 "addressType": "INTERNAL",
 "subnetwork": "regions/us-central1/subnetworks/my-custom-subnet",
 "address": "10.128.0.12"
}

Promoting an in-use ephemeral internal IP address to a static address

If you have ephemeral IP addresses that are currently in use, you can promote these addresses to static internal IP addresses so the addresses remain with your project until you actively remove them.

Before you reserve an existing IP address, you will need the value of the IP address you want to promote. Make a describe request to the resource to get the IP address. For example, if promoting an IP address currently in use by a VM instance, use:

gcloud compute instances describe [INSTANCE_NAME] --zone [ZONE] | grep "networkIP"

The gcloud tool returns the networkIP value, which is the internal IP being used by the resource. For example:

networkIP: 10.240.0.2

Next, promote the address.

gcloud

To promote one or more existing IP address, use the compute addresses create command and provide the --addresses flag with the explicit internal IPs to promote:

gcloud compute addresses create [ADDRESS_NAME_1] [[ADDRESS_NAME_2]..] \
    --addresses [IP_ADDRESS_1],[[IP_ADDRESS_2],..] \
    --region [REGION] \
    --subnet [SUBNETWORK]

where:

• [ADDRESS_NAME] are the desired names of the address. Declare the names in the same order you will declare the IP addresses. In this case [ADDRESS_NAME_1] would correspond with [IP_ADDRESS_1] and [ADDRESS_NAME_2] would correspond with [IP_ADDRESS_2].
• [IP_ADDRESS],[[IP_ADDRESS_2],...] are the IP addresses to promote. For example, 10.128.1.9.
• [REGION] is the region to reserve this address.
• [SUBNETWORK] is the subnetwork for this request.

For example:

gcloud compute addresses create example-address-1 example-address-2 \
    --addresses 10.128.4.90,10.128.0.232 \
    --region us-central1 \
    --subnet subnet-1

API

In the API, make a POST request to the following URL:

POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/regions/[REGION]/addresses

The body of the request must include the addressType which should be INTERNAL, the name of the address, the address to promote, and the subnetwork the IP address belongs to:

{
    "addressType": "INTERNAL",
    "address": "[IP_ADDRESS]",
    "name": "[ADDRESS_NAME]",
    "subnetwork": "regions/[REGION]/subnetworks/[SUBNET]"
}

For example:

POST https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1/addresses

{
 "name": "example-address-1",
 "addressType": "INTERNAL",
 "address": "10.128.0.2",
 "subnetwork": "regions/us-central1/subnetworks/my-custom-subnet"
}

Creating a VM instance with a static internal IP address

You can assign a reserved static internal IP address when you create a new VM.

1. First, reserve a static internal IP address. For example, the following example reserves an address called my-vm-ip-address in the us-central1 region. Since the command omits the --addresses flag, Compute Engine reserves a random IP address:

   gcloud compute addresses create my-vm-ip-address \
       --region us-central1 --subnet my-subnet
   

2. Next, use that address when you create your instance. For example:

   gcloud compute instances create my-instance \
       --image-family [IMAGE_FAMILY] \
       --image-project [IMAGE_PROJECT] \
       --private-network-ip my-vm-ip-address \
       --subnet my-subnet
   

Creating an internal load balancer with a static internal IP address

To create an internal load balancer that uses a static internal IP address, follow the instructions for Setting Up Internal Load Balancing but when configuring the load balancer, provide a reserved IP address instead.

1. First, reserve a new static internal IP address. For example, the following example reserves an address called my-ilb-ip-address in the us-central1 region. Since the command omits the --addresses flag, Compute Engine reserves a random IP address:

   gcloud compute addresses create my-ilb-ip-address \
       --region us-central1 --subnet my-subnet
   

2. Next, when creating a forwarding rule, include the --address flag. For example:

   gcloud compute forwarding-rules create my-int-lb-forwarding-rule \
       --address my-ilb-ip-address \
       --load-balancing-scheme internal \
       --backend-service my-int-lb \
       --ports 80 \
       --region us-central1 \
       --subnet my-subnet
   

Using a static internal IP address for a secondary network interface

When you create a VM instance with multiple network interfaces, you can use a reserved static internal IP address for both primary and secondary network interfaces.

To assign a static internal IP address to a secondary network interface, do the following:

1. First, reserve a static internal IP address. For example, the following example reserves an address called my-second-ip-address in the us-central1 region. Since the command omits the --addresses flag, Compute Engine reserves a random IP address:

   gcloud compute addresses create my-second-ip-address \
       --region us-central1 --subnet subnet-b
   

2. Use the address as the IP address for the secondary interface when you create a VM instance. For example:

   gcloud compute instances create my-instance \
       --image-family [IMAGE_FAMILY] \
       --image-project [IMAGE_PROJECT] \
       --network-interface subnet=subnet-a,no-address \
       --network-interface \
         subnet=subnet-b,private-network-ip=my-second-ip-address,no-address
   

Using a static internal IP with a shared VPC network

Using a reserved internal IP with a shared VPC network is the same as for any other VPC network. In order to use a reserved static IP address with a VM instance in a shared network, you must create both the IP address and the resource in the same project. For example, if you create a VM instance or internal load balancer in a shared VPC service project, you must also reserve the internal IP address in the same project.

Deleting a static internal IP address

You can delete a static internal IP address if you no longer need it. You can delete an address whether or not it is currently being used by another resource. If the address is being used by a resource, it remains attached to the resource until the resource is deleted, in which case, the address is returned to the pool of available addresses for other projects.

gcloud

Using the gcloud tool, run the compute addresses delete command:

gcloud compute addresses delete [ADDRESS_NAME] \
    --region [REGION]

where:

• [ADDRESS_NAME] is the name of the address to delete.
• [REGION] is the region the address belongs to.

For example:

gcloud compute addresses delete example-address-to-delete \
    --region us-west1

API

In the API, make a DELETE request to the following URL:

DELETE https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/regions/[REGION]/addresses/[ADDRESS_NAME]

For example, to delete an address in the us-west1 region:

DELETE https://www.googleapis.com/compute/v1/projects/myproject/regions/us-west1/addresses/example-address-to-delete

What's next

• Learn more about IP Addresses.
• Learn how to reserve a static external IP address.
• Learn how to assign multiple internal IP addresses using alias IP addresses.
• Learn more about internal load balancing.