Managing Zones

A managed zone is the container for all of your DNS records that share the same domain name, for example, Managed zones are automatically assigned a set of name servers when they are created to handle responding to DNS queries for that zone. A managed zone has quotas for the number of resource records that it can include.

Before you begin

The Cloud DNS API requires that you create a Cloud DNS project and enable the Cloud DNS API.

If you are creating an application that will use the REST API, you will also need to create an OAuth 2.0 client ID.

  1. If you don't already have one, sign up for a Google account.
  2. Enable the Cloud DNS API in the GCP Console. You can choose an existing Compute Engine or App Engine project, or you can create a new project.
  3. If you need to make requests to the REST API, you will need to create an OAuth 2.0 ID: Setting up OAuth 2.0.
  4. Note the following information in the project that you will need to input in later steps:
    • The client ID (
    • The project ID that you wish to use. You can find the ID at the top of the Overview page in the GCP Console. You could also ask your user to provide the project name that they want to use in your app.

If you have not run the gcloud command-line tool previously, you will need to run the following command to specify the project name and authenticate with the GCP Console:

gcloud auth login

You can also specify the --project parameter for a command to operate against a different project for that invocation.

Creating managed zones

When you get started with Cloud DNS API, you will need to create a managed zone to contain your DNS records. The managed zone is connected to your Cloud DNS project. Note that when you create a zone, the new zone won't be used until you update your domain registration, or explicitly point some resolver at, or directly query, one of your zone's name servers.

To create a zone, you must provide the DNS zone name, a description, and a name to identify the zone. Use the --visibility flag to designate the managed zone as public or private and the --networks flag to indicate the VPC networks to which a private zone is visible.


To create a private zone:

gcloud beta dns managed-zones create my-zone-name \
    --dns-name="" \
    --description="A zone" \
    --visibility=private \

To create a public zone:

gcloud beta dns managed-zones create my-zone-name \
    --dns-name="" \

To change the networks to which a private zone is visible:

gcloud beta dns managed-zones update my-zone-name \
    --networks default,newnetwork

The above command makes the private zone visible to the networks default and newnetwork. All networks to which the private zone was visible are replaced with the new list of networks.


def create_zone(project_id, name, dns_name, description):
    client = dns.Client(project=project_id)
    zone =
        name,  # examplezonename
        dns_name=dns_name,  #
    return zone

If you receive an accessNotConfigured error, you must enable the Cloud DNS API.

Creating forwarding zones

A forwarding zone overrides normal DNS resolution of the specified zones. Instead, queries for the specified zones are forwarded to the listed forwarding targets.

gcloud beta dns managed-zones create example-forwarding-zone \
    --dns-name="" \
    --networks="default,my-network" \
    --visibility=private \


  • --dns-name is the list of domains to be resolved by the forwarding zone.
  • --networks is the list of networks that should use the forwarding zone.
  • --visibility indicates whether the forwarding zone is public or private.
  • --forwarding-targets is a list of static IP addresses. These IP addresses can be RFC 1918 addresses if those addresses are reachable on the same VPC network or on a network reachable via VPN or Interconnect. Otherwise, they must be publicly reachable IP addresses.

Requirements: For an external nameserver to receive the forwarded DNS queries, you must do the following:

  • Ensure the external name servers are reachable from your VPC network.
    • In your on-premises network, set up routing and configure firewalls to permit traffic from Google's IP address range.
      • This address block is used exclusively by Google's proxies to forward DNS queries from your VPC network to another name server.
      • This address block is only reachable from within your VPC network, and, when forwarding is configured, your on-premises networks.
      • Even though is used for all GCP customers, your on-premises name servers will only receive requests from your VPC networks authorized to access your private zones (that have forwarding enabled).
  • GCP requires that the IP address of the on-premises name server that receives the forwarded query be the one that responds. If your on-premises name server responds from a different source IP address, GCP ignores the response for security reasons.

Updating managed zones

Once you have created a managed zone to contain your DNS records, you may want to update some of its properties. Currently you can only update the description and DNSSEC configuration.

To update a zone, you must provide the zone resource name (which cannot contain .—as opposed to the DNS name, which does) and the updated information associated with the zone:

Command line

gcloud dns managed-zones update --description="My zone" "myzonename"


     BODY = {
          'name' : 'myzonename',
          'description' : 'My zone'
        service = build('dns', 'v1')
        response = service.managedZones().create(project=PROJECT_NAME,

Adding and updating labels for managed zones

You can add labels to a managed zone, and you can remove existing labels.

In the following examples, [KEY]:[VALUE] is an arbitrary key:value pair, such as Dept:Marketing or Project:project1.

Add labels when you create a managed zone

gcloud dns managed-zones create \
    --dns-name="" \
    --labels [KEY]:[VALUE] \
    --description="A zone" "myzonename"

Add labels to an existing managed zone

This command adds a label to an existing managed zone.

gcloud dns managed-zones update \
    --labels [KEY]:[VALUE],[[KEY]:[VALUE]] \

Update values of label key:value pairs

This command update the value of an existing key:value label pair. If the key does not already exist, a new key:value pair is created.

gcloud dns managed-zones update \
    --update-labels [KEY]:[VALUE],[[KEY]:[VALUE]] \

Remove label key:value pairs

This command removes the specified key:value label pair(s).

gcloud dns managed-zones update \
    --remove-labels [KEY]:[VALUE],[[KEY]:[VALUE]] \

Clear all label key value pairs

This command clears all labels.

gcloud dns managed-zones update \
    --clear-labels \

Listing managed zones

To list all of your zones within a project:


gcloud dns managed-zones list


def list_zones(project_id):
    client = dns.Client(project=project_id)
    zones = client.list_zones()
    return [ for zone in zones]

Getting managed zone details

To get details about your managed zone, such as if you need to look up the associated name servers:


gcloud dns managed-zones describe "myzonename"


def get_zone(project_id, name):
    client = dns.Client(project=project_id)
    zone =

        return zone
    except NotFound:
        return None

Deleting managed zones

To delete a zone, provide the zone name to the delete command:


gcloud dns managed-zones delete "myzonename"

Note that only empty zones can be deleted. An empty managed-zone has only SOA and NS record-sets. You can easily empty a zone using the import command as follows:

touch empty-file
gcloud dns record-sets import -z "myzonename" --delete-all-existing empty-file
rm empty-file


def delete_zone(project_id, name):
    client = dns.Client(project=project_id)
    zone =

Using DNS server policies

A DNS server policy is a collection of Cloud DNS rules that govern the behaviors of the name servers that host your zone. You can use DNS server policies to:

  • Specify an alternative name server that handles all DNS queries from the specified networks
  • Enable or disable the acceptance of inbound forwarding of DNS queries

You can apply a DNS server policy to one or more GCP networks.

See DNS server policy for an overview.

Creating a DNS policy that enables inbound DNS forwarding

This policy enables inbound DNS forwarding for the default network in the project.

gcloud beta dns policies create my-policy --project=myproject \
    --description="Inbound DNS forwarding for default network" \
    --enable-inbound-forwarding=true \

Creating a DNS policy that enables an alternative name server

This policy enables an alternative name server for the default network in the project.

gcloud beta dns policies create alt-dns-policy --project=myproject \
    --description="Alternative nameservers for default network" \
    --networks=default \

Listing DNS policies

gcloud beta --project=my-project dns policies list

Deleting a DNS policy

gcloud beta --project=my-project dns policies delete example-policy

Updating a DNS policy

gcloud beta --project=myproject dns policies update --networks="default, somenewnetwork"

Listing the inbound forwarder IP Address

gcloud compute addresses list --filter='name ~ ^dns-forwarding.*' \
    --format='csv[no-heading](address, subnetwork)'

Next steps

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud DNS Documentation