Configuring an Instance's IP Addresses

This page explains how to configure and manage IP addresses for your instances, including:

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

Each virtual machine instance has an ephemeral internal IP address and, optionally, an external IP address. To communicate between instances on the same network, you can use an instance's internal IP address. To communicate with the Internet and instances outside of the same network, you must specify the instance's external IP address.

Internal IP addresses are ephemeral and only belong to an instance for the lifetime of the instance; if the instance is deleted and recreated, the instance is assigned a new internal IP address, either by Compute Engine or by you. External IP addresses can be either ephemeral or static.

To learn more about IP addresses, read the IP Addresses documentation.

Contents

Before you begin

Reserving a new static external IP address

A static external IP address belongs to your project until you decide to release it. To use a static external IP address, you must first reserve it. After reserving the address, assign the address to an instance or network load balancer.

Reserve a static external IP address in gcloud or through the API. After reserving the address, assign it to an instance during instance creation or to an existing instance.

Restrictions

  • Only one resource at a time can use a static external 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 external 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.

Note: You can only assign a static external IP address to a single instance. However, it is possible that your instance might receive traffic from multiple forwarding rules, which may serve other external IP addresses. In summary, a virtual machine instance can:

  • Have one static external IP address attached using the instance's accessConfig. Packets for this IP will have their destination IP translated to the instance's internal IP address.
  • Have any number of external IP addresses referencing the instance through forwarding rules and target pools.

For more information, review the load balancing documentation.

Console


  1. Go to the Reserve a static address page in the Cloud Platform Console.

    Go to the Reserve a static address page

  2. Choose a name for the new address.
  3. Choose whether this IP address is regional or global. To reserve a static IP for an instance, choose Regional.
  4. Select the region to create this IP in.
  5. [Optional] Select an instance to attach the IP.
  6. Click Reserve to reserve the IP.

gcloud


To reserve a new static external IP address using gcloud compute, use the addresses create sub-command:

gcloud compute addresses create [ADDRESS_NAME]

where [ADDRESS_NAME] is the name you want to call this address.

API


With the API client libraries, use the addresses().insert function, passing in the region for the request and a request body that contains the name of the address. The following is a snippet from the Python client library:

def reserveIpAddress(auth_http, gce_service):
  addressName = "[ADDRESS_NAME]"
  region = "[REGION]"
  body = {
    "name": addressName,
  }
  request = gce_service.addresses().insert(project=[PROJECT_ID],
    region=region, body=body)
  response = request.execute(auth_http)

  print response

where:

  • [ADDRESS_NAME] is the name you want to call this address.
  • [REGION] is the name of the region for this request.
  • [PROJECT_ID] is the project ID for this request.

To make a request to the API directly, make a PUT request to the following URI:

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

Your request body should contain the following:

{
  name: "[ADDRESS_NAME]"
}

Assigning a static external IP address to a new instance

When you create an instance, it is assigned an ephemeral external IP address by default. Alternatively, you can explicitly reserve a static external IP address to an instance instead.

You must reserve the static external IP address before you assign it.

Console


  1. In the Cloud Platform Console, go to the VM Instances page.

    Go to the VM Instances page

  2. Click the Create instance button.
  3. On the Create a new instance page, fill in the desired properties for your instance.
  4. Expand the Management, disk, networking, SSH keys section.
  5. Click Networking.
  6. Under External IP, select a static external IP address.
  7. Click the Create button to create the instance.

gcloud


To assign a static external IP address, use the --address flag during instance creation and provide the static external IP address:

gcloud compute instances create [INSTANCE_NAME] --address [IP_ADDRESS]

where:

  • [INSTANCE_NAME] is the name of the instance.
  • [IP_ADDRESS] is the IP address to assign to the instance. Use the IP address, not the address name.

API


In your request to create a new instance, explicitly provide the networkInterfaces[].accessConfigs[].natIP property and the external IP you want to use. For example:

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

where:

  • [INSTANCE_NAME] is the name of the instance.
  • [IP_ADDRESS] is the IP address to assign to the instance.

Assigning an external IP address to an existing instance

You can assign an external IP address, either ephemeral or static, to an existing instance by modifying the instance's access configuration.

An instance can have only one external IP address. If the instance already has an external IP address, you can remove that address by deleting the old access configuration. Then you can add a new access configuration with the new external IP address.

Console


  1. Go to the VM instances page in the Cloud Platform Console.

    Go to the VM instances page

  2. Click the name of the instance that you want to assign an external IP to.
  3. Click the Edit button at the top of the page.
  4. Under External IP, select either an ephemeral or static external IP address to assign to the instance.
  5. Click the Save button to save your changes.

