Internal DNS

Google Cloud Platform (GCP) Virtual Private Cloud (VPC) networks have an internal DNS service that allows you to address instances by their DNS names rather than their internal IP addresses. If you delete and recreate an instance, the internal IP address can change. This change can disrupt connections from other Compute Engine resources, which must obtain the new IP address before they can connect again. The DNS name always points to a specific instance no matter what the internal IP address is.

Each instance has a metadata server that also acts as a DNS resolver for that instance. The metadata server handles all DNS queries for local network resources, and routes all other queries to Google's public DNS servers for public name resolution.

An instance is not aware of any external IP address assigned to it. Instead, the network stores a lookup table that matches external IP addresses with the internal IP addresses of the relevant instances.

Instance fully qualified domain names

An internal fully qualified domain name (FQDN) for an instance has the following formats:

  • Instances using the default global DNS: [HOST_NAME].c.[PROJECT_ID].internal
  • Instances enabled for Zonal DNS: [HOST_NAME].[ZONE].c.[PROJECT_ID].internal

You can address instances over the internal VPC network using this FQDN. For example, if your instances are enabled for Zonal DNS, you can ping from one instance to another instance over the internal VPC network using the zonal fully qualified domain name:

$ ping example-instance.us-west1-c.c.example-project.internal -c 1

PING example-instance.us-west1-c.c.example-project.internal (10.240.0.17) 56(84) bytes of data.
64 bytes from example-instance.us-west1-c.c.example-project.internal (10.240.0.17): icmp_seq=1 ttl=64 time=0.136 ms

Compute Engine instances receive internal DNS resolution information as part of their DHCP leases. You can use any DNS resolver on your instances, as long as it supports the Local Subnet Routes feature documented in RFC3442.

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 enabled for zonal DNS, the DHCP lease expires every hour. DHCP renewal overwrites this file, undoing any changes that you might have made. Instances enabled for Zonal DNS have both zonal and global entries in the resolv.conf file.

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

where [PROJECT_ID] is 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 "[INSTANCE_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;
}

where:

  • [INSTANCE_NAME] is the hostname of the instance. Typically, this value is the same as the instance name.
  • [PROJECT_ID] is the project to which the instance belongs.

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

where:

  • [ZONE] is the zone where your instance is located.
  • [PROJECT_ID] is 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 "[INSTANCE_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;
}

where:

  • [INSTANCE_NAME] is the hostname of the instance. Typically, this value is the same as the instance name.
  • [ZONE] is the zone where your instance is located.
  • [PROJECT_ID] is the project to which the instance 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 will not be 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 will result in it being reverted to the default DHCP every time the 24-hour DHCP lease expires on your instance. On instances enabled for 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 instance, the zone where your instance is located, and the project that owns the instance. Global DNS names do not include the zone where the instance is located. Zonal DNS names in one location function independently of other locations, allowing you to build more fault-tolerant multi-region applications with better availability characteristics.

Existing projects and organizations can continue to use global DNS names, but have the option to enable zonal DNS names.

Configuring zonal DNS on your project or instances

Enable zonal DNS search paths on 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.

  • 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 cannot address these instances using their global DNS names or search paths. This is the preferred option as long as your applications can support it.
  • Set VmDnsSetting=ZonalPreferred to enable zonal DNS search paths while still retaining the global DNS name. Instances with this setting can address each other using either zonal or global DNS names and can continue to address instances configured only for global DNS names.
  • Set VmDnsSetting=GlobalOnly so that instances use only global names as domain names and search path entries. Use this value to exclude instances from a project-wide zonal DNS setting, or to restore your instances to use only global DNS names.

Read Setting Custom metadata to learn how to set project metadata or instance metadata values.

After you configure an instance for zonal DNS names, 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

Migrating existing applications to zonal DNS names

