When you create a virtual machine (VM) instance, Google Cloud creates an internal DNS name from the VM name. Unless you specify a custom hostname, Google Cloud uses the automatically created internal DNS name as the hostname it provides to the VM.
You can create a VM with a custom hostname by specifying any fully qualified DNS name. Custom hostnames are useful to maintain conventions or to support requirements for applications that expect a particular hostname.
Even when you specify a custom hostname, Google Cloud still creates the Compute Engine internal DNS name. You can still contact your VM by using this automatically created DNS record.
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.
Limitations
You must manually configure the DNS record for your custom hostname. Custom hostnames are not resolved by the automatically created records provided by Compute Engine internal DNS. You can use any of the following to host the DNS record for the custom hostname:
any other public DNS name server
You cannot change a custom hostname after you have created the VM.
Naming convention
Custom hostnames must conform to RFC 1035 requirements for valid hostnames. To meet these requirements, custom hostnames must meet the following format specifications:
- Contain at least two labels described as follows:
- Each label matching the regular expression
[a-z]([-a-z0-9]*[a-z0-9])?
- Each label is concatenated with a dot
- Each label can be 1-63 characters long
- Each label matching the regular expression
- The entire hostname must not exceed 253 characters
Not valid — contains a single label
my-host1234
Valid — contains three labels, each concatenated with a dot
my-host1234.example.com
Create a VM with a custom hostname
Console
In the Google Cloud Console, go to the VM instances page.
Select your project and click Continue.
Click Create instance.
Specify a Name for your VM. See Resource naming convention.
Expand the Management, security, disks, networking, sole tenancy section.
- Click Networking.
- Under Hostname, specify the custom hostname.
Make additional VM customizations as needed.
Click the Create button to create and start the VM.
Next step: Configure your DNS records. For more information, see Managing records.
gcloud
Using the gcloud
command-line tool, follow the instructions to
create an instance from an image
or a
snapshot,
add the --hostname
flag, and use the
gcloud compute instances create
command as follows:
gcloud compute instances create VM_NAME \ --hostname=HOST_NAME
Replace the following:
VM_NAME
: the name of the VMHOST_NAME
: the fully qualified domain hostname that you want to assign
For example, to create a VM myinstance
with the custom
hostname test.example.com
. You can run the following command:
gcloud compute instances create myinstance \ --hostname=test.example.com
Next step: Configure your DNS records. For more information, see Managing records.
API
Follow the API instructions to
create an instance from an image
or a
snapshot,
and specify the hostname
field in the request body.
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances { "name": "VM_NAME", "hostname": "HOST_NAME", ... }
Replace the following:
PROJECT_ID
: your project IDVM_NAME
: the name of the VMHOST_NAME
: the fully qualified domain hostname that you want to assignZONE
: the zone where you want to create the VM
Next step: Configure your DNS records. For more information, see Managing records.
Verifying the custom hostname
For Linux VMs, you can verify the hostname by running the
hostname -f
command on the VM.
You can also verify the custom hostname by using the Google Cloud Console or the
gcloud
command-line tool.
Console
To view the custom hostname for your VM, go to the VM instances page.
Click the instance name to open the VM instance details page.
Review the Hostname section. The Hostname field only displays if a custom hostname is set.
gcloud
To view the custom hostname for your VM
using gcloud compute
, use the
instances describe
sub-command with a --format
flag to filter the output. Replace
VM_NAME
with the name of the VM.
gcloud compute instances describe VM_NAME \ --format='get(hostname)'
For example, to view the custom hostname for a VM named
myinstance
, run the following command.
gcloud compute instances describe myinstance \ --format='get(hostname)'
The output might resemble the following:
test.example.com
If a custom hostname is not set, the output for this command is blank.