When you create a virtual machine (VM) instance, you must specify a name. However, after creating a VM, you can rename it. This is useful when you want to choose a different name. There are many reasons you might change the name of a VM, the following reasons are a few examples:
- To better represent the workload running on the VM
- To refer to the operating system running on the VM
- To adhere to any naming conventions required by your organization
VM uniform resource identifiers (URIs)
Changing the name of a VM might affect your projects. Instead of referencing VM
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 VM instance ID, see Get the ID of a VM instance.
Pricing
Renaming a VM does not change the amount that you are billed. Also, because your bill shows VMs according to their stock keeping units (SKUs) and not their names, you will not see the names of your VMs on your bill.
Limitations
Limitations on the following apply when renaming a VM:
Automatically named resources:
- When you rename a VM, the names of any resources that were based on the original VM name are not updated. For example, when you create a VM, the name of the boot disk is the same as the name of the VM. If you rename the VM, the name of the boot disk does not change.
DHCP server:
- After renaming a VM, 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.
- After renaming a VM, the DHCP server responds to DHCP requests with the
updated hostname with the format
Google Cloud console:
- You must refresh your browser for the Google Cloud console to update the name of the VM.
Hostnames:
Hostnames are modified when you change the name of the instance. On Windows, hostname updates might require a reboot.
VMs that have custom hostnames are not updated.
Changing the hostname directly on the host does not affect the name of the VM resource.
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.
- You can't rename instances that are in managed instance groups (MIGs)
because these instances automatically and irreversibly inherit their names
from the
Naming conventions:
You can't rename a VM with a name that is already in use by another VM in the project.
VM names must adhere to the resource naming conventions.
VM states:
- Stop the instance before
renaming it because you can only rename VMs that are in the
TERMINATED
state. You can't, for example, rename a VM that is in theSUSPENDED
state.
- Stop the instance before
renaming it because you can only rename VMs that are in the
Before you begin
- If you want to use the command-line examples in this guide, do the following:
- Install or update to the latest version of the Google Cloud CLI.
- 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 a VM, 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.
- SQL Server host names: If you rename a VM that hosts SQL Server, you must update the SQL server VM name. For more information, see Rename a computer that hosts a stand-alone instance of SQL Server.
Rename a VM
You must stop a VM before renaming it. If, after renaming, you receive an error message in the Google Cloud console, refresh your browser.
Console
In the Google Cloud console, go to the VM instances page.
In the Name column, click the name of the VM.
Click Stop
.Click Edit
.In Basic information > Rename > VM instance name, enter a new name for the VM.
Click Save.
Click Start / Resume
.
gcloud
Stop the VM by using the
gcloud compute instances stop
command.Rename the VM 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
Start the VM by using the
gcloud compute instances start
command.
API
Stop the VM by using the
instances.stop
method.Rename the VM by using the
instances.setName
method:POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME/setName { currentName: "INSTANCE_NAME", name: "NEW_INSTANCE_NAME" }
Replace the following:
PROJECT_ID
: ID of the project containing the VM to renameZONE
: zone containing the VM to renameINSTANCE_NAME
: VM to renameNEW_INSTANCE_NAME
: new name for the VM
Get the status of the renaming by polling 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.After renaming, start the VM by using the
instances.start
method.