Configure static internal IP addresses

This page shows you how to configure and manage static internal IPv4 or IPv6 addresses for your Compute Engine virtual machine (VM) instances.

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

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. To learn about IP addresses, read the IP addresses documentation.

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

To configure a static external IP address instead of an internal IP address, see Configure 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 to Compute Engine 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

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

      gcloud init
    2. Set a default region and zone.

    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.

    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 configure and manage static IP addresses, ask your administrator to grant you the following IAM roles on your project:

For more information about granting roles, see Manage access.

These predefined roles contain the permissions required to configure 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 configure and manage static IP addresses:

  • compute.instances.update on the VM instance
  • compute.instances.updateNetworkInterface on the VM instance
  • compute.instances.addAccessConfig on the VM instance
  • compute.instances.deleteAccessConfig on the VM instance
  • compute.networks.list on the network
  • compute.subnetworks.use on the subnet
  • compute.subnetworks.list on the subnet
  • To create VMs:
    • compute.instances.create on the project
    • To use a custom image to create the VM: compute.images.useReadOnly on the image
    • To use a snapshot to create the VM: compute.snapshots.useReadOnly on the snapshot
    • To use an instance template to create the VM: compute.instanceTemplates.useReadOnly on the instance template
    • To assign a legacy network to the VM: compute.networks.use on the project
    • To specify a static IP address for the VM: compute.addresses.use on the project
    • To assign an external IP address to the VM when using a legacy network: compute.networks.useExternalIp on the project
    • To specify a subnet for the VM: compute.subnetworks.use on the project or on the chosen subnet
    • To assign an external IP address to the VM when using a VPC network: compute.subnetworks.useExternalIp on the project or on the chosen subnet
    • To set VM instance metadata for the VM: compute.instances.setMetadata on the project
    • To set tags for the VM: compute.instances.setTags on the VM
    • To set labels for the VM: compute.instances.setLabels on the VM
    • To set a service account for the VM to use: compute.instances.setServiceAccount on the VM
    • To create a new disk for the VM: compute.disks.create on the project
    • To attach an existing disk in read-only or read-write mode: compute.disks.use on the disk
    • To attach an existing disk in read-only mode: compute.disks.useReadOnly on the disk

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.

How to configure a static internal IP address

You can reserve a static internal IP address, and then specify the reserved address when creating a VM. You can also create the VM with an ephemeral internal IP address and then promote that ephemeral IP address to a static internal IP address.

To use a static internal IP address, you must have a VPC network in place for your project. To view the VPC networks in your project, see View VPC networks.

Reserve a static internal IPv4 or IPv6 address and then associate it with a specific VM

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

  1. Choose a subnet in your VPC network. For IPv6 addresses, make sure that it is a dual-stack subnet.

  2. Reserve an internal IP address from the subnet's primary IP range. This step creates a named internal IP address resource that contains that specific internal IP address. Reserving the IP address prevents Google Cloud from automatically allocating that address as an ephemeral address.

  3. Use the reserved internal IP address by associating it with a VM instance when you create the VM resource.

Specify an ephemeral internal IPv4 or IPv6 address for a VM and then promote the address

In this scenario, you promote an ephemeral internal IPv4 or IPv6 address that is still attached to a VM:

  1. Choose a subnet in your VPC network. For IPv6 addresses, make sure that it is a dual-stack subnet.

  2. Create a VM instance with either an automatically allocated ephemeral IPv4 or IPv6 address or a specific IPv4 address.

  3. Promote the ephemeral internal IP address to a static address.

The two methods are outlined in Figure 1.

Internal IP address reservation states.
Figure 1. Internal IP address reservation states (click to enlarge).

View available static internal IP 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

Configure static internal IP addresses

VM interfaces are assigned IP addresses from the subnet that they are connected to. Each VM interface has one primary internal IPv4 address that is assigned from the subnet's primary IPv4 range. If the VM is connected to a dual-stack subnet with an internal IPv6 range, you can assign an internal IPv6 address to each network interface.

Internal IPv4 addresses can be assigned in the following ways:

  • Compute Engine assigns a single IPv4 address from the primary IPv4 subnet range automatically.
  • You can assign a specific internal IPv4 address when you create a VM instance, or you can reserve a static internal IPv4 address for your project and assign that address to a VM network interface.

Internal IPv6 addresses can be assigned in the following ways:

The following procedures let you configure static internal IP addresses for your VMs:

Create a VM instance with a reserved internal IPv4 or IPv6 address

