This document explains how to migrate an existing project from global DNS tozonal DNS. Zonal DNS enhances reliability by isolating outages within zones,preventing disruptions to essential services like instance creation andautohealing.

Before you begin

• If you haven't already, set upauthentication. Authentication verifies your identity 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

  1. Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:

     gcloudinit

     If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

     Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.
  2. Set a default region and zone.

  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. After installation,initialize the Google Cloud CLI by running the following command:

  gcloudinit

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.

  For more information, seeAuthenticate for using REST in the Google Cloud authentication documentation.

Required roles

To get the permissions that you need to migrate projects to use zonal DNS, ask your administrator to grant you the following IAM roles:

• Migrate a project to use zonal DNS:Project Editor (roles/resourcemanager.projectEditor) on the project
• Migrate VMs to zonal DNS within a project:Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1) on the project
• If your VM uses a service account:Service Account User (roles/iam.serviceAccountUser) on the service account or project

For more information about granting roles, seeManage access to projects, folders, and organizations.

These predefined roles contain the permissions required to migrate projects to use zonal DNS. To see the exact permissions that are required, expand theRequired permissions section:

You might also be able to get these permissions withcustom roles or otherpredefined roles.

Configure monitoring for DNS lookup failures

As a best practice,enable Cloud DNS query logsin your Compute Engine project before migrating to zonal DNS. You can usethe logs to monitor and compare internal DNS failure rates before and aftermigration to zonal internal DNS. Google recommends that you enable DNS querylogging at least 24 hours before the migration to establish a pre-migrationbaseline.

After you have collected enough data in the DNS query logs, you can performthe zonal DNS migration. You can monitor DNS resolution rates during themigration to ensure that the migration doesn't cause an increase in DNS queryfailures.

For information about the cost of DNS query monitoring, seePricing information for Cloud DNS query logging.

Migrate your project to zonal DNS

To migrate a project to use zonal DNS, complete the following tasks:

1. Check if your project uses global DNS by default
2. Determine the migration readiness of your projects by using query analysis
3. Migrate projects that are compatible with zonal DNS
4. Fix incompatible queries
5. Monitor global DNS logs to confirm migration readiness.
6. Migrate the remaining projects to zonal DNS
7. Check if a change to zonal DNS is impacting your project

Check if your project uses global DNS by default

Check your projects to see if they need to migrate from using global DNS tozonal DNS. You only need to migrate projects that are configured to use globalDNS as the default for any internal DNS names created within the project.

gcloud compute project-info describe --project=PROJECT_ID --flatten="vmDnsSetting"

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID?fields=id,name,vmDnsSetting

Use query analysis to determine the migration readiness of a project

To assess if a project can be migrated to zonal DNS without code changes oraltering how global DNS is used, Google Cloud analyzes your DNS query history.This analysis provides the following metrics that indicate project compatibilitywith zonal DNS:

• zonal_dns_ready (Compatible queries): This metric represents thetotal number of queries within a 100-day period that can be successfullyresolved using zonal DNS.

• zonal_dns_risky (Incompatible queries): This metric represents thetotal number of queries that can't be resolved using zonal DNS. Thesequeries typically involve cross-region communication or other scenarioswhere zonal resolution fails.Crucially, if this metric has a non-zerovalue, your project is not yet ready for migration. You must addressthese incompatible queries before switching to zonal DNS.

  Note: The query analysis metrics are updated every 24 hours and refreshedby 9 AM PST each day.

To view these metrics, use theMetrics Explorer in the Google Cloud console.

1. In the Google Cloud console, go to theleaderboard Metrics explorer page:

   Go toMetrics explorer

   If you use the search bar to find this page, then select the result whose subheading isMonitoring.

2. On the right side of the toolbar that contains theSelect a metricfield, clickCode editor,MQL, orPromQL.

3. If the query input field isn't titledPromQL Query, then forLanguage, selectPromQL.