gcloud


  1. [Optional] Reserve a static external IP address.

    If you want to assign a static external IP address, you must reserve an address and make sure the address is not currently in use by another resource. If necessary, follow the instructions to reserve a new static external IP address or to unassign a static external IP address.

    If you intend to use an ephemeral external IP address, you can skip this step, and Compute Engine will randomly assign an ephemeral external IP address.

  2. Delete existing access configs.

    It is only possible to assign one access config per instance. Before you attempt to assign a new access config to an instance, check to see if your instance has an access config by making a gcloud compute instances describe request:

    gcloud compute instances describe [INSTANCE_NAME]
    

    If there is an existing access config, the access config appears in the following format:

    networkInterfaces:
    - accessConfigs:
      - kind: compute#accessConfig
        name: external-nat
        natIP: 130.211.181.55
        type: ONE_TO_ONE_NAT

    Before you add a new access config, you must delete the existing access configuration using the instances delete-access-config sub-command:

    gcloud compute instances delete-access-config [INSTANCE_NAME] \
        --access-config-name [ACCESS_CONFIG_NAME]`
    

    where:

    • [INSTANCE_NAME] is the name of the instance.
    • [ACCESS_CONFIG_NAME] is the access config to delete.
  3. Add the new external IP address.

    Using the instances add-access-config sub-command, add a new external IP address:

    Note: Don't replace [IP_ADDRESS] with the name of the static IP. You must use the actual IP address.

    gcloud compute instances add-access-config [INSTANCE_NAME] \
        --access-config-name [ACCESS_CONFIG_NAME] --address [IP_ADDRESS]
    

    where:

    • [INSTANCE_NAME] is the name of the instance.
    • [ACCESS_CONFIG_NAME] is access config to delete.
    • [IP_ADDRESS] is the IP address to add.

    If you want Compute Engine to assign an ephemeral external IP address rather than using a static external IP address, omit the --address [IP_ADDRESS] property:

    gcloud compute instances add-access-config [INSTANCE_NAME] \
        --access-config-name [ACCESS_CONFIG_NAME]
    

Promoting an ephemeral external IP address

If your instance has an ephemeral external IP address and you want to use the IP beyond the life of the instance, promote the ephemeral external IP address to a static external IP address. This assigns the IP permanently to your project until you explicitly release it.

Console


  1. Go to the External IP addresses page in the Cloud Platform Console.

    Go to the External IP addresses page

  2. In the Type column, change the address type to Static for the IP address you want to promote.
  3. Provide a name for the new static IP address and click Reserve.

gcloud


To promote an ephemeral external IP address to a static external IP address, provide the ephemeral external IP address using the --addresses flag when creating a new address:

gcloud compute addresses create [ADDRESS_NAME] \
    --addresses [IP_ADDRESS]

where:

  • [ADDRESS_NAME] is the name you want to call this address.
  • [IP_ADDRESS] is the IP address you want to promote.

API


With the API client libraries, use the addresses().insert function, passing in the region for the request and a request body that contains the name of the address and the ephemeral external IP address to promote. The following is a snippet from the Python client library:

def promoteIpAddress(auth_http, gce_service):
  addressName = "[ADDRESS_NAME]"
  region = "[REGION]"
  ipAddressToPromote = "[IP_ADDRESS]"
  body = {
    "name": addressName,
    "address": ipAddressToPromote
  }
  request = gce_service.addresses().insert(project=[PROJECT_ID],
    region=region, body=body)
  response = request.execute(auth_http)

  print response

where:

  • [ADDRESS_NAME] is the name you want to call this address.
  • [IP_ADDRESS] is the IP address you want to promote.
  • [REGION] is the name of the region for this request.
  • [PROJECT_ID] is the project ID for this request.

To make a request to the API directly, make a PUT request to the following URI:

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

Your request body should contain the following:

{
  name: "[ADDRESS_NAME]",
  address: "[IP_ADDRESS]"
}

The external IP address remains attached to the instance even after it is been promoted to a static external IP address. If you need to assign the newly-promoted static external IP address to another resource, unassign the static external IP address from the existing instance.

Listing static external IP addresses

To list static external IP addresses that you have reserved for your project, run addresses list or make a GET request to the API.

Console


Go to the External IP addresses page in the Cloud Platform Console to see a list of IP addresses for your project.

Go to the External IP addresses page

gcloud


In gcloud:

gcloud compute addresses list

API


With the API client libraries, use the addresses().list function. Here's a snippet from the Python client library that lists static IP addresses from one region:

def listIpAddresses(auth_http, gce_service):
  request = gce_service.addresses().list(project=[PROJECT_ID],
    region="[REGION]")
  response = request.execute(auth_http)

  print response

where:

  • [REGION] is the name of the region for this request.
  • [PROJECT_ID] is the project ID for this request.

To make a request to the API directly, perform a GET request to the following URI with an empty request body:

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

To list all addresses in all regions, make a request to the following URI:

https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/aggregated/addresses

In the client libraries, use the addresses().aggregatedList function:

def listAllIpAddresses(auth_http, gce_service):
  request = gce_service.addresses().aggregatedList(project=[PROJECT_ID])
  response = request.execute(auth_http)

  print response

Describing a static external IP address

To get information about a static external IP address, use the gcloud compute addresses describe command and provide the name of the address, or make a GET request to the API.

Console


  1. Go to the External IP addresses page in the Cloud Platform Console.

    Go to the External IP addresses page

  2. Click on the IP address you want to get more information about.

gcloud


To use gcloud compute addresses describe:

gcloud compute addresses describe [ADDRESS_NAME]

where [ADDRESS_NAME] is the name of the external IP address you want to describe.

API


With the API client libraries, use the addresses().get method and specify the address for which you want to get more information:

def getIpAddress(auth_http, gce_service):
  addressName = "[ADDRESS_NAME]"
  request = gce_service.addresses().get(project="[PROJECT_ID]",
    region="[REGION]", address=addressName)
  response = request.execute(auth_http)

  print response

where:

  • [ADDRESS_NAME] is the name of the IP address.
  • [REGION] is the name of the region for this request.
  • [PROJECT_ID] is the project ID for this request.

To make a request to the API directly, make a GET request with an empty request body to the following URI:

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

Unassigning a static external IP address

You can unassign a static external IP address by deleting the instance or deleting the access config attached to the instance that is using the address. Unassigning a static external IP address from an instance allows you to reassign the static external IP address to another resource.

You can tell that an static IP address is in use by performing a gcloud compute addresses list request:

gcloud compute addresses list
NAME                 REGION      ADDRESS            STATUS
example-address      [REGION]    130.211.160.207    RESERVED
example-address-new  [REGION]    130.211.114.137    IN_USE

In this example, example-address-new is currently in use.

To delete an instance's access config and unassign a static external IP address, follow these steps:

  1. Get the name of the access config to delete.

    To get the name, perform a gcloud compute instances describe request:

    gcloud compute instances describe [INSTANCE_NAME]
    

    where [INSTANCE_NAME] is the name of the instance.

    The access config appears in the following format:

    networkInterfaces:
    - accessConfigs:
      - kind: compute#accessConfig
        name: external-nat
        natIP: 130.211.181.55
        type: ONE_TO_ONE_NAT

    Note: The name of your access config might be different than external-nat; make sure to check for your own access config name. In some cases, an older version of the access config name, External NAT, might be used.

  2. Delete the access config.

    Use the instances delete-access-config sub-command:

    gcloud compute instances delete-access-config [INSTANCE_NAME] \
        --access-config-name [ACCESS_CONFIG_NAME]
    

    where:

    • [INSTANCE_NAME] is the name of the instance.
    • [ACCESS_CONFIG_NAME] is the name of the access config to delete.
  3. Check that your static external IP address is now available and marked as RESERVED instead of IN_USE.

    gcloud compute addresses list
    

    NAME                 REGION      ADDRESS            STATUS
    example-address      [REGION]    130.211.160.207    RESERVED
    example-address-new  [REGION]    130.211.114.137    RESERVED

Now that your static external IP address is available, you can choose to assign it to another instance.

Releasing a static external IP address

Releasing a static external IP address returns it to the general IP pool for other Compute Engine users.

Console


  1. Go to the External IP addresses page in the Cloud Platform Console.

    Go to the External IP addresses page

  2. Check the box next to the IP address to release.
  3. Click Release IP address.

gcloud


In gcloud:

gcloud compute addresses delete [ADDRESS_NAME]

where [ADDRESS_NAME] is the name of the IP address.

API


With the API client libraries, use the addresses().delete method, providing the address name and the region:

def releaseAddress(auth_http, gce_service):
  addressName = "[ADDRESS_NAME]"
  request = gce_service.addresses().delete(project="[PROJECT_ID]",
    region="[REGION]", address=addressName)
  response = request.execute(auth_http)

  print response

where:

  • [ADDRESS_NAME] is the name of the IP address.
  • [REGION] is the name of the region for this request.
  • [PROJECT_ID] is the project ID for this request.

To make a request to the API directly, make a DELETE request to the following URI with an empty request body:

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

Specifying an internal IP address at instance creation

You can assign a specific internal IP address to an instance when you create it. 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.

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

gcloud


gcloud compute instances create [INSTANCE_NAME]
     --private-network-ip [IP_ADDRESS]

where:

  • [INSTANCE_NAME] is the name of the instance you want to create.
  • [IP_ADDRESS] is 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 an instance with a static internal IP address, use the Compute Engine API. Make a request to create a new instance, as you would normally but explicitly provide the networkInterfaces[].networkIP property with the internal IP you want to use. For example:

{
  "name": "[INSTANCE_NAME]",
  "machineType": "zones/us-central1-f/machineTypes/f1-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"
     }
   }]
 }

where:

  • [INSTANCE_NAME] is the name of the instance.
  • [IP_ADDRESS] is the IP address to assign to the instance.

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 set a static internal target IP address using routes.

What's next

Send feedback about...

Compute Engine Documentation