After you reserve a static internal IP address, you can assign the reserved address to a VM instance when you create the instance.

When you create a VM that is connected to a dual-stack subnet with an internal IPv6 range without specifying any reserved static internal IPv6 address, Compute Engine automatically assigns the VM an ephemeral internal IPv6 address from the subnet's IPv6 range.

Console

  1. In the Google Cloud console, go to the Create an instance page.

    Go to Create an instance

  2. Expand the Advanced options section.

  3. Expand the Networking section.

  4. To assign an internal IPv4 address, do the following:

    1. Select a network and a subnetwork.
    2. Select a reserved internal IPv4 address from the Primary internal IPv4 address list.

    Alternatively, select Reserve static internal IP address and reserve a new static internal IPv4 address.

  5. To assign an internal IPv6 address, do the following:

    1. Select a network that contains an IPv6 subnet.
    2. Select a dual-stack subnet from the Subnetwork list. The subnet must have the INTERNAL IPv6 access type.
    3. For IP stack type, select IPv4 and IPv6 (dual-stack).
    4. Select a reserved internal IPv6 address from the Primary internal IPv6 address list.

    Alternatively, select Reserve static internal IPv6 address and reserve a new static internal IPv6 address.

  6. To finish modifying the default network interface, click Done.

  7. Continue with the VM creation process.

  8. Click Create.

gcloud

  • To create an instance with a reserved internal IPv4 address, use the --private-network-ip flag to specify a reserved internal IPv4 address when you create the instance:

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

    Replace the following:

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

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

  • To create an instance with a reserved internal IPv6 address, use the --internal-ipv6-address flag to specify the reserved internal IPv6 address when you create the instance:

    gcloud compute instances create VM_NAME
    --subnet SUBNETWORK
    --stack-type IPV4_IPV6
    --internal-ipv6-address INTERNAL_IPV6_ADDRESS
    --zone ZONE

    Replace the following:

    • VM_NAME: the name of the VM that you want to create.
    • SUBNETWORK: the subnet for the internal IPv6 address.
    • INTERNAL_IPV6_ADDRESS: the /96 IPv6 address, the IP address name, or the URI of the address resource. The IP address must be reserved before you can use it.
    • ZONE: the zone for the VM.

REST

To create a VM instance with a static internal IP address, use the instances.insert method.

  • For internal IPv4 addresses, explicitly provide the networkInterfaces[].networkIP property with the internal IPv4 address that 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": "IPV4_ADDRESS"
}],
"disks": [{
  "autoDelete": "true",
  "boot": "true",
  "type": "PERSISTENT",
  "initializeParams": {
      "sourceImage": "projects/debian-cloud/global/images/v20150818"
  }
}]
}

    Replace the following:

    • PROJECT_ID: the ID of the project to create the VM in.
    • ZONE: the zone to create the VM in.
    • VM_NAME: the name of the virtual machine.
    • IPV4_ADDRESS: the internal IPv4 address to assign to the VM.

  • For internal IPv6 addresses, explicitly specify the values for the following properties:

    • networkInterfaces[].stackType
    • networkInterfaces[].ipv6Address
    • networkInterfaces[].internalIpv6PrefixLength
    • networkInterfaces[].ipv6AccessType

    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",
  "stackType": "IPV4_IPV6"
  "ipv6Address": ""IPV6_ADDRESS"",
  "internalIpv6PrefixLength": 96
  "ipv6AccessType": INTERNAL,
}],
"disks": [{
  "autoDelete": "true",
  "boot": "true",
  "type": "PERSISTENT",
  "initializeParams": {
      "sourceImage": "projects/debian-cloud/global/images/v20150818"
  }
}]
}

    Replace the following:

    • PROJECT_ID: the ID of the project to create the VM in.
    • ZONE: the zone to create the VM in.
    • VM_NAME: the name of the VM.
    • IPV6_ADDRESS: the internal IPv6 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.

Use a static internal IPv4 or IPv6 address for a secondary network interface

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

To use a static internal IPv4 or IPv6 address for a secondary network interface, see Create VM instances with multiple network interfaces.

Change or assign an internal IPv6 address to an existing VM

You can change or assign an internal IPv6 address to an existing VM instance.

If the instance already has an internal IPv6 address assigned to it, you must first unassign that address. Then, assign a new address to the instance by using the instance's network interface.

To change or assign a static internal IPv6 address to an existing VM instance, complete the following steps.