4. In the query input field, enter the following text exactly as it appears:

   increase({"compute.googleapis.com/global_dns/request_count", monitored_resource="compute.googleapis.com/Location"}[1d])

5. Click theRun query button.

   Note: When theAuto-run toggle is enabled, theRun query buttonisn't displayed. Instead, the query runs automatically.

   The Google Cloud console displays a chart of the two metrics(zonal_dns_ready andzonal_dns_risky) and the corresponding number ofqueries made over the time period for each metric.

   

6. Check the value for thezonal_dns_risky metric.

   • If the value is0, then the project is ready for migration to zonalDNS. You can migrate the project, as described inMigrate projects that are ready to zonal DNS.
   • If the value is a non-zero number, such as0.02k as shown in theprevious screenshot, then there are some queries that might not workafter you migrate to zonal DNS. The project is not ready for migration.Continue with the steps inFix incompatible queries.

Migrate projects that are compatible with zonal DNS

Use any of the following options to migrate projects that are ready to switchto zonal DNS:

• Click theUse Zonal DNS button in the Google Cloud console.

  1. When you view theVM instances page for your project, if your projectis ready for migration (is compatible with zonal DNS queries), then thebanner includes a recommendation toUse Zonal DNS. This recommendationis based on internal DNS usage in the project, but is limited to thelast 30 days.

     

     If you click theUse Zonal DNS button, then the project metadata isupdated to use zonal DNS.

  2. Optional:View and query VM metadatato confirm the metadata change.

• Manually change the project metadata to use zonal DNS.

  1. Enable zonal DNS for your instances by setting thevmDnsSettingmetadata entry for the project. After you set this metadata entry, yourcompute instances can be accessed only by their zonal DNS names(VM_NAME.ZONE.c.PROJECT_ID.internal)when using search paths. The instances still retain both the zonal andglobal search paths, but their global DNS names, which don't include theZONE as part of the internal DNS name, no longerfunction. Only instances in the same region and same project can accesseach other using the global name when this setting is in place.

     Console

     1. To update the setting at the project level, in theGoogle Cloud console, go to the Compute EngineMetadata page.

        Go to the Custom metadata page

     2. ClickeditEdit.

     3. If a key with the valueVmDnsSetting exists, change its valuetoZonalOnly.

     4. If a key with the valueVmDnsSetting doesn't exist, then clickadd_boxAdd item.

        • In theKey field, enterVmDnsSetting.
        • In theValue field, enterZonalOnly.

     5. To finish modifying your custom metadata entries, clickSave.

     gcloud

     1. To update the metadata setting for the current project, use theproject-info add-metadata command.

        gcloud compute project-info add-metadata \    --metadata vmDnsSetting=ZonalOnly

     2. Optional: To verify the metadata settings for a project, usethe following command:

        gcloud compute project-info describe --project=PROJECT_ID --flatten="vmDnsSetting"

        ReplacePROJECT_ID with the name of theproject to query.

     REST

     Note: If usingcurl orInvoke-RestMethod to set projectmetadata, ensure that you add theContent-Type:application/jsonheader to the request.

     To update the metadata setting at the project level, constructaPOST request using theprojects.setCommonInstanceMetadata method.

     1. Optional: To perform optimistic locking, you can optionallyprovide afingerprint.

        A fingerprint is a random string of characters generated byCompute Engine. The fingerprint changes after eachrequest, and if you provide a mismatched fingerprint, yourrequest is rejected.

        If you don't provide a fingerprint, no check for consistency isperformed, and theprojects.setCommonInstanceMetadata requestsucceeds. If you use theinstances.setMetadata method, thena fingerprint is always required.

        To get the current fingerprint of a project, call theproject.get method.

        GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID

        The output is similar to the following:

        { "name": "myproject", "commonInstanceMetadata": { "kind": "compute#metadata", "fingerprint": "FikclA7UBC0=", ... }}

     2. Construct aPOST request to theprojects.setCommonInstanceMetadata methodto set the metadata key-value pair:

        POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/setCommonInstanceMetadata{"fingerprint": "FikclA7UBC0=","items": [  {  "key": "vmDnsSetting",  "value": "ZonalOnly"  }]}

        ReplacePROJECT_ID with your project ID.

  2. After you configure thevmDnsSetting metadata entry for your project,refresh the DHCP lease on each instance in that project. You canrefresh the lease by restarting the instance, or by waiting for thelease to expire, or by running one of the following commands:

     Linux instances

     sudodhclient-v-r

     Windows instances

     ipconfig/renew

  3. Check that your project uses zonal DNS.