Although your existing projects can continue to use global DNS names, you can migrate your existing instances and applications to use zonal DNS names and gain the benefits of the zonal DNS system. In general, you can use the following migration process:

  1. Check your applications and update them to resolve compatibility issues with zonal-only settings:
    • Applications that address instances by the instance name or global fully-qualified domain names: Instance names and global instance names will not always resolve in a zonal-only environment. Update these names to use zonal fully-qualified domain names as a best practice.
    • Applications that assume a specific global fully qualified domain name format: Assuming a domain name format usually represents a fundamental issue in application design. Google recommends that you design your applications to function independently of the domain name format.
    • Applications that do not expect domain name changes: Some applications might not expect domain name changes, and require a complete restart in order to pick up the new names. If possible, update your applications to identify and handle changes in your instance's domain name.
  2. Configure instances on your internal VPC network to use the VmDnsSetting=ZonalPreferred setting, which uses both global and zonal DNS names. This transition phase allows instances to continue using global names until your applications are ready to use only zonal names:
    1. Enable VmDnsSetting=ZonalPreferred on one instance by setting that value in custom metadata.
    2. Refresh the DHCP lease on that instance so that it starts using zonal DNS names:
      • Linux instances: sudo dhclient -v -r
      • Windows Server instances: ipconfig /renew
    3. Test the applications on that instance to make sure they function as expected. Some applications might not expect domain name changes, and can require a complete restart in order to pick up the new names.
    4. Repeat this process to enable VmDnsSetting=ZonalPreferred and refresh the DHCP lease on the remaining instances in your VPC network until they all operate as expected using only the zonal DNS names. Alternatively, you can set VmDnsSetting=ZonalPreferred in project metadata to configure every instance in your project to use zonal DNS names.
  3. After your applications run properly using only zonal domain names with the VmDnsSetting=ZonalPreferred setting, you can disable global names on that VPC network. Configure instances on your internal VPC network to use the
    VmDnsSetting=ZonalOnly setting, which uses only the zonal DNS names:
    1. Enable VmDnsSetting=ZonalOnly on one instance by setting that value in custom metadata.
    2. Refresh the DHCP lease on that instance so that it starts using zonal DNS names:
      • Linux instances: sudo dhclient -v -r
      • Windows Server instances: ipconfig /renew
    3. Test the applications on that instance to make sure they function as expected.
    4. Repeat this process to enable VmDnsSetting=ZonalOnly and refresh the DHCP lease on the remaining instances in your VPC network until they all operate as expected using only the zonal DNS names.
  4. Repeat this process across each of your VPC networks until all of the instances in your project use the VmDnsSetting=ZonalOnly setting. You can set VmDnsSetting=ZonalOnly in project-level metadata so that it applies automatically to any instances you create in that project. Alternatively, you can set VmDnsSetting=ZonalOnly in project metadata to configure every instance in your project to use zonal DNS names.

Disabling zonal DNS on your project or instances

To disable zonal DNS on a specific instance, set VmDnsSetting=GlobalOnly in that instance's metadata. To disable zonal DNS across a project, set VmDnsSetting=GlobalOnly in project metadata and ensure that none of your instances are configured individually with the VmDnsSetting value. Read Setting Custom metadata to learn how to set project metadata or instance metadata values.

If you need to force the DHCP lease to refresh immediately, you can use one of the following commands:

  • Container-optimized OS (Google Kubernetes Engine): sudo systemctl restart systemd-networkd
  • Debian/Google App Engine Flex instances: sudo dhclient -r -v eth0 && sudo rm /var/lib/dhcp/dhclient.* ; sudo dhclient -v eth0
  • Ubuntu 15.04 and above: sudo dhclient -r -v ens4 && sudo rm /var/lib/dhcp/dhclient.* ; sudo dhclient -v ens4
  • Ubuntu older than 15.04: sudo dhclient -r -v eth0 && sudo rm /var/lib/dhcp/dhclient.* ; sudo dhclient -v eth0
  • Windows: ipconfig /renew

Some operating systems do not fully change their DNS configurations even after the DHCP lease renews. In those cases, restart the network of the VM instance to force the DNS configuration change:

  • Ubuntu: sudo ifdown --exclude=lo -a && sudo ifup --exclude=lo -a
  • CentOS: sudo /etc/init.d/network restart
  • CoreOS: sudo systemctl restart systemd-networkd
  • Container-optimized OS: sudo systemctl restart systemd-networkd

If you run your application in containers, on 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 applications, you must set VmDnsSetting=GlobalOnly on your projects and instances and restart the containers so that their DNS settings to revert back to the original state.

What's next

  • See the VPC Overview for information on GCP VPC networks.
  • See Using VPC for instructions on creating and modifying VPC networks.
Was this page helpful? Let us know how we did:

Send feedback about...

Compute Engine Documentation