Internal DNS

Virtual Private Cloud networks on GCP have an internal DNS service that allows instances in the same network to access each other by using internal DNS names. Internal DNS records are created in a .internal zone. As you manage your VM instances, GCP automatically creates, updates, and removes the internal DNS records.

For example, if you delete a VM instance, GCP automatically removes the instance's internal DNS record. If you create a new instance with the same name, GCP creates a new record for the replacement instance.

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 other VMs that are in the same project and VPC network. You cannot use internal DNS to contact instances that are in other VPC networks, even if they are in the same project.

  • You cannot customize the fully qualified domain name syntax for an internal DNS name.

Types of internal DNS names

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

Internal DNS type Fully qualified domain name (FQDN) Project's default type
Zonal DNS [INSTANCE_NAME].[ZONE].c.[PROJECT_ID].internal Default for all organizations or standalone projects that have enabled the Compute Engine API after September 06, 2018.
Global (project wide) DNS [INSTANCE_NAME].c.[PROJECT_ID].internal Default for all organizations or standalone projects that have enabled the Compute Engine API before September 06, 2018.

where:

  • [INSTANCE_NAME] is the name of the instance.
  • [ZONE] is the zone where your instance is located.
  • [PROJECT_ID] is the project to which the instance belongs.

You can control which type of internal DNS name is used at the project or instance level. See configuring DNS names for your project or instances.

Determining internal DNS name for a VM

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

  1. Connect to the instance.
  2. View the hostname from instance metadata:

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

The format of the hostname indicates the type of internal DNS name the VM uses.

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 [INSTANCE_NAME].[ZONE].c.[PROJECT_ID].internal -c 1

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

where:

  • [INSTANCE_NAME] is the name of the instance.
  • [ZONE] is the zone where the instance is located.
  • [PROJECT_ID] is 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 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.

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 name of the instance.
  • [ZONE] is the zone where your instance is located.
  • [PROJECT_ID] is the project to which the instance 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

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 name of the instance.
  • [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 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 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 are encouraged to migrate to zonal DNS names.

Configuring DNS names for your project or instances

Enable zonal DNS and/or global 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. This is the default setting for instances in standalone projects and projects created in an organization that enable the Compute Engine API after September 06, 2018. Note that, if a project is migrated to an organization, the default DNS name for that project will not change.
  • 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. This is the default setting for instances in standalone projects and projects created in an organization that enabled the Compute Engine API before September 06, 2018. Note that, if a project is migrated to an organization, the default DNS name for that project will not change.

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

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

Migrating existing applications to zonal DNS names

Although your existing projects can continue to use global DNS names, you are encouraged to 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 ensure that 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