1. Use the Logs Explorer to access and query the global DNS usage forcompute instances your project.

   Go to Logs Explorer

2. Select the project.

3. Apply the resource and log name filters:

   1. ClickResource.
   2. In theSelect resource dialog, selectVM Instance, and then clickApply.
   3. ClickLog name.

   4. In theSelect log names dialog, selectgdnsusage, and thenclickApply.

      Note: The Logs Explorer updates your global DNS usage logs onlyonce per day. For more up-to-date information about yourglobal DNS usage, follow the instructions explained inTrack global DNS usage within the project.

      Alternative query

      Alternatively, you can enter the following into thequery field:

       resource.type='gce_instance' log_name='projects/PROJECT_ID/logs/compute.googleapis.com/gdnsusage'

4. In theQuery results pane, each query has ajsonPayload field. EachjsonPayload field contains the following information:

   • The source VM name, its project ID, and zone name.
   • The destination VM name, its project ID, and zone name.

   • A debug message that provides information about how to update the globalDNS query that can't be resolved by using zonal DNS names. These areconsidered migration blocking queries that you should debug and fix.

     "To use Zonal DNS, update the Global DNS query sent from the source VMVM_NAME.c.PROJECT_ID.internal to the following zonalFQDN:VM_NAME.ZONE.c.PROJECT_ID.internal"

   • A query count that shows how many migration blocking queries the source VMsends to the destination VM for that day.

   The following screenshot shows thejsonPayload field information in theLogs Explorer console page.

   

   Note: Google Cloud can identify the compute instance the query originatesfrom, but it can't determine the specific application responsible.

5. Use the information in thejsonPayload that you obtained in the previousstep to determine what FQDN to use to manually update your global DNSqueries to use zonal DNS, and make the project ready for migration. The mostcommon use cases for where to update the FQDN and resolve compatibility areas follows:

   • Internal DNS names from the metadata server: No action is requiredbecause the returned DNS name will change to a zonal FQDN immediatelyafter the migration to zonal DNS. If the DNS name is cached, you justneed to make one more call to update the cache value.
   • Internal DNS names used to access VMs in another region: If you have anapplication that uses the internal DNS names for VMs in differentregions, you can modify the DHCP policy or configuration file toinclude the zone in the other region.
   • Hard-coded global FQDN: If you have an application that uses hard-codedglobal FQDN names for VMs, you can update the call within the applicationto use the internal DNS name or zonal FQDN instead. You can make thischange through a code change or configuration change in Terraform.
   • VMs in service projects that use a Shared VPC network: Toresolve DNS names of VMs in service projects that use aShared VPC network, you must use the zonal FQDNs of the VMs.

6. After you have updated the global DNS queries to use zonal DNS, dothe following:

   1. Use the Logs Explorer page to query the global DNS usage again.After you fix all blocking global DNS queries, there should be no debuglogs displayed in the query results.

   2. Recheck themonitoring metric to see if allincompatible DNS queries have been removed.

• Create dashboards: Visualize yourincompatible global DNS query patterns to gain insights into yourapplication's communication behavior.
• Aggregate logs: Analyze DNS logsacross your entire organization to identify broader trends and potentialareas for improvement.

