Reserving a static internal IP address

If a virtual machine (VM) instance requires a fixed internal IP address that does not change, you can obtain a static internal IP address for that VM using one of the following options:

Reserve a new static internal IP address and then assign the address when creating the VM.
Promote an existing ephemeral internal IP address to become a static internal IP address.

To learn how to manage secondary internal IP addresses, read 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 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.

To reserve a static external IP address instead of an internal IP address, read Reserving a static external address.

Before you begin

If you want to use the command-line examples in this guide, do the following:
1. Install or update to the latest version of 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 about IP addresses.

Permissions

To reserve and manage static internal IP addresses, you need to be granted the compute.networkAdmin role, or one or more of the following permissions:

compute.addresses.create on the IP address
compute.addresses.createInternal on the IP address
compute.instances.update on the VM instance
compute.subnetworks.use on the subnetwork

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.
The number of static internal IP addresses that you can reserve cannot exceed your project's quota. For more information, see the per-project quotas in the VPC documentation.
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 internal IP addresses available to the project.
Reserving a static internal IP address is only supported for VPC networks. It is not supported for legacy mode networks.
Deleting a resource does not automatically release a static internal IP address. You must manually release static internal IP addresses when you no longer require them.

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.

In order to use a static internal IP address, you must have a VPC network in place for your project. Read Using VPC Networks to learn how to create your VPC network.

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:

Create a subnet from your VPC network.
Reserve an internal IP address from the subnet's primary IP range. This step creates an internal IP address resource containing that specific internal IP address. This step also prevents Google Cloud from automatically allocating that address as an ephemeral address.
Use the reserved internal IP address by associating it with a VM instance or an internal load balancer when you create the VM or load balancer resource.

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.

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

The two methods are outlined in the diagram below.

Internal IP reservation.

Reserve a new static internal IP address

Before you can reserve a new static internal IP address, you must create a VPC network with a subnet.

Console

You can reserve a standalone internal IP address using the Cloud Console.

In the Cloud Console, go to the VPC networks page.
Go to VPC networks
Click the VPC network that you want to reserve the new static IP in.
Click Static internal IP addresses and then click Reserve static address.
Enter a Name for this IP address.
Select a Subnet.
If you want to specify which IP address to reserve, under Static IP address, select Let me choose, then fill in a Custom IP address. Otherwise the system automatically assigns an IP address in the subnet for you.
If you want to share this IP in different frontends, under Purpose, choose Shared.
Click Reserve to finish the process.

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

Replace the following:

ADDRESS_NAME: the desired names of one or more addresses to create.
REGION: the region for this request.
SUBNETWORK: the subnet for this internal IP address.
IP_ADDRESS: the IP address to reserve, which must be within the subnet's primary 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

Call the addresses.insert method:

POST https://compute.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 for you, or specify the address for a specific IP address. The IP address must belong to the subnet's primary IP address range.

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

For example:

POST https://compute.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"
}

Terraform

You can use a Terraform module to create an internal IP address.

In the following example, the Terraform arguments have example values that you can change. The example creates two specific internal IP addresses:

examples/internal_with_specific_ip/main.tf

View on GitHub

module "address" {
  source     = "terraform-google-modules/address/google"
  version    = "3.0.0"
  project_id = var.project_id # Replace this with your project ID in quotes
  region     = "asia-east1"
  subnetwork = "my-subnet"
  names      = ["internal-address1", "internal-address2"]
  addresses  = ["10.0.0.3", "10.0.0.4"]
}

The following example creates two dynamically allocated internal IP addresses:

examples/internal_with_dynamic_ip/main.tf

View on GitHub

module "address" {
  source     = "terraform-google-modules/address/google"
  version    = "3.0.0"
  project_id = var.project_id # Replace this with your project ID in quotes
  region     = "asia-east1"
  subnetwork = "my-subnet"
  names      = ["internal-address1", "internal-address2"]
}

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

Console

To promote an ephemeral internal IP address to a static IP address in the console:

Go to the VM instances page.
Go to VM instances
Select your project.
Select the instance you want to change.
Click on the Edit tool at the top of the page.
Click on the edit tool for Network Interfaces.
Under Internal IP type, select Static.
Complete the information for a static IP address.
Click Done to save your changes.
Click Save to update your instance.

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

Replace the following:

ADDRESS_NAME: the desired names of the address. Declare the names in the same order that you declare the IP addresses. In this case ADDRESS_NAME_1 corresponds with IP_ADDRESS_1 and ADDRESS_NAME_2 corresponds with IP_ADDRESS_2.
IP_ADDRESS_1,[IP_ADDRESS_2,...]: the IP addresses to promote. For example, 10.128.1.9.
REGION: the region to reserve this address.
SUBNETWORK: 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

