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 andHOSTNAME.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 theSUSPENDED
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:
- Install or update to the latest version of the gcloud command-line tool.
- 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 andHOSTNAME.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 renameNEW_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 renameZONE
: zone containing the instance to renameINSTANCE_NAME
: instance to renameNEW_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 ofZONE
: zone containing the instance to get the ID ofINSTANCE_NAME
: name of the instance to get the ID of
What's next
Learn about the instance life cycle.