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
-
If you haven't already, then set up authentication.
Authentication is
the process by which your identity is verified for access to Google Cloud services and APIs.
To run code or samples from a local development environment, you can authenticate to
Compute Engine by selecting one of the following options:
Select the tab for how you plan to use the samples on this page:
Console
When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
-
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
- Set a default region and zone.
Terraform
To use the Terraform samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment.
Go
To use the Go samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment.
Java
To use the Java samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment.
Node.js
To use the Node.js samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment.
Python
To use the Python samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment.
REST
To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.
-
Required roles
To get the permissions that you need to create VM with a custom hostname,
ask your administrator to grant you the
Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1
) IAM role on the project.
For more information about granting roles, see Manage access to projects, folders, and organizations.
This predefined role contains the permissions required to create VM with a custom hostname. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to create VM with a custom hostname:
-
compute.instances.create
on the project -
To use a custom image to create the VM:
compute.images.useReadOnly
on the image -
To use a snapshot to create the VM:
compute.snapshots.useReadOnly
on the snapshot -
To use an instance template to create the VM:
compute.instanceTemplates.useReadOnly
on the instance template -
To assign a legacy network to the VM:
compute.networks.use
on the project -
To specify a static IP address for the VM:
compute.addresses.use
on the project -
To assign an external IP address to the VM when using a legacy network:
compute.networks.useExternalIp
on the project -
To specify a subnet for your VM:
compute.subnetworks.use
on the project or on the chosen subnet -
To assign an external IP address to the VM when using a VPC network:
compute.subnetworks.useExternalIp
on the project or on the chosen subnet -
To set VM instance metadata for the VM:
compute.instances.setMetadata
on the project -
To set tags for the VM:
compute.instances.setTags
on the VM -
To set labels for the VM:
compute.instances.setLabels
on the VM -
To set a service account for the VM to use:
compute.instances.setServiceAccount
on the VM -
To create a new disk for the VM:
compute.disks.create
on the project -
To attach an existing disk in read-only or read-write mode:
compute.disks.use
on the disk -
To attach an existing disk in read-only mode:
compute.disks.useReadOnly
on the disk
You might also be able to get these permissions with custom roles or other predefined roles.
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.
Supported operating systems
Custom hostnames are set in the guest environment using hook scripts which integrate with the guest networking software. Linux operating systems that don't have a script to integrate with the guest network software might not have the correct hostname.
For the full list of operating system versions that support custom hostnames, check the guest environment support in Operating system details.
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.
- Each label contains regular expressions that includes only these characters:
- 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
In the Google Cloud console, go to the Create an instance page.
Specify a Name for your VM. For more information, see Resource naming convention.
Expand the Advanced options section, and then do the following:
- Expand the Networking section.
- In the Hostname field, specify the custom hostname.
Make additional VM customizations, as needed.
To create and start the VM, click Create.
Next step: Configure your DNS records. For more information, see Managing records.
gcloud
Using the Google Cloud CLI, 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
, 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.
Terraform
You can use a Terraform
resource
to create an instance with a custom hostname by using the hostname
argument.
- In the Google Cloud console, go to the VM instances page.
- Click Create instance.
- Specify the parameters you want.
- At the top or bottom of the page, click Equivalent code, and then click the Terraform tab to view the Terraform code.
Next step: Configure your DNS records. For more information, see Managing records.
Go
Java
Node.js
Python
REST
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:
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 Google Cloud CLI.
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 is visible only 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.