Call the addresses.insert method:

POST https://compute.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/SUBNETWORK"
}

For example:

POST https://compute.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"
}

Create a VM instance with a specific internal IP address

You can choose a specific internal IP address to assign to an instance when you create the instance. The IP address must be a valid IP address of the subnet of the instance, and the IP address must not already be in use. The IP address remains attached to the instance until you delete the instance, which releases the IP address back into the pool. If you stop and restart the instance, the instance retains the same internal IP address.

If you do not specify an IP address, Compute Engine automatically allocates one from the subnet or network. You can specify an internal IP address using the Google Cloud Console, the gcloud tool, or the Compute Engine API.

Console

In the Cloud Console, go to the VM instances page.
Go to VM instances
Click Create instance.
On the Create a new instance page, fill in the properties for your instance.
Expand the Management, security, disks, networking, sole tenancy section.
Click Networking.
Under Network interfaces, click on the default network interface to edit it.
Optionally, under Network and Subnetwork, select the network and subnetwork that you want to use.
Under Primary internal IP, select an internal IP address option from the drop-down list.
Click Done to finish modifying the network interface.
Click Create to create the instance.

gcloud

Specify a valid IP address when creating the instance:

gcloud compute instances create VM_NAME
     --private-network-ip IP_ADDRESS

Replace the following:

VM_NAME: the name of the VM you want to create
IP_ADDRESS: the IP address you want to assign

If you are using a custom subnet mode network, you must also specify the subnet using the --subnet SUBNET parameter.

API

To create a VM instance with a static internal IP address, call the instances.insert method and explicitly provide the networkInterfaces[].networkIP property with the internal IP address you want to assign for the VM.

For example:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances

{
  "name": "VM_NAME",
  "machineType": "zones/us-central1-f/machineTypes/e2-micro",
  "networkInterfaces": [{
    "accessConfigs": [{
      "type": "ONE_TO_ONE_NAT",
      "name": "External NAT",
     }],
    "network": "global/networks/default",
    "networkIP": "IP_ADDRESS"
  }],
  "disks": [{
     "autoDelete": "true",
     "boot": "true",
     "type": "PERSISTENT",
     "initializeParams": {
        "sourceImage": "projects/debian-cloud/global/images/v20150818"
     }
   }]
 }

Replace the following:

PROJECT_ID: ID of the project to create the VM in
ZONE: zone to create the VM in
VM_NAME: the name of the virtual machine
IP_ADDRESS: the IP address to assign to the VM

If you delete an instance with a specified IP address, the address goes back into the unallocated address pool. If you need an internal IP address to persist beyond the life of the instance, you can reserve a static internal IP address.

Create 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 at:

Use 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:

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. Because 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
```

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

Use a static internal IP with Shared VPC

You can create a reserved static internal IP in a shared subnet of a Shared VPC network. The IP address object itself is created in the same service project as the resource that will use it, even though its value comes from the range of available IPs in the selected shared subnet of the Shared VPC network. Refer to these pages for more information about this use case:

The IP addresses section of the Shared VPC Overview page
Reserving a static internal IP on the Provisioning Shared VPC page

List static internal IP addresses

In Cloud Console, you can view your static internal IP addresses of a selected VPC. To view all your existing static IP address, including external IP address and internal IP address, run addresses list or make a GET request to the API.

Console

In the Cloud Console, go to the VPC networks page.
Go to VPC networks
Click the VPC network that you want to check.
Click STATIC INTERNAL IP ADDRESSES to view all reserved static internal IP addresses in this VPC.

gcloud

Use the compute addresses list command to list all static IP address, including external IP address and internal IP address.

gcloud compute addresses list

API

Call the addresses.list method:

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/addresses

Replace the following:

REGION: the name of the region for this request
PROJECT_ID: the project ID for this request

To list all addresses in all regions, call the aggregatedList method.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/aggregated/addresses

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

Console

In the Cloud Console, go to the VPC networks page.
Go to VPC networks
Identify the VPC network that contains the IP you want to release, click on its name.
Click STATIC INTERNAL IP ADDRESSES.
Select the IP address(es) you want to release.
Click RELEASE, and confirm this operation by click RELEASE on the pop up message.

gcloud

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

gcloud compute addresses delete ADDRESS_NAME \
    --region REGION

Replace the following:

ADDRESS_NAME: The name of the address to delete.
REGION: The region the address belongs to.

For example:

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

API

Call the addresses.delete method:

DELETE https://compute.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://compute.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 TCP/UDP load balancing.
Learn more about Internal HTTP(S) load balancing.