Internal DNS

Stay organized with collections Save and categorize content based on your preferences.

Virtual Private Cloud networks on Google Cloud have an internal DNS service that lets instances in the same network access each other by using internal DNS names. Internal A records for virtual machine (VM) instances are created in a DNS zone for .internal. PTR records for VM instances are created in corresponding reverse zones. As you manage your instances, Google Cloud automatically creates, updates, and removes these DNS records.

For example, when you delete an instance, Google Cloud automatically removes the associated A and PTR records for its .internal DNS name. If you then create an instance with the same name, Google Cloud creates a record for the replacement.

About internal DNS

Internal DNS names have the following specifications:

  • The internal DNS name of a VM instance only resolves to its primary internal IP address. Internal DNS names cannot be used to connect to the external IP addresses of an instance.

  • Internal DNS names cannot be configured to resolve to secondary Alias IPs.

  • Internal DNS names can only be resolved from VMs that are in the same network. These VMs can be in the same project as the network, or can be in service projects using the same Shared VPC network. To resolve DNS names of VMs in service projects, you must use the FQDNs of the VMs. You cannot use internal DNS to contact VMs that are in a different network.

Types of internal DNS names

Google Cloud has two types of internal DNS names. The default internal DNS type is set based on when you enabled the Compute Engine API.

In general, Google strongly recommends using zonal DNS because it offers higher reliability guarantees by isolating failures in the DNS registration to individual zones.

Internal DNS type Fully qualified domain name (FQDN) Project's default type Notes
Zonal DNS VM_NAME.ZONE.c.PROJECT_ID.internal Default for all organizations or standalone projects that have enabled the Compute Engine API after September 06, 2018. VM instance names must be unique within each zone. But with zonal DNS you can reuse VM instance names across zones. For example, you can have several instances named instance-1 as long as the instances are in different zones.
Global (project wide) DNS VM_NAME.c.PROJECT_ID.internal Default for all organizations or standalone projects that have enabled the Compute Engine API before September 6, 2018. VM instance names must be unique across the project. With global DNS, you cannot reuse VM instance names within the project.

Replace the following:

  • VM_NAME: the name of the VM For zonal DNS, this value must be unique within the zone but can be repeated across zones. For global DNS, the instance name must be unique across the project.
  • ZONE: the zone where your instance is located
  • PROJECT_ID: the project to which the instance belongs

For information about how to control which type of internal DNS name is used at the project or instance level, see configuring DNS names for your project or instances.

PTR records and internal DNS

Google Cloud's internal DNS service automatically creates PTR records for VMs in the following reverse zones:

  • 10.in-addr.arpa.
  • 168.192.in-addr.arpa.
  • 16.172.in-addr.arpa., 17.172.in-addr.arpa., ... through 31.172.in-addr.arpa.

Custom records with Cloud DNS

You can use a Cloud DNS private zone to create custom DNS entries for your VM instances. You can configure PTR records that let you override the default Internal DNS VM URL with the custom URL you provide.

To create custom PTR records that override the automatically created internal DNS PTR names, see PTR records for RFC 1918 addresses in private zones.

Custom hostnames

You can specify a custom hostname for a VM when you create it. Custom hostnames assigned in this way are not resolved by internal DNS. With custom hostnames, you still need to create a corresponding DNS record in the appropriate zone (for example, using Cloud DNS). For more information, see creating a VM instance with a custom hostname.

Internal DNS names and Shared VPC

You can use an internal DNS name to refer to an instance's internal IP address even when that IP address is located in a Shared VPC network in a host project. With Shared VPC, the project ID portion of either the zonal or a global (project wide) internal DNS name is the ID of the service project.

Determining the internal DNS name for a VM instance

Use the following procedure to read the internal DNS name assigned to a VM instance. The source of truth for an internal DNS name is its metadata server.

  1. Connect to the VM instance.
  2. Query the hostname metadata:

    Linux VMs

    curl "http://metadata.google.internal/computeMetadata/v1/instance/hostname" \
      -H "Metadata-Flavor: Google"
    

    Windows VMs

    Invoke-RestMethod `
      -Headers @{"Metadata-Flavor" = "Google"} `
      -Uri "http://metadata.google.internal/computeMetadata/v1/instance/hostname"
    

