Reserve a static internal IP address

This page shows you how to reserve and manage static internal IPv4 or IPv6 addresses in Virtual Private Cloud (VPC) networks.

Static internal IP addresses provide the ability to reserve internal IP addresses from the IP address range configured in the subnet, and then assign those reserved internal IP 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 Identity and Access Management (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 re-create the resource.

To reserve a static external IP address instead of an internal IP address, see Reserve a static external IP addresses.

Before you begin

• Read about IP addresses.
• If you haven't already, set up authentication. Authentication is the process by which your identity is verified for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate as follows.

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  Install the Google Cloud CLI, then initialize it by running the following command:

  gcloud init

  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

  Terraform

  To use the Terraform samples on this page from a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. Create local authentication credentials for your Google Account:

     gcloud auth application-default login

  For more information, see Set up authentication for a local development environment in the Google Cloud authentication documentation.

  REST

  To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

  Install the Google Cloud CLI, then initialize it by running the following command:

  gcloud init

Required roles

To get the permissions that you need to reserve and manage static IP addresses, ask your administrator to grant you the Compute Network Admin (roles/compute.networkAdmin) IAM role on your project. For more information about granting roles, see Manage access.

This predefined role contains the permissions required to reserve and manage static IP addresses. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to reserve and manage static IP addresses:

• compute.addresses.create on the IP address
• compute.addresses.createInternal on the IP address
• compute.networks.list on the network
• compute.subnetworks.use on the subnet
• compute.subnetworks.list on the subnet

You might also be able to get these permissions with custom roles or other predefined roles.

Limitations

• You cannot unassign or change the internal IPv4 address of an existing resource. For example, you cannot assign a new static internal IP address to a running or a stopped VM instance. You can, however, promote the ephemeral internal IP address of a resource to a static internal IP address 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.

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

• You cannot change the name of a static IP address.

• Static internal IP addresses are regional, meaning they are restricted to the region in which they are reserved. For example, if there is a reserved static internal IP address in Region A, you can only use the IP address in Region A.

Reserve a new static internal IPv4 or IPv6 address

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

If you want to reserve a new static internal IPv6 address, the VPC network must have the ULA internal IPv6 range enabled. In addition, it must have a dual-stack subnet with the INTERNAL IPv6 access type.

To reserve a standalone internal IP address, complete the following steps.

Console

1. In the Google Cloud console, go to the IP addresses page.

   Go to IP addresses

2. Click Reserve internal static IP address. You might need to click the More actions menu to see this button.
3. In the Name field, enter an IP address name.
4. In the IP version list, select the required IP version:
   • To reserve a static internal IPv4 address, select IPv4.
   • To reserve a static internal IPv6 address, select IPv6.
5. In the Network and Subnetwork lists, select a VPC network and a subnet, respectively.
6. Specify how you want to reserve the IP address:
   • For IPv4 addresses, to specify a static internal IPv4 address to reserve, for Static IP address, select Let me choose, and then enter a custom IP address. Otherwise, the system automatically assigns a static internal IPv4 address in the subnet for you.
   • For IPv6 addresses, the system automatically assigns a static internal IPv6 address from the subnet's internal IPv6 address range.

7. Optional: If you want to share the static internal IPv4 address in different frontends, in the Purpose list, choose Shared. The default selection is Non-shared.

   Note: You cannot share a static internal IPv6 address across multiple load balancer frontends.

8. Click Reserve.

gcloud

• To reserve an internal IPv4 address, use the compute addresses create command:

  gcloud compute addresses create ADDRESS_NAMES \
      --region REGION --subnet SUBNETWORK \
      --addresses IP_ADDRESS
  

  Replace the following:

  • ADDRESS_NAMES: the names of one or more [--purpose=SHARED_LOADBALANCER_VIP] addresses that you want to create. In case of multiple addresses, specify all the addresses as a list, separated by spaces—for example, example-address-1 example-address-2 example-address-3
  • 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, an IP address is automatically allocated from the subnet.

• To reserve an internal IPv6 address, use the compute addresses create command. Specify IPV6 as the value for --ip-version:

  gcloud compute addresses create ADDRESS_NAMES \
      --region REGION --subnet SUBNETWORK \
      --ip-version IPV6
  

  Replace the following:

  • ADDRESS_NAMES: the names of one or more addresses that you want to reserve. In case of multiple addresses, specify all the addresses as a list, separated by spaces—for example, example-address-1 example-address-2 example-address-3
  • REGION: the region for this request.
  • SUBNETWORK: the subnet for this internal IPv6 address.

  Unlike internal IPv4 reservation, internal IPv6 reservation doesn't support reserving a specific IP address from the subnetwork. Instead, a /96 internal IPv6 address is automatically allocated from the subnet's /64 internal IPv6 address range.

Examples

• Reserve an automatically allocated internal IPv4 address from a subnet:

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

• Reserve a specific internal IPv4 address from a subnet:

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

• Reserve a static internal IPv6 address from a subnet:

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

• Create multiple IPv4 addresses by passing in more than one IPv4 address name; all the addresses are reserved in the same subnet:

  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
  

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:

module "address" {
  source     = "terraform-google-modules/address/google"
  version    = "~> 3.1"
  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:

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

API

Use the addresses.insert method:

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

For both IPv4 and IPv6 addresses, the body of the request must include the addressType field, which should be INTERNAL, the name of the address, and the subnetwork that the IP address belongs to. The body of the request can optionally include the purpose of the internal IP address.

In addition, for internal IPv4 addresses, you can let the system automatically allocate an IP address for you, or use address to specify an internal IPv4 address. The IPv4 address must belong to the subnet's primary IP address range.

{
  "addressType": "INTERNAL",
  "name": "IPV4_ADDRESS_NAME",
  "subnetwork": "regions/REGION/subnetworks/SUBNETWORK",
  "address": "IPV4_ADDRESS"
  "purpose": "GCE_ENDPOINT"
}

For example:

POST https://compute.googleapis.com/compute/v1/projects/example-project/regions/us-central1/addresses
{
  "addressType": "INTERNAL",
  "name": "example-ipv4-address-1",
  "subnetwork": "regions/us-central1/subnetworks/my-custom-subnet",
  "address": "10.128.0.12"
  "purpose": "GCE_ENDPOINT"
}

For internal IPv6 addresses, you need to also specify ipVersion as IPV6. The system automatically assigns a static internal IPv6 address from the subnet's internal IPv6 address range.

{
  "addressType": "INTERNAL",
  "name": "IPV6_ADDRESS_NAME",
  "ipVersion": "IPV6",
  "subnetwork": "regions/REGION/subnetworks/SUBNETWORK",
  "purpose": "GCE_ENDPOINT"
}

For example:

POST https://compute.googleapis.com/compute/v1/projects/example-project/regions/us-central1/addresses
{
  "addressType": "INTERNAL",
  "name": "example-ipv6-address-1",
  "ipVersion": "IPV6"
  "subnetwork": "regions/us-central1/subnetworks/my-custom-subnet",
  "purpose": "GCE_ENDPOINT"
}

Reserve a static internal IP address range for HA VPN over Cloud Interconnect

You can reserve a static internal IP address range to use with HA VPN over Cloud Interconnect.

When you create the static internal IP address, you must specify the flag --purpose=IPSEC_INTERCONNECT and a prefix length (--prefix-length) between 26 and 29.

The regional internal IPv4 addresses that you reserve are applied to the HA VPN gateways used by Cloud Interconnect.

For more information, see Assign internal IP address ranges to HA VPN gateways.

Determine if an internal IPv4 or IPv6 address is ephemeral or static

Static and ephemeral internal IP addresses behave and appear the same in most contexts. However, with static internal IP addresses, you can use the same IP address for the same resource even if you delete and re-create the resource. In general, an ephemeral IP address is released if you stop or delete the resource.

To determine if an address is static or ephemeral, do the following:

1. In the Google Cloud console, go to the IP addresses page.

   Go to IP addresses

2. Find the address in the list and check the Type column for the type of IP address.

Promote an in-use ephemeral internal IPv4 or IPv6 address to a static address

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

To promote an ephemeral internal IP address to a static internal IP address, complete the following steps.

Console

1. In the Google Cloud console, go to the IP addresses page.

   Go to IP addresses

2. Click Internal IP addresses.
3. Optional: In the Filter field, to search for ephemeral IP addresses, enter ephemeral then select Ephermal : Type from the drop-down list.
4. Select the internal IP address that you want to promote.
5. In the More actions menu () at the end of the display row for the selected IP address, select Promote to static IP address.
6. Enter a name for the new static IP address, and then click Reserve.

gcloud

1. Before promoting an existing ephemeral internal IPv6 address, you need to know the value of that IP address. Use the Google Cloud CLI to make a describe request to the resource to get the IP address value.

   Note: For VM instances, the gcloud CLI returns the networkIP value (for IPv4) or the ipv6Address value (for IPv6), which is the internal IP address being used by the VM. For forwarding rules, the gcloud CLI returns the IPAddress value.

   • For an instance with an IPv4 address, use the following command:

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

   • For an instance with an IPv6 address, use the following command:

     gcloud compute instances describe INSTANCE_NAME --zone ZONE | grep "ipv6Address"
     

   • For a regional forwarding rule, use the following command:

     gcloud compute forwarding-rules describe FORWARDING_RULE_NAME --region REGION | grep "IPAddress"
     

     For a global forwarding rule, use the --global flag instead of the --region flag.

2. Promote the address:

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

     gcloud compute addresses create IPV4_ADDRESS_NAMES \
       --addresses IPV4_ADDRESSES \
       --region REGION \
       --prefix-length PREFIX_LENGTH \
       --subnet SUBNETWORK
     

     Replace the following:

     • IPV4_ADDRESS_NAMES: the names of the IPv4 addresses. In case of multiple addresses, specify all the address names as a list, separated by spaces—for example, example-address-name-1 example-address-name-2 example-address-name-3. Declare the names in the same order that you declare the IP addresses. For example, suppose you specify the address names as example-address-name-1 example-address-name-2 example-address-name-3 and the IPv4 addresses as 192.0.2.0 192.0.2.1 192.0.2.2. In this scenario, Compute Engine maps the names and addresses in the following way:

       • example-address-name-1: 192.0.2.0
       • example-address-name-2: 192.0.2.1
       • example-address-name-3: 192.0.2.2

     • IPV4_ADDRESSES: the IPv4 addresses to promote. In case of multiple addresses, specify all the addresses as a list, separated by spaces—for example, 192.0.2.0 192.0.2.1 192.0.2.2.

     • REGION: the region to reserve this address.

     • PREFIX_LENGTH: Optional. The prefix length of the IPv4 address range. The value must be an integer between 7 and 31. Include this field only if you specify an address range. Exclude the field if the specified IPv4 address is a single IP address.

     • SUBNETWORK: the subnetwork for this request.

   • To promote one or more existing internal IPv6 addresses, use the compute addresses create command and provide the --addresses flag with the explicit internal IPv6 addresses:

     gcloud compute addresses create IPV6_ADDRESS_NAMES \
      --addresses IPV6_ADDRESSES \
      --region REGION \
      --prefix-length PREFIX_LENGTH \
      --subnet SUBNETWORK
     

     Replace the following:

     • IPV6_ADDRESS_NAMES: the names of the address. Declare the names in the same order that you declare the IPv6 addresses. In this case, IPV6_ADDRESS_NAME_1 corresponds with IPV6_ADDRESS_1, and IPV6_ADDRESS_NAME_2 corresponds with IPV6_ADDRESS_2.
     • IPV6_ADDRESS_1,[IPV6_ADDRESS_2,...]: the IPv6 addresses to promote in CIDR format.
     • PREFIX_LENGTH_1,[PREFIX_LENGTH_2,...]: the prefix length of IPv6 addresses.
     • REGION: the region to reserve this address.
     • SUBNETWORK: the subnetwork for this request.

     The internal IPv6 address remains attached to the existing instance even after it has been promoted to a static internal IPv6 address. If you need to assign the newly promoted static internal IPv6 address to another resource, first unassign the static internal IPv6 address from the existing instance.

API

Use the addresses.insert method:

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

For both IPv4 and IPv6 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 that the IP address belongs to. For IPv6 addresses, additionally, the body of the request must include prefixLength with 96 as the value.

• Request body for promoting internal IPv4 addresses:

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

  For example:

  POST https://compute.googleapis.com/compute/v1/projects/example-project/regions/us-central1/addresses
  {
  "name": "example-IPv4-address-1",
  "addressType": "INTERNAL",
  "address": "10.128.0.2",
  "subnetwork": "regions/us-central1/subnetworks/my-custom-subnet"
  }
  

• Request body for promoting internal IPv6 addresses:

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

  For example:

  POST https://compute.googleapis.com/compute/v1/projects/example-project/regions/us-central1/addresses
  {
  "name": "example-IPv6-address-1",
  "addressType": "INTERNAL",
  "address": "fd20:0:0::",
  "subnetwork": "regions/us-central1/subnetworks/my-custom-subnet"
  "prefixLength": 96
  }
  

Use a static internal IPv4 or IPv6 address with Shared VPC

You can create a reserved static internal IP address 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 IP addresses in the selected shared subnet of the Shared VPC network. For more information about this use case, see the following resources:

• The IP addresses section in the Shared VPC overview
• The Reserve a static internal IPv4 or IPv6 address section in Provision Shared VPC

List static internal IPv4 or IPv6 addresses

To view all your existing static internal IP addresses, complete the following steps.

Console

1. In the Google Cloud console, go to the IP addresses page.

   Go to IP addresses

2. Click Internal IP addresses.

gcloud

Use the gcloud compute addresses list command:

gcloud compute addresses list

API

Use the addresses.list method:

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

Replace the following:

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

To list all the addresses in all regions, use the addresses.aggregatedList method:

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

Release a static internal IPv4 or IPv6 address

If you no longer need a static internal IP address, you can release the IP address by deleting the IP address resource.

If you are using the Google Cloud console, you can release a static IP address only if it is not being used by another resource.

If you're using the gcloud CLI or API, you can release an IP address whether or not it's being used by another resource.

• If the IP address is not being used by a resource, the IP address is returned to the pool of available internal IP addresses.

• If the IP address is being used by a resource, it remains attached to the resource until the resource is deleted.

To release a static internal IPv4 or IPv6 address, complete the following steps.

Console

1. In the Google Cloud console, go to the IP addresses page.

   Go to IP addresses

2. Select the Internal IP addresses tab.
3. Optional: In the Filter field, enter static and then select Static : Type from the drop-down list.
4. Select the static internal IP address that you want to release.

5. Click Release static address, and then confirm this operation by clicking Release in the dialog.

   If you don't see this option, click the More actions menu () in the top menu bar, and then select Release static address from the list.

gcloud

Use 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

Use the addresses.delete method:

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

This example deletes 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 how to configure static internal IP addresses for VMs.

• Create an internal load balancer that uses a static internal IPv4 address:

  • Set up an internal passthrough Network Load Balancer with VM instance group backends
  • Set up an internal Application Load Balancer with VM instance group backends
  Note: You can create only internal passthrough Network Load Balancers by using internal IPv6 addresses. For more information about the supported IP address type for different load balancers, see Summary of Google Cloud load balancers.

• Learn about IP address specifications for forwarding rules, and how to use forwarding rules, in the Forwarding rules overview.

• Learn more about IP addresses.