Renaming an instance

This document describes how to rename a virtual machine (VM) instance. To stop or start an instance, see Stopping and starting an instance. To suspend or resume an instance, see Suspending and resuming an instance. For information about the instance life cycle, see Instance life cycle.

When creating an instance, you must specify a name. After creation, you might want to change the instance's name so that the name:

  • Better represents the workload running on the instance
  • Refers to the operating system running on the instance
  • Adheres to any naming conventions required by your organization

Instance URIs

Changing the name of an instance might affect your projects. Instead of referencing instance resources by their name, you can reference them by their URI, which is permanent. The URI has the following format: projects/PROJECT_NAME/zones/ZONE/instances/INSTANCE_ID.

For information about getting the instance ID, see Getting the instance ID.

Pricing

Renaming an instance does not change the amount you are billed. Also, because your bill shows VM instances according to their stock keeping units (SKUs), not their names, you will not see the names of your VM instances on your bill.

Limitations

Automatically named resources
When you rename an instance, any resources that are named based on the original instance name are not updated. For example, if you add a disk to an instance while creating that instance, and choose to rename the disk automatically based on the instance name, the disk is not renamed.
Console
You must refresh your browser for the Cloud Console to update the name of the VM.
DHCP server
After renaming an instance, the DHCP server responds to DHCP requests with the updated hostname with the format HOSTNAME.c.PROJECT_ID.internal for global DNS and HOSTNAME.ZONE.c.PROJECT_ID.internal for zonal DNS. For more information, see Types of internal DNS names.
Hostnames

Hostnames are modified when you change the name of the instance. On Windows, hostname updates might require a reboot.

Instances that have custom hostnames are not updated.

Changing the hostname directly on the host does not affect the name of the VM resource.

Instance states

Stop the instance before renaming it because you can only rename instances that are in the TERMINATED state. You can't, for example, rename an instance that is in the SUSPENDED state.

Managed instance groups

You can't rename instances that are in managed instance groups (MIGs) because these instances automatically and irreversibly inherit their names from the base instance name property of their stateless MIG.

Naming conventions

You can't rename an instance with a name that is already in use by another instance in the project.

Instance names must adhere to the resource naming conventions.

Before you begin

  • If you want to use the command-line examples in this guide:
    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.
  • Review, and if applicable, update the following:
    • Cloud Monitoring groups, charts, and alerts: Monitoring matches strings, and when you rename an instance, these strings are not updated. If you rename a VM, update your Monitoring rules to include the renamed VMs in your reports.
    • Console URLs: Renaming a VM changes its console URL. If you rename a VM, update links, such as browser bookmarks, that reference the VM's console URL.
    • Identity and Access Management (IAM) conditional role bindings: Conditional role bindings support granting permissions on the name of the resource. For example, IAM might grant a role to a user if the name of a VM begins with a particular string. These bindings are not updated when you change the name of a VM, so a user's access to the VM resource might be affected because you are changing the set of VMs that the prefixed name applies to. If you rename a VM, update these bindings.
    • Internal DNS service cache: The internal DNS service assigns internal DNS names to VMs, in which the hostname is of the format HOSTNAME.c.PROJECT_ID.internal for global DNS and HOSTNAME.ZONE.c.PROJECT_ID.internal for zonal DNS. After renaming a VM, these hostnames change. Then, the internal DNS service begins resolving to the new hostname, and requests to the previous DNS name fail. If you rename a VM, you might need to update your DNS cache to update the hostname. For more information about global DNS and zonal DNS hostnames, see Types of internal DNS names.
    • Metadata queries: After renaming a VM, the metadata server reports the new name. If you rename a VM, update any scripts or programs that query the metadata server so they query for the VM's new name.
    • Organization policies restricting external IP addresses: Constraints against VMs that have an external IP address reference the VM name. When you rename a VM, this constraint is not updated. If you rename a VM, update the external IP organization policy with the VM's new name.

Renaming an instance

You must stop an instance before renaming it. If, after renaming, you receive an error message in the Google Cloud Console, refresh your browser.

Permissions required for this task

To perform this task, you must have the following permissions:

  • compute.instances.setName on the instance

gcloud

Before renaming the instance, stop it by using the gcloud compute instances stop command. After renaming, start the instance by using the gcloud compute instances start command.

Rename the instance by using the gcloud beta compute instances set-name command:

gcloud beta compute instances set-name INSTANCE_NAME \
    --new-name=NEW_INSTANCE_NAME

Replace the following:

  • INSTANCE_NAME: name of the instance to rename
  • NEW_INSTANCE_NAME: new name for the instance

API

Before renaming the instance, stop it by using the instances.stop method. After renaming, start the instance by using the instances.start method.

To get the status of the renaming, poll the operation ID returned by the rename API. After renaming, API calls that depend on the previous name return a 404 Not Found status code. For more information, see Handling API responses.

Rename the instance by using the instances.setName method:

POST https://www.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME/setName

{
    Name: "NEW_INSTANCE_NAME"
}

Replace the following:

  • PROJECT_ID: ID of the project containing the instance to rename
  • ZONE: zone containing the instance to rename
  • INSTANCE_NAME: instance to rename
  • NEW_INSTANCE_NAME: new name for the instance

Getting the instance ID

The instance ID lets you reference a VM by using an immutable value.

gcloud

Get the instance ID by using the gcloud compute instances describe command. This command returns the instance ID as a string in the id field.

gcloud compute instances describe INSTANCE_NAME

Replace INSTANCE_NAME with the name of the instance.

API

Get the instance ID by using the instances.get method. This method returns the instance ID as a string value for the id in the response body.

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

Replace the following:

  • PROJECT_ID: ID of the project containing the instance to get the ID of

  • ZONE: zone containing the instance to get the ID of

  • INSTANCE_NAME: name of the instance to get the ID of

What's next