The metadata server returns the VM's hostname in one of the following formats and it shows the type of internal DNS name the VM uses:

  • Zonal DNS: VM_NAME.ZONE.c.PROJECT_ID.internal
  • Global DNS: VM_NAME.c.PROJECT_ID.internal

In the output:

  • VM_NAME: the name of the VM instance
  • ZONE: the zone where the instance is located
  • PROJECT_ID: the project to which the instance belongs

Accessing VMs by internal DNS

The metadata server is also the name server resolver for DNS queries issued by the VM. The metadata server resolves all DNS queries, both to internal DNS names and to external DNS names. For external DNS queries, the metadata server passes requests to Google's public name servers.

The following example uses ping to contact an instance that uses zonal DNS. This method works, provided that you have created a firewall rule that allows incoming ICMP traffic to the instance.

$ ping VM_NAME.ZONE.c.PROJECT_ID.internal -c 1

PING VM_NAME.ZONE.c.PROJECT_ID.internal (10.240.0.17) 56(84) bytes of data.
64 bytes from VM_NAME.ZONE.c.PROJECT_ID.internal (10.240.0.17): icmp_seq=1 ttl=64 time=0.136 ms

Replace the following:

  • VM_NAME: the name of the VM instance
  • ZONE: the zone where the instance is located
  • PROJECT_ID: the project to which the instance belongs

Internal DNS and resolv.conf

By default, most Linux distributions store DHCP information in resolv.conf. Compute Engine instances are configured to renew DHCP leases every 24 hours. For instances that are enabled for zonal DNS, the DHCP lease expires every hour. DHCP renewal overwrites this file, undoing any changes that you might have made. Instances using zonal DNS have both zonal and global entries in the resolv.conf file.

On Linux distributions that store DHCP information in systemd.resolved.conf, you can view zonal and global DNS entries in the /etc/systemd/resolved.conf file.

Note: VPC networks have a default maximum transmission unit (MTU) of 1460 bytes. However, the network MTU can be set to the standard Ethernet MTU of 1500 bytes, up to 8896 bytes for jumbo frames, or as low as 1300. For more information about network MTUs, see the maximum transmission unit overview.

Zonal DNS

Sample zonal resolv.conf file:

# Local domain name. Computed from your project name.
domain ZONE.c.PROJECT_ID.internal
# Search list for hostname lookup. Starting with entries that represent
# your project and ending with google.internal to facilitate metadata server requests.
search ZONE.c.PROJECT_ID.internal. c.PROJECT_ID.internal. google.internal.
# Address of the DNS server to resolve project specific, and global domain names.
nameserver 169.254.169.254

Replace the following:

  • ZONE: the zone where your instance is located
  • PROJECT_ID: the project to which the instance belongs

Sample zonal dhcp.lease file:

lease {
  # What interface we are using for the network
  interface "eth0";
  fixed-address 10.128.0.9;
  option subnet-mask 255.255.255.255;
  option routers 10.128.0.1;
  # Lease timeout, older VM instances will have this value set to infinite.
  option dhcp-lease-time 3600;
  option dhcp-message-type 5;
  option domain-name-servers 169.254.169.254;
  option dhcp-server-identifier 169.254.169.254;
  option interface-mtu 1460;
  # Search path options that are copied into the resolv.conf
  option domain-search "ZONE.c.PROJECT_ID.internal.", "c.PROJECT_ID.internal.", "google.internal.";
  option ntp-servers 169.254.169.254;
  option rfc3442-classless-static-routes 32,10,128,0,1,0,0,0,0,0,10,128,0,1;
  option host-name "VM_NAME.ZONE.c.PROJECT_ID.internal";
  option domain-name "ZONE.c.PROJECT_ID.internal";
  renew 4 2017/11/16 02:15:52;
  rebind 4 2017/11/16 02:43:59;
  expire 4 2017/11/16 02:51:29;
}

Replace the following:

  • VM_NAME: the name of the VM
  • ZONE: the zone where your VM is located
  • PROJECT_ID: the project to which the VM belongs

Global DNS

Sample global resolv.conf file:

# Local domain name. Computed from your project name.
domain c.PROJECT_ID.internal
# Search list for hostname lookup. Starting with entries that represent
# your project and ending with google.internal to facilitate metadata server requests.
search c.PROJECT_ID.internal google.internal.
# Address of the DNS server to resolve project specific, and global domain names.
nameserver 169.254.169.254