Check if a change to zonal DNS is impacting your project

After migrating to zonal DNS, it's crucial to verify that your applications andservices are still working correctly. Since zonal DNS changes how internalDNS names are resolved, some applications might experience issues if they relyon global DNS names.

The following section describes how to check for potential impacts and how toresolve them:

1. Command-line instance communication

   Task: Try pinging one instance from another instance usinggcloud CLI.

   gcloud compute sshVM-A --command "pingVM-B"

   Potential Error: "Could not resolve host"—This meansVM-A can'tfind the IP address forVM-B.

   Resolution: Update the hostname you're using forVM-B to its fullyqualified domain name (FQDN), which includes the zone name:INSTANCE_NAME.ZONE.c.PROJECT_ID.internal

2. Instance communication within Compute Engine services

   Task: If you're using health checks formanaged instance groups (MIGs)that rely on internal DNS names, check if the health checks are passing.

   Potential Error: "Health check failed"—This indicates the healthcheck can't reach its target due to DNS resolution problems.

   Resolution: Ensure thehealth checkis using the FQDN of the target instance, including the zone name.

3. Application-specific use cases

   Many applications rely on internal DNS for tasks like the following:

   • Connecting to databases (for example, Cloud SQL)

   • Interacting with message queues (for example, Pub/Sub)

   • Potential Errors: These vary depending on the application but mightinclude:

     • "Unable to connect toSERVICE_NAME"
     • "Connection timed out"
     • "No such host is known"

   • Resolution: Check your application's configuration to make sure it'susing the FQDN (including the zone name) when referencing services.

Troubleshoot the global DNS to zonal DNS migration process

If you have issues with the migration process, refer to thetroubleshooting guide.

Revert to using global DNS

You can undo the migration to zonal DNS by changing the default internal DNStype back to global DNS. You can do this at the organization, project, instance,or container level.

Revert to using global DNS for a project

To revert a project to using global DNS, complete the following steps.

1. Add the following to the project's metadata:vmDnsSetting=GlobalDefault.

   For information about how to set project metadata values, seeSet and remove custom metadata.

2. Verify that none of the instances in the project have thevmDnsSettingmetadata value set toZonalOnly.

   gcloud compute instances describeINSTANCE_NAME --flatten="metadata[]"

   ReplaceINSTANCE_NAME with the name of the instance tocheck.

3. Refresh the DHCP lease on each instance. You can refresh the lease byrestarting the instance, waiting for thelease to expire, or byrunning one of the following commands in the guest operating system:

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

Revert to using global DNS for an instance

To revert a specific instance to using global DNS, complete the following steps.

1. Update the instance's metadata to includevmDnsSetting=GlobalDefault.

   For information about how to set compute instance metadata values, seeSet and remove custom metadata.

2. To force the DNS configuration change, restart the network of the instanceusing one of the following commands:

   • For Container-Optimized OS or Ubuntu:

     sudo systemctl restart systemd-networkd

   • For CentOS, RedHat EL, Fedora CoreOS, or Rocky Linux:

     sudo systemctl restart network

     or

     sudo systemctl restart NetworkManager.service

   • For Debian:

     sudo systemctl restart networking

   • For Linux systems withnmcli:

     sudo nmcli networking offsudo nmcli networking on

   • For Windows:

     ipconfig /renew

Revert to using global DNS for a container

If you run your application or workload in containers, on Google Kubernetes Engine, or onApp Engine flexible environment, the DNS configuration in your container settings might notautomatically update until you restart the containers. To disable zonal DNS onthese container apps, complete the following steps.

1. Set the project metadata settingvmDnsSetting toGlobalDefault on theprojects that own the containers and VMs.

2. Restart the containers so that their DNS settings revert to the originalstate.

What's next

• Review theGoogle Cloud resourcehierarchyfor information about the relationship between organizations, folders, andprojects.
• Learn more aboutinternal DNS forCompute Engine.