This document explains how to update your internal DNS policy to use zonal DNSfor new projects. Zonal DNS improves application reliability by isolatingoutages within zones, preventing disruptions to critical services like instancecreation and autohealing.

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 view organization wide internal dns usage and update the default policy, ask your administrator to grant you the following IAM roles:

• Check the default global DNS policy:Organization Policy Administrator (roles/orgpolicy.policyAdmin) on the folder or organization
• Determine if a folder is ready to migrate to zonal DNS:Browser (roles/browser) on the folder or organization

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

These predefined roles contain the permissions required to view organization wide internal dns usage and update the default policy. 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.

Overview of the configuration

When you set an organization policy to override the default internal DNS type,newly created projects use zonal DNS by default. The organization policy doesn'timpact existing projects where the Compute Engine API is already enabled. Toswitch existing projects to use zonal DNS, seeswitching existing projects to zonal DNS.

We recommend enforcing a zonal DNS policy at the organization level. Thisapproach ensures that all new projects created within your organization willuse zonal DNS, improving their reliability and resilience. However, you mightneed to exempt some folders from this organization-wide policy.Exempting folders is necessary when new projects within those folders depend onexisting projects that are incompatible with zonal DNS.

The process of enforcing a zonal DNS policy at the organization level includesthe following steps:

1. Gather a list of projects and folders: Compile a list of all projectsand their associated folders within your organization.
2. Identify folders to exempt: Pinpoint the folders that contain theincompatible projects identified in the Step 1. These folders willneed to be temporarily exempt from the zonal DNS policy.
3. Set the organizational policy: Enforce the zonal DNS policy at theorganizational level.
4. Exempt specific folders: Apply exemptions to the folders identified inStep 3. This allows them to continue using global DNS while you address theincompatible projects within them.

This approach ensures that new projects utilize zonal DNS for enhancedreliability, while also accommodating existing dependencies on older projectsthat might not be ready for immediate migration.

Limitations

Enabling zonal DNS names across your entire organization applies zonal DNSsettings to instances in other services, such as the following:

• App Engine flexible environment,Google Kubernetes Engine, andContainers running on Compute Engine
• Cloud SQL,Cloud Run functions, andBatch
• Dataproc andDataflow

Review whether your applications use any of these services anduse query analysis to identify compatibility issues with zonal DNSfor the folders and projects associated with those applications.

Check if your organization uses Global DNS by default

The default DNS setting for your organization depends on two factors:

• Theorganization creation date:

  • Created after September 6, 2018: Your organization uses zonal DNS bydefault. No further action is needed.
  • Created before September 6, 2018: Your organization uses global DNS bydefault. You should consider migrating to zonal DNS.

• The existence and enforcement of anorganization policy constraint:

  Even if your organization was created before September 6, 2018, anadministrator might have enforced a policy to use zonal DNS for all newprojects created within the organization. To check if such a policy exists,you can use the Google Cloud console or Google Cloud CLI.

Determine which projects in a folder or organization use global DNS

To determine which projects are using global DNS, we recommendusing BigQuery to create a table that lists the relative projects foryour organization and their metadata. You can then use this table to run a query

1. Create a BigQuery dataset.

2. Export the asset metadata for your organization to a BigQuery table.

   1. Make sure the Cloud Asset Inventory API is enabled.
   2. Configure the permissionsthat are required to use the Cloud Asset Inventory API.

   3. Use the following gcloud CLI command to export thecompute.googleapis.com/Project asset:

      gcloud asset export \   --content-type resource \   --organization 'ORGANIZATION_ID' \   --bigquery-table 'projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_NAME' \   --asset-types='compute.googleapis.com/Project' \   --output-bigquery-force

      Replace the following:

      • ORGANIZATION_ID: the organization ID number
      • PROJECT_ID: the project ID
      • DATASET_ID: the name of the BigQuery dataset
      • TABLE_NAME: the table you're exporting your metadata to. Ifthe table doesn't exist, BigQuery creates the table.

3. Go to theBigQuery page in theGoogle Cloud console.

4. Selectadd_boxCompose a new query.

