Creating a VM instance with a custom hostname


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 creates the Compute Engine internal DNS name. You can connect to your VM by using this automatically created internal DNS record. The internal DNS record resolves to the internal DNS name and not the custom hostname. With custom hostnames, you still need to create a corresponding DNS record in the appropriate zone, for example, by using Cloud DNS.

Before you begin

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:

  • 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:

  • The hostname contains at least two labels described as follows:
    • Each label contains regular expressions that includes only these characters: [a-z]([-a-z0-9]*[a-z0-9])?.
    • Labels are concatenated with a dot.
    • Each label is 1-63 characters long.
  • The hostname does not exceed 253 characters.

Not valid: contains a single label

my-host1234

Valid: contains three labels concatenated with dots

my-host1234.example.com

Create a VM with a custom hostname

Console

  1. In the Google Cloud Console, go to the VM instances page.

    Go to VM instances

  2. Select your project and click Continue.

  3. Click Create instance.

  4. Specify a Name for your VM. See Resource naming convention.

  5. Expand the Management, security, disks, networking, sole tenancy section.

    1. Click Networking.
    2. Under Hostname, specify the custom hostname.

      Set hostname.

  6. Make additional VM customizations, as needed.

  7. Click Create 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 VM
  • HOST_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, 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 ID
  • ZONE: the zone where you want to create the VM
  • VM_NAME: the name of the VM
  • HOST_NAME: the fully qualified domain hostname that you want to assign

Next step: Configure your DNS records. For more information, see Managing records.

Verify 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

  1. To view the custom hostname for your VM, go to the VM instances page.

    Go to VM instances

  2. Click the instance name to open the VM instance details page.

  3. Review the Hostname section. The Hostname field is visible only if a custom hostname is set.

    VM instances page showing the hostname.

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.

What's next