Creating a VM instance with a custom hostname

When you create a VM instance, Google Cloud creates an internal DNS name from the instance 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.

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:

  • a Cloud DNS public or private zone

  • any other public DNS name server

• You cannot change a custom hostname after you have created the VM.

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

Requirements

The hostname must conform to RFC 1035 requirements for valid hostnames. To meet this requirement, hostnames must contain a series of labels matching the regular expression [a-z]([-a-z0-9]*[a-z0-9])?, and each label is concatenated with a dot. Each label can be 1-63 characters long, and the entire sequence must not exceed 253 characters.

Permissions required for this task

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

• compute.instances.create on the project
• compute.instances.updateShieldedVmConfig if you plan to create a Shielded VM instance and you want to be able to change any of the Shielded VM settings.
• compute.networks.use on the project if using a legacy network
• compute.subnetworks.use either on the whole project or on the chosen subnet (VPC networks)
• compute.networks.useExternalIp on the project if you need to assign an external IP address (either ephemeral or static) to the instance using a legacy network
• compute.subnetworks.useExternalIp either on the whole project or on the chosen subnet if you need to assign an external IP address (either ephemeral or static) to the instance using a VPC network
• compute.address.use on the project if specifying a static address in the project
• compute.instances.setMetadata if setting metadata
• compute.instances.setTags on the instance if setting tags
• compute.instances.setLabels on the instance if setting labels
• compute.images.useReadOnly on the image if creating a new root persistent disk
• compute.disks.create on the project if creating a new root persistent disk with this instance
• compute.disks.useReadOnly on the disk if attaching an existing persistent disk in read-only mode
• compute.disks.use on the disk if attaching an existing disk in read-write mode
• compute.disks.setLabels on the disk if setting labels
• compute.snapshots.create on the project to create a new snapshot if creating an instance from a snapshot
• compute.snapshots.use on the snapshot if creating an instance from a snapshot

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.

Create a VM with a custom hostname

Console

1. In the Google Cloud Console, go to the Create instance page.

   Go to the Create instance page

2. Expand the Management, security, disks, networking, sole tenancy section.
3. Under Hostname in the Networking tab, set the custom hostname.
4. Continue with the rest of the instance creation process.

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 instance-name \
    --hostname=hostname

Replace the following:

• instance-name: The name of the instance.
• hostname: The fully qualified domain hostname that you want to assign.

For example, to create an instance called myinstance with the custom hostname test.example.com. You can run the following command:

gcloud compute instances create myinstance \
    --hostname=test.example.com

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": "instance-name",
 "hostname": "hostname",
 ...
}

Replace the following:

• project-id: Your Project ID.
• instance-name: The name of the instance.
• hostname: The fully qualified domain hostname that you want to assign.
• zone: The zone where you want to create the instance.

Verifying the custom hostname

For Linux VM instances, you can verify the hostname by running the hostname -f command on the VM instance.

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 instance, go to the VM instances page.

   Go to the VM instances page

2. Click the instance name to open the VM instance details page.
3. Review the Hostname section. The Hostname field only displays if a custom hostname is set.

   

gcloud

To view the custom hostname for your instance using gcloud compute, use the instances describe sub-command with a --format flag to filter the output. Replace instance-name with the name of the instance.

gcloud compute instances describe instance-name \
    --format='get(hostname)'

For example, to view the custom hostname for an instance 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

• Connect to your instance.