Replace PROJECT_ID with the project to which the instance belongs.

Sample global dhcp.lease file:

lease {
  # What interface we are using for the network
  interface "eth0";
  fixed-address 10.128.0.8;
  option subnet-mask 255.255.255.255;
  option routers 10.128.0.1;
  # Lease timeout, older VM instances will have this value set to infinite.
  option dhcp-lease-time 86400;
  option dhcp-message-type 5;
  option domain-name-servers 169.254.169.254;
  option dhcp-server-identifier 169.254.169.254;
  option interface-mtu 1460;
  # Search path options that are copied into the resolv.conf
  option domain-search "c.PROJECT_ID.internal.", "google.internal.";
  option ntp-servers 169.254.169.254;
  option rfc3442-classless-static-routes 32,10,128,0,1,0,0,0,0,0,10,128,0,1;
  option host-name "VM_NAME.c.PROJECT_ID.internal";
  option domain-name "c.PROJECT_ID.internal";
  renew 4 2017/11/16 12:07:00;
  rebind 4 2017/11/16 22:44:53;
  expire 5 2017/11/17 01:44:53;
}

Replace the following:

  • VM_NAME: the name of the VM
  • PROJECT_ID: the project to which the VM belongs

These files have the following restrictions:

  • The search path can handle only 6 records, and 3 of those records are provided by Compute Engine. If you add entries to the search path such that the total number of entries is greater than 6, search rules after the 6th entry are not applied by your OS. This can cause Compute Engine functionality to stop working, such as accessing instances via their instance names.
  • Manually editing resolv.conf results in it being reverted to the default DHCP every time the 24-hour DHCP lease expires on your instance. On instances using zonal DNS, the DHCP lease expires every hour. To make static modifications in the resolv.conf file, several Linux distributions allow items to be prepended or appended to the DHCP policy.

Debian 9

Sample /etc/dhcp/dhclient.conf file:

# Configuration file for /sbin/dhclient.
#
...
append domain-search "mydomain.com";
prepend domain-name-servers 172.16.1.1;

Where mydomain.com is the new search domain and 172.16.1.1 is the IP of your DNS server.

Zonal DNS names

Zonal DNS names include the name of your VM, the zone where your VM is located, and the project that owns the VM. Global DNS names do not include the zone where the VM is located. Zonal DNS names in one location function independently of other locations, letting you build more fault-tolerant multiregional apps with better availability characteristics.

Existing projects and organizations can continue to use global DNS names, but are encouraged to migrate to zonal DNS names for regional isolation and better multi-region reliability.

Configuring DNS names for your project or instances

Enable zonal DNS and global DNS for your instances by setting the VmDnsSetting variable in either project or instance metadata. If you set the VmDnsSetting variable on metadata for a specific instance, it overrides any VmDnsSetting variables inherited from project metadata for that instance.

The VmDnsSetting variable supports the following settings:

  • Recommended: Set VmDnsSetting=ZonalOnly to have your instances be addressable only by their zonal DNS names. The instances still retain both the zonal and global search paths, but their global DNS names no longer function. Other instances can address instances with this setting using only their zonal DNS names and can't address these instances using their global DNS names or search paths. This is the preferred and more reliable option as long as your apps can support it. This is the default setting for instances in standalone projects and projects created in an organization that enabled the Compute Engine API after September 6, 2018.
  • Set VmDnsSetting=GlobalDefault so that instances register both global and zonal DNS names, but use only global names as default domain names and search path entries. This is the default setting for instances in standalone projects and projects created in an organization that enabled the Compute Engine API before September 6, 2018.

Note that migrating a project to a different organization does not change the project's default DNS name.

For information about how to set project metadata or instance metadata values, see Setting custom metadata.

After you configure the VmDnsSetting variable for an instance, refresh the DHCP lease on the instance. You can refresh the lease by restarting the instance, waiting for the lease to expire, or by running one of the following commands:

  • Linux instances: sudo dhclient -v -r
  • Windows Server instances: ipconfig /renew

After refreshing the DHCP lease, check whether your VM is enabled for zonal DNS.

Enforce zonal DNS only by default to future/new projects

Compared to internal global DNS, internal zonal DNS offers higher reliability by isolating failures in the DNS registration to individual zones. Google strongly recommends switching to zonal DNS whenever possible.

If a new project is created under an organization that was created before September 6, 2018, by default the project's internal DNS type is still global DNS. To avoid the reliability risks related to global DNS, you can enforce the boolean organization policy constraints/compute.setNewProjectDefaultToZonalDNSOnly at an organization or folder level. When you set such a policy to override the default DNS setting, newly created projects use internal zonal DNS by default; but the policy does not impact existing projects where the Compute Engine API is already enabled. To switch existing projects to use zonal DNS, see switching existing projects to zonal DNS.

To enforce this policy change, you must have folder or organization level access with the IAM role roles/orgpolicy.policyAdmin.

Use the following steps to set the organization policy for a folder or organization:

  1. Sign in to the Google Cloud console as a Google Workspace or Cloud Identity super administrator.

  2. In the console, go to the Organization policies page.

    Go to Organization policies

  3. Select the folder or organization for which you want to view organization policies. A list of organization policy constraints that are available are displayed on one or more pages.

  4. To find the policy to enforce zonal DNS, click Filter and select Name, then set the filter name to Sets the internal DNS setting for new projects to Zonal DNS Only.

  5. Click the policy name to see its details.

  6. The policy details page provides information about the constraint and how the constraint is currently applied. By default, the enforcement is undefined for a folder or organization. However, if a parent folder has a defined enforcement, then the enforcement is inherited from the closest parent folder that has a defined enforcement. For more information, see Understanding hierarchy evaluation.

  7. To customize the organization policy, click Edit.

  8. In the edit page, select Customize.

  9. Under Enforcement, select an enforcement option:

    • To enforce the constraint, select On. For new projects, the default internal DNS type will be zonal DNS.
    • To disable the constraint, select Off. The default project DNS type is still determined by the organization creation time.
  10. Click Save.

To validate the organization policy change, you can create a new project under the folder or organization, then create a VM instance, and check whether your VM is enabled for zonal DNS.

If internal global DNS is needed to resolve a DNS name query built into your workload, you can rollback this change at the organization or folder level by disabling the enforcement.

Switching existing projects to zonal DNS names

Global DNS has been replaced by zonal DNS as the default internal DNS type for all new organizations onboarded to Google Cloud after September 6, 2018. If your existing projects are still using global DNS, Google strongly recommends that you switch these projects to use internal zonal DNS names. Zonal DNS mitigates the risk of cross-regional outages.

In general, you can use the following migration process:

  1. Check your apps and update them to resolve compatibility issues with zonal-only settings:
    • If you have any app that uses hard-coded internal global DNS names, fix them to use internal zonal DNS names.
    • If VM names are used to access instances in another zone, make sure the destination zone name is added in the query–for example: <DESTINATION_VM_NAME>.<DESTINATION_ZONE_NAME>.
    • To resolve DNS names of VMs in service projects using a shared VPC network, you must use the zonal fully qualified domain names of the VMs.
  2. To switch the project to use internal zonal DNS, set VmDnsSetting=ZonalOnly in project-level metadata

To test that the project metadata has been updated, you can run gcloud compute project-info describe --flatten="commonInstanceMetadata[VmDnsSetting]". The command should return ZonalOnly.

Reverting to global DNS on your project or instances

To revert to global DNS on a specific instance, add the following to the instance's metadata: VmDnsSetting=GlobalDefault.

To revert to global DNS for a project, add the following to the project's metadata: VmDnsSetting=GlobalDefault. And ensure that none of your instances are configured individually with the VmDnsSetting metadata value. For information about how to set project metadata or instance metadata values, see Setting custom metadata.

To force the DNS configuration change, restart the network of the VM instance:

  • Container-optimized OS/Ubuntu: sudo systemctl restart systemd-networkd
  • CentOS/RHEL/Fedora CoreOS/Rocky Linux: sudo systemctl restart network
  • Debian: sudo systemctl restart networking
  • Windows: ipconfig /renew

If you run your app in containers, on Google Kubernetes Engine, or on App Engine flexible environment, the DNS configuration in your container settings might not automatically update until you restart the containers. To disable zonal DNS on these container apps, you must set VmDnsSetting=GlobalDefault on your projects and instances and restart the containers so that their DNS settings revert to the original state.

What's next

  • For information about Google Cloud VPC networks, see the VPC overview.
  • For information about creating and modifying VPC networks, see Using VPC.