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 Google Cloud DNS API requires that you create a Google 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 Google 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 Google 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

where [KEY]:[VALUE] is an arbitrary key:value pair, such as Dept:Marketing or Project:project1. The --labels flag is not required for this command.

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

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.

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 =

Next steps

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

Send feedback about...

Cloud DNS Documentation