Console

  1. Reserve a static internal IPv6 address.
  2. In the Google Cloud console, go to the VM instances page.

    Go to VM instances

  3. Click the name of the instance whose internal IPv6 address you want to change.

  4. On the Instance details page, complete the following steps:

    1. Click Edit.
    2. Expand Network interfaces.
    3. In the Primary internal IPv6 address list, select either Auto-allocated (/96) or a reserved static internal IPv6 address.
    4. Click Done.

  5. Click Save.

gcloud

Use the compute instances network-interfaces update command.

gcloud compute instances network-interfaces update VM_NAME \
    --network-interface NIC \
    --ipv6-network-tier PREMIUM \
    --stack-type IPV4_IPV6 \
    --internal-ipv6-address INTERNAL_IPV6_ADDRESS \
    --zone ZONE

Replace the following:

  • VM_NAME: the name of the VM that you want to create.
  • NIC: the name of the network interface to update.
  • INTERNAL_IPV6_ADDRESS: the /96 internal IPv6 address to be assigned to the interface, the IP address name, or the URI of the address resource.
  • ZONE: the zone for the VM.

REST

Use the instances.update method. Update the networkInterfaces[].ipv6Address property with the internal IPv6 address that you want to assign.

For example: 

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME
  {
    ...
    "networkInterfaces": [{
      "accessConfigs": [{
        "type": "ONE_TO_ONE_NAT",
        "name": "External NAT",
      }],
      "stackType": "IPV4_IPV6"
      "ipv6Address": "IPV6_ADDRESS",
      "internalIpv6PrefixLength": 96
      "subnetwork": "regions/REGION/subnetworks/SUBNETWORK",
    }],
    "disks": [{
      "autoDelete": "true",
      "boot": "true",
      "type": "PERSISTENT",
      "initializeParams": {
          "sourceImage": "projects/debian-cloud/global/images/v20150818"
      }
    }]
  }

Replace the following:

  • PROJECT_ID: the ID of the project the VM is in.
  • ZONE: the zone to create the VM in.
  • VM_NAME: the name of the VM.

  • IPV6_ADDRESS: the internal IPv6 address to assign to the VM.

    If you specify the URI of the internal IPv6 address resource or an IPv6 address range as the value for IPV6_ADDRESS, then you must leave the value of internalIpv6PrefixLength blank.

Manage static internal IP addresses

The following procedures let you manage static internal IP addresses for your VMs:

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.

Unassign a static internal IPv6 address

You can unassign a static internal IPv6 address from a VM instance by updating the instance's network interface or by deleting the instance to which the address is assigned.

When you unassign an internal IPv6 address, the system removes it from the resource but keeps the address reserved for your project. You can later reassign the address to another resource.

To unassign a static internal IPv6 address from a VM instance, complete the following steps.

Console

  1. In the Google Cloud console, go to the VM instances page.

    Go to VM instances

  2. Click the name of the instance whose internal IPv6 address you want to unassign.

  3. On the Instance details page, complete the following steps:

    1. Click Edit.
    2. Expand Network interfaces.
    3. For IP stack type, select IPv4 (single-stack).
    4. Click Done.

  4. Click Save.

gcloud

Use the compute instances network-interfaces update command with the --stack-type flag set to IPV4_ONLY:

gcloud compute instances network-interfaces update VM_NAME \
    --network-interface NIC \
    --stack-type IPV4_ONLY \
    --zone ZONE

Replace the following:

  • VM_NAME: the name of the VM whose network interface you want to update.
  • NIC: the name of the network interface to update.
  • ZONE: the zone for the VM.

Check that your static internal IPv6 address is now available and marked as RESERVED instead of IN_USE:

gcloud compute addresses list \
    --filter="region=REGION AND name=NAME"

REST

Update the instance stack type of the network interface where the internal IPv6 address is attached:

  1. Make a PATCH request to the instances.updateNetworkInterface method.

  2. In the request body, update the value of the stackType field to IPV4_ONLY.

    For example:

    PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/updateNetworkInterface
{
  "networkInterfaces": [{
    ...
    "stackType" : "IPV4_ONLY"
    ...
    }]
}

    Replace the following:

    • PROJECT_ID: the ID of the project that the VM is in.
    • ZONE: the zone to create the VM in.
    • VM_NAME: the name of the VM.

Release a static internal IP address

If you no longer need a static external IPv4 or IPv6 address, you can release the IP address by deleting the IP address resource. Deleting a VM doesn't automatically release a static external IP address. You must manually release static external IP addresses when you no longer require them.

To release a static internal IP address, see Release a static internal IPv4 or IPv6 address in the VPC documentation.

What's next