5. In the query editor text area, enter the following GoogleSQLquery and then clickplay_arrow Run.

   SELECT  JSON_VALUE(SAFE.PARSE_JSON(resource.data).vmDnsSetting) AS vmDnsSetting,  count(*) as project_countFROMPROJECT_ID.DATASET_ID.TABLE_NAMEGROUP BY 1

   Replace the following:

   • PROJECT_ID: the project ID
   • DATASET_ID: the name of the BigQuery dataset
   • TABLE_NAME: the table that contains the exported metadata,from Step 2.

   Projects with the valueZONAL_ONLY forvmDnsSetting have zonalDNS configured. Otherwise, the projects use global DNS by default.

6. Optional: For a detailed view of thevmDnsSetting for eachproject, enter the following GoogleSQL query and thenclickplay_arrow Run.

   SELECT  SUBSTR(name,35) as project_id,  JSON_VALUE(SAFE.PARSE_JSON(resource.data).vmDnsSetting) AS vmDnsSettingFROMPROJECT_ID.DATASET_ID.TABLE_NAME

Determine migration readiness of a folder

This step uses abash script and the BigQuery table created inthe previous section to determine the migration readinessof the folder.

• The folder is ready if all projects haven't made any queries that are incompatible with zonal DNS in the last 30 days.
• If a folder is not ready for migration, the script responds with the project IDs in the folder that are preventing the folder from being ready for migration. The projects in this result list are not yet compatible with zonal DNS and require additional action.

Complete the following steps:

1. Get the folder ID. If you don't know the folder ID, do the following:
   1. In the Google Cloud console, go to theManaged resources page.
   2. Apply the filterName:FOLDER_NAME to get thefolder ID.

2. Query the BigQuery table with the exportedcompute.Project assets data.

   For the instructions on how to create the BigQuery table, seeDetermine which projects in a folder or organization use global DNS.

   Enter the following GoogleSQL query and thenclickplay_arrow Run:

   SELECT  SUBSTR(name,35) AS project_id,FROMPROJECT_ID.DATASET_ID.TABLE_NAMEWHERE CONTAINS_SUBSTR(ancestors, 'FOLDER_NUMBER')

   Replace the following:

   • PROJECT_ID: the project ID
   • DATASET_ID: the name of the BigQuery dataset
   • TABLE_NAME: the table that contains the exported metadata
   • FOLDER_NUMBER: the folder ID number

3. Copy the project ID list and save it to a file.

4. Run the followingbash script. The script iterates through the project IDsin the saved file to determine whether a folder is ready for migration.

#!/bin/bashinaccessible_projects=()unready_projects=()for project in $(cat ~/FILENAME | tr '\n' ' '); do  echo -e "Checking project $project..."  ERROR=`curl -s --request POST "https://monitoring.googleapis.com/v3/projects/$project/timeSeries:query"   -H "Authorization: Bearer $(gcloud auth print-access-token)"   -H "Accept: application/json"   -H "Content-Type: application/json"   --data '{"query":"fetch compute.googleapis.com/Location | metric '"'"'compute.googleapis.com/global_dns/request_count'"'"' | filter metric.zonal_dns_readiness = '"'"'zonal_dns_risky'"'"' | every 30d | within 30d"}'   --compressed | jq --raw-output '.error'`  if ! [[ "$ERROR" -eq "null" ]]; then    inaccessible_projects+=($project)    continue  fi  QUERY_COUNT=`curl -s --request POST "https://monitoring.googleapis.com/v3/projects/$project/timeSeries:query"   -H "Authorization: Bearer $(gcloud auth print-access-token)"   -H "Accept: application/json"   -H "Content-Type: application/json"   --data '{"query":"fetch compute.googleapis.com/Location | metric '"'"'compute.googleapis.com/global_dns/request_count'"'"' | filter metric.zonal_dns_readiness = '"'"'zonal_dns_risky'"'"' | every 30d | within 30d"}'   --compressed | jq --raw-output '.timeSeriesData[0].pointData[0].values[0].int64Value'`  if [[ "$QUERY_COUNT" -ne "null" ]] && [[ "$QUERY_COUNT" -ne "0" ]]; then    unready_projects+=($project)  fidoneerror_len=${#inaccessible_projects[@]}unready_len=${#unready_projects[@]}echo -e "$error_len projects were inaccessible"echo -e "$unready_len projects were not ready for migration"if [ $error_len -ne 0 ]; then  echo "Unable to access the following projects:"  for project in "${inaccessible_projects[@]}"; do    echo "$project"  donefiif [ $unready_len -ne 0 ]; then  echo "The following projects are not ready for migration:"  for project in "${unready_projects[@]}"; do    echo "$project"  donefiif (( $error_len + $unready_len > 0 )); then  echo "This folder is NOT ready for gDNS -> zDNS migration."else  echo "This folder is ready for gDNS -> zDNS migration."fi

ReplaceFILENAME with the name of the file that you saved theproject ID list in.

Convey the results of the migration readiness analysis with the project owners:

• For folders and projects that are safe to migrate, notify the project ownersthat they can begin tomigrate ready projects.
• For folders that contain projects that aren't safe to migrate, instructproject owners tofix incompatible queries.

Exempt folders not ready to migrate to zonal DNS

To exempt a folder from the organization policy, complete thefollowing steps to set the enforcement optionfor the policy at the folder level toOff.

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

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

   Go to Organization policies

3. ClickSelect, and then select the folders that you want to exemptfrom the organization policy.

   The Google Cloud console displays a list of organization policy constraintsfor that folder on one or more pages.

4. To find the organization policy constraint that enforces zonal DNS:

   1. ClickFilter.
   2. SelectName.
   3. Set the filter name toSets the internal DNS setting for newprojects to Zonal DNS Only.

5. Click the organization policy constraint name to open thePolicy details page.

6. ClickEdit.

7. On theEdit page, selectCustomize.

8. UnderEnforcement, selectOff to disable enforcement of theconstraint. This means that the default internal DNS type for allprojects in the folder are determined by the organization creation date.

9. ClickSave.

For more information about customizing organization policy constraints, seeCustomizing policies for boolean constraints in theResource Manager documentation.

Enforce zonal DNS by default for new projects

Use the following steps to set the organization policy for a folder ororganization.

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

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

   Go to Organization policies

3. Select the folder or organization for which you wantto view organization policies. The Google Cloud console displays a list oforganization policy constraints that are available. The list might spanmultiple pages.

4. To find the policy to enforce zonal DNS, clickFilter and selectName, then set the filter name toSets the internal DNS setting for new projects to Zonal DNS Only.

5. Click the policy name to see itsdetails.

   The policy details page provides information about the constraint and how theconstraint is applied.

   By default, the enforcement is undefined for a folder or organization.However, if a parent folder has a defined enforcement, then theenforcement is inherited from the closest parent folder that hasa defined enforcement. For more information, seeUnderstanding hierarchy evaluation.

6. To customize the organization policy, clickEdit.

7. In the edit page, selectCustomize.

8. UnderEnforcement, selectOn.

   This sets the default internal DNS type for all new projects in theorganization to zonal DNS.

9. ClickSave.

To validate the organization policy change, you can create a new project underthe folder or organization, thencreate and start a VM instance,andcheck whether your VM is enabled for zonal DNS.

If global DNS is needed to resolve a DNS name query built into yourworkload, you can rollback this change at the organization or folder level bydisabling the enforcement.

Revert to using global DNS for an organization or folder

To revert an organization or folder to using global DNS, stop enforcementof the organizational policy for zonal DNS. Complete the following steps.

1. Disable the organization policyconstraints/compute.setNewProjectDefaultToZonalDNSOnly at the organizationor folder level. For instructions on how to modify this policy, seeEnforce zonal DNS by default for new projects.

   Set the enforcement ofSets the internal DNS setting for new projects toZonal DNS Only toOff.

2. If you want to revert to using global DNS for the entire organization,verify that none of the folders in the organization are enforcing theorganization policyconstraints/compute.setNewProjectDefaultToZonalDNSOnly.

3. To verify that global DNS is configured for your projects and instances,seeDetermine which projects in a folder or organization use global DNS.

What's next

• Any existing projects that use global DNS must be migrated separately. Formore information, seeUpdate your projects to use zonal DNS.
• Use Cloud DNS logs to monitor DNS failure rates.