Internal DNS

Linux Windows

---

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

For example, when you delete a VM, Google Cloud automatically removes the associated A and PTR records for its .internal DNS name. If you then create a VM 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 only resolves to its primary internal IP address. Internal DNS names cannot be used to connect to the external IP addresses of a VM.

• 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 names must be unique within each zone. But with zonal DNS you can reuse VM names across zones. For example, you can have several VMs named instance-1 as long as the VMs 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 names must be unique across the project. With global DNS, you cannot reuse VM 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 VM name must be unique across the project.
• ZONE: the zone where your instance is located.
• PROJECT_ID: the project to which the VM 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.

Note: Migrating a project to a different organization doesn't change the instance's default internal DNS type.

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 VMs. You can configure PTR records that let you override the default Internal DNS URL for your VM with the custom URL that 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.

Note: Internal DNS names are distinct from custom records created via Cloud DNS. Internal DNS records are automatically created and cannot be changed.

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 create a VM instance with a custom hostname.

Internal DNS names and Shared VPC

You can use an internal DNS name to refer to a VM'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.

Determine the internal DNS name for a VM

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.

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
• ZONE: the zone where the VM is located
• PROJECT_ID: the project to which the VM belongs

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

Important: Compute Engine instances receive internal DNS resolution information as part of their DHCP leases. On Linux, by default, the VM's metadata server (169.254.169.254) resolves internal DNS names. On Windows, by default, the subnet's default gateway resolves internal DNS names. If you change the name server configuration for your instance, you cannot resolve records in Compute Engine internal DNS (the .internal zone) or in Cloud DNS managed private zones, forwarding zones, and peering zones unless your replacement DNS server forwards these queries to the metadata server on Linux or the default gateway on Windows.

The following example uses ping to contact a VM 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
• ZONE: the zone where the VM is located
• PROJECT_ID: the project to which the VM belongs

Internal DNS and DHCP

Compute Engine VMs are configured to renew DHCP leases every 24 hours. For VMs that are enabled for zonal DNS, the DHCP lease expires every hour. VMs using zonal DNS have both zonal and global entries in the DHCP configuration file.

By default, most Linux distributions store DHCP information in resolv.conf. Manually editing resolv.conf results in it being reverted to the default DHCP every time the DHCP lease expires on your VM. To make static modifications in the resolv.conf file, several Linux distributions allow items to be prepended or appended to the DHCP policy.

How you modify the DHCP policy or configuration file depends on what distribution of Linux you use. For example, Red Hat Enterprise Linux and Debian use the /etc/dhcp/dhcpd.conf configuration file. On CentOS, you use the Network Manager command line utility, nmcli.

Refer to your operating system documentation for information about how to configure custom DHCP and DNS network settings.

Example resolv.conf file

By default, most Linux distributions store DHCP information in resolv.conf. systemd-resolved also provides resolver services for DNS. You can configure this resolver by editing the /etc/systemd/resolved.conf file and other *.conf files in /etc/systemd/resolved.conf.d/. On Linux distributions that store DHCP information in resolved.conf, you can view zonal and global DNS entries in the /etc/systemd/resolved.conf file.

Note: When you view the resolv.conf file, make sure that the file is refreshed to the latest version. To do this, you might need to refresh the DHCP lease or restart the network stack, depending on the operating system that your VM uses.

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 6^th entry are not applied by your OS. This can cause Compute Engine functionality to stop working, such as accessing VMs 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 VM. On VMs 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.

Zonal DNS config

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 VM is located
• PROJECT_ID: the project to which the VM 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 config

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 VM 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

Example dhclient.conf file

Sample /etc/dhcp/dhclient.conf file:

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

In this example, 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.

Configure DNS names for your project or VMs

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

Note: Setting the VmDnsSetting metadata value at the project level affects VMs on other Google Cloud services such as Google Kubernetes Engine, App Engine flexible environment, Cloud SQL, Dataproc, and containers running on Compute Engine. Update your apps to use zonal DNS names for those services in addition to your Compute Engine VMs.

The VmDnsSetting variable supports the following settings:

• Recommended: Set VmDnsSetting=ZonalOnly to have your VMs be addressable only by their zonal DNS names. The VMs still retain both the zonal and global search paths, but their global DNS names no longer function. Other VMs can address VMs with this setting using only their zonal DNS names and can't address these VMs 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 VMs in standalone projects and projects created in an organization that enabled the Compute Engine API after September 6, 2018.
• Set VmDnsSetting=GlobalDefault so that VMs 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 VMs 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 VM metadata values, see Setting custom metadata.

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

• Linux VMs: sudo dhclient -v -r
• Windows Server VMs: 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 and start 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.

Switch existing projects to zonal DNS names

Note: Enabling zonal DNS names across your entire project applies zonal DNS settings to VMs in the following services: App Engine flexible environment, Google Kubernetes Engine, Cloud SQL, Dataproc, Dataflow, and Cloud Functions. Make sure your apps can resolve compatibility issues with zonal-only settings.

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:

Note: If a VM running Linux or Unix already has 6 domains in the search path (run cat /etc/resolv.conf), make sure the VM is running with glibc version 2.26 or greater (one way to check glibc version is to run ldd --version). DHCP clients with glibc 2.25 and older only support up to 6 search domains, so there might be a risk of discarding an existing search domain.

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

Revert to global DNS on your project or VMs

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

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

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

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