Manage zones

This page provides directions for creating, updating, listing, and deleting Cloud DNS managed zones. Before you use this page, familiarize yourself with the Cloud DNS overview and Key terms.

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 uses the REST API, you must also 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 Google Cloud 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 need to create an OAuth 2.0 ID: Setting up OAuth 2.0.
  4. In the project, note the following information that you will need to input in later steps:
    • The client ID (xxxxxx.apps.googleusercontent.com).
    • The project ID that you want to use. You can find the ID at the top of the Overview page in the Google Cloud 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 Google Cloud CLI previously, you must run the following command to specify the project name and authenticate with the Google Cloud console:

gcloud auth login

If you want to run a gcloud command on Google Cloud resources in another project, specify the --project option for this command and for the other gcloud commands throughout this page.

Create managed zones

Each managed zone that you create is associated with a Google Cloud project. The following sections describe how to create the type of managed zone that Cloud DNS supports.

Create a public zone

To create a new managed zone, complete the following steps.

Console

  1. In the Google Cloud console, go to the Create a DNS zone page.

    Go to Create a DNS zone

  2. For the Zone type, select Public.

  3. Enter a Zone name such as my-new-zone.

  4. Enter a DNS name suffix for the zone using a domain name that you own. All records in the zone share this suffix, for example: example.com.

  5. Under DNSSEC, select Off, On, or Transfer. For more information, see Enable DNSSEC for existing managed zones.

  6. Click Create. The Zone details page is displayed.

gcloud

Run the dns managed-zones create command:

gcloud dns managed-zones create NAME \
    --description=DESCRIPTION \
    --dns-name=DNS_SUFFIX \
    --labels=LABELS \
    --visibility=public

Replace the following:

  • NAME: a name for your zone
  • DESCRIPTION: a description for your zone
  • DNS_SUFFIX: the DNS suffix for your zone, such as example.com
  • LABELS: an optional comma-delimited list of key-value pairs such as dept=marketing or project=project1; for more information, see the SDK documentation

API

Send a POST request using the managedZones.create method:

POST https://dns.googleapis.com/dns/v1/projects/PROJECT_ID/managedZones
{
  "name": "NAME",
  "description": "DESCRIPTION",
  "dnsName": "DNS_NAME",
  "visibility": "public"
}

Replace the following:

  • PROJECT_ID: the ID of the project where the managed zone is created
  • NAME: a name for your zone
  • DESCRIPTION: a description for your zone
  • DNS_NAME: the DNS suffix for your zone, such as example.com

Terraform

resource "google_dns_managed_zone" "example-zone" {
  name        = "example-zone"
  dns_name    = "example-${random_id.rnd.hex}.com."
  description = "Example DNS zone"
  labels = {
    foo = "bar"
  }
}

resource "random_id" "rnd" {
  byte_length = 4
}

Create a private zone

To create a new managed private zone with private DNS records managed by Cloud DNS, complete the following steps. For more information, see Best practices for Cloud DNS private zones.

Console

  1. In the Google Cloud console, go to the Create a DNS zone page.

    Go to Create a DNS zone

  2. For the Zone type, select Private.

  3. Enter a Zone name such as my-new-zone.

  4. Enter a DNS name suffix for the private zone. All records in the zone share this suffix, for example: example.private.

  5. Optional: Add a description.

  6. Under Options, select Default (private).

  7. Select the Virtual Private Cloud (VPC) networks to which the private zone must be visible. Only the VPC networks that you select are authorized to query records in the zone.

  8. Click Create.

gcloud

Run the dns managed-zones create command:

gcloud dns managed-zones create NAME \
    --description=DESCRIPTION \
    --dns-name=DNS_SUFFIX \
    --networks=VPC_NETWORK_LIST \
    --labels=LABELS \
    --visibility=private

Replace the following:

  • NAME: a name for your zone
  • DESCRIPTION: a description for your zone
  • DNS_SUFFIX: the DNS suffix for your zone, such as example.private
  • VPC_NETWORK_LIST: a comma-delimited list of VPC networks that are authorized to query the zone
  • LABELS: an optional comma-delimited list of key-value pairs such as dept=marketing or project=project1; for more information, see the SDK documentation

API

Send a POST request using the managedZones.create method:

POST https://dns.googleapis.com/dns/v1/projects/PROJECT_ID/managedZones
{

"name": "NAME",
"description": "DESCRIPTION",
"dnsName": "DNS_NAME",
"visibility": "private"
"privateVisibilityConfig": {
    "kind": "dns#managedZonePrivateVisibilityConfig",
    "networks": [{
            "kind": "dns#managedZonePrivateVisibilityConfigNetwork",
            "networkUrl": VPC_NETWORK_1
        },
        {
            "kind": "dns#managedZonePrivateVisibilityConfigNetwork",
            "networkUrl": VPC_NETWORK_2
        },
        ....
    ]
}

Replace the following:

  • PROJECT_ID: the ID of the project where the managed zone is created
  • NAME: a name for your zone
  • DESCRIPTION: a description for your zone
  • DNS_NAME: the DNS suffix for your zone, such as example.private
  • VPC_NETWORK_1 and VPC_NETWORK_2: URLs for VPC networks in the same project that can query records in this zone. You can add multiple VPC networks as indicated. To determine the URL for a VPC network, use the following gcloud command, replacing VPC_NETWORK_NAME with the network's name:

    gcloud compute networks describe VPC_NETWORK_NAME \
     --format="get(selfLink)"
    

Terraform

resource "google_dns_managed_zone" "private-zone" {
  name        = "private-zone"
  dns_name    = "private.example.com."
  description = "Example private DNS zone"
  labels = {
    foo = "bar"
  }

  visibility = "private"

  private_visibility_config {
    networks {
      network_url = google_compute_network.network-1.id
    }
    networks {
      network_url = google_compute_network.network-2.id
    }
  }
}

resource "google_compute_network" "network-1" {
  name                    = "network-1"
  auto_create_subnetworks = false
}

resource "google_compute_network" "network-2" {
  name                    = "network-2"
  auto_create_subnetworks = false
}

Create a zone with specific IAM permissions

The Identity and Access Management (IAM) permission for individual resource managed zone lets you set up specific read, write, or administrator permissions for different managed zones under the same project.

For instructions about how to create a zone with specific Identity and Access Management (IAM) permissions, see Create a zone with specific IAM permissions.

Create a Service Directory DNS zone

You can create a Service Directory zone that allows your Google Cloud-based services to query your Service Directory namespace through DNS.

For detailed instructions about how to create a Service Directory DNS zone, see Configuring a Service Directory DNS zone.

For instructions about how to use DNS to query your Service Directory, see Querying using DNS.

Terraform

resource "google_dns_managed_zone" "private-zone" {
  name        = "private-zone"
  dns_name    = "private.example.com."
  description = "Example private DNS zone"
  labels = {
    foo = "bar"
  }

  visibility = "private"

  private_visibility_config {
    networks {
      network_url = google_compute_network.network-1.id
    }
    networks {
      network_url = google_compute_network.network-2.id
    }
  }
}

resource "google_compute_network" "network-1" {
  name                    = "network-1"
  auto_create_subnetworks = false
}

resource "google_compute_network" "network-2" {
  name                    = "network-2"
  auto_create_subnetworks = false
}

Create a managed reverse lookup private zone

A managed reverse lookup zone is a private zone with a special attribute that instructs Cloud DNS to perform a PTR lookup against Compute Engine DNS data. You must set up managed reverse lookup zones for Cloud DNS to correctly resolve non-RFC 1918 PTR records for your virtual machine (VM) instances.

For instructions on how to create a new managed reverse lookup private zone, see Create a managed reverse lookup zone.

Create a forwarding zone

Forwarding zones let you target name servers for specific private zones. For instructions on how to create a new managed private forwarding zone, see Create a forwarding zone.

Create a peering zone

DNS peering lets you send requests for records that come from one zone's namespace to another VPC network. For instructions on how to create a peering zone, see Create a peering zone.

Create a cross-project binding zone

Create a managed private zone that can be bound to a network that is owned by a different project within the same organization. For instructions on how to create a cross-project binding zone, see Cross-project binding zones.

Update managed zones

Cloud DNS lets you modify certain attributes of your managed public or managed private zone.

Update public zones

You can change the description or DNSSEC configuration of a public zone.

Console

  1. In the Google Cloud console, go to the Cloud DNS zones page.

    Go to Cloud DNS zones

  2. Click the public zone that you want to update.

  3. Click Edit.

  4. To change DNSSEC settings, under DNSSEC, select Off, On, or Transfer. For more information, see Enabling DNSSEC for existing managed zones.

  5. Optional: Update the description.

  6. Click Save.

gcloud

Run the dns managed-zones update command:

gcloud dns managed-zones update NAME \
    --description=DESCRIPTION \
    --dnssec-state=STATE

Replace the following:

  • NAME: a name for your zone
  • DESCRIPTION: a description for your zone
  • STATE: a DNSSEC setting such as Off, On, or Transfer

To modify the VPC networks to which a private zone is visible:

Console

  1. In the Google Cloud console, go to the Cloud DNS zones page.

    Go to Cloud DNS zones

  2. Click the private zone that you want to update.

  3. Click Edit.

  4. Select the VPC networks to which the private zone must be visible. Only the selected VPC networks are authorized to query records in the zone.

  5. Click Save.

gcloud

Run the dns managed-zones update command:

gcloud dns managed-zones update NAME \
    --description=DESCRIPTION \
    --networks=VPC_NETWORK_LIST

Replace the following:

  • NAME: a name for your zone
  • DESCRIPTION: a description for your zone
  • VPC_NETWORK_LIST: a comma-delimited list of VPC networks that are authorized to query the zone

Update labels

To add new, change existing, remove selected, or clear all labels on a managed zone, complete the following steps.

gcloud

Run the dns managed-zones update command:

gcloud dns managed-zones update NAME \
    --update-labels=LABELS
gcloud dns managed-zones update NAME \
    --remove-labels=LABELS
gcloud dns managed-zones update NAME \
    --clear-labels

Replace the following:

  • NAME: a name for your zone
  • LABELS: an optional comma-delimited list of key-value pairs such as dept=marketing or project=project1; for more information, see the SDK documentation

List and describe managed zones

The following sections show how to list or describe a managed zone.

List managed zones

To list all of your managed zones within a project, complete the following steps.

Console

  1. In the Google Cloud console, go to the Cloud DNS zones page.

    Go to Cloud DNS zones

  2. View managed zones in the right pane.

gcloud

Run the dns managed-zones list command:

gcloud dns managed-zones list

To list all managed zones, modify the command as follows:

gcloud dns managed-zones list \
   --filter="visibility=public"

To list all managed private zones, modify the command as follows:

gcloud dns managed-zones list \
   --filter="visibility=private"

Describe a managed zone

To view the attributes of a managed zone, complete the following steps.

Console

  1. In the Google Cloud console, go to the Cloud DNS zones page.

    Go to Cloud DNS zones

  2. Click the zone that you want to inspect.

gcloud

Run the dns managed-zones describe command:

gcloud dns managed-zones describe NAME

Replace NAME with the name of your zone.

Delete a managed zone

To delete a managed zone, complete the following steps.

Console

  1. In the Google Cloud console, go to the Cloud DNS zones page.

    Go to Cloud DNS zones

  2. Click the managed zone that you want to delete.

  3. Remove all records in the zone except for the SOA and NS records. For more information, see Removing a record.

  4. Click Delete zone.

gcloud

  1. Remove all records in the zone except for the SOA and NS records. For more information, see Removing a record. You can quickly empty an entire zone by importing an empty file into a record set. For more information, see Importing and exporting record sets. For example:

    touch empty-file
    gcloud dns record-sets import -z NAME \
       --delete-all-existing \
       empty-file
    rm empty-file
    

    Replace NAME with the name of your zone.

  2. To delete a new managed private zone, run the dns managed-zones delete command:

    gcloud dns managed-zones delete NAME
    

    Replace NAME with the name of your zone.

Forwarding target network requirements

When Cloud DNS sends requests to forwarding targets, it sends packets with the source ranges listed in the following table. For more background information about the different types of targets, see Forwarding targets and routing methods.

Forwarding target type Source ranges

Type 1 target

An internal IP address of a Google Cloud VM or an internal TCP/UDP load balancer in the same VPC network that is authorized to use the forwarding zone.

Type 2 target

An IP address of an on-premises system, connected to the VPC network authorized to use the forwarding zone, using Cloud VPN or Cloud Interconnect.

35.199.192.0/19

Cloud DNS uses the 35.199.192.0/19 source range for all customers. This range is only accessible from a Google Cloud VPC network or from an on-premises network connected to a VPC network.

Type 3 target

An external IP address of a DNS name server accessible to the internet or the external IP address of a Google Cloud resource; for example, the external IP address of a VM in another VPC network.

Google Public DNS source ranges

Type 1 and Type 2 targets

Cloud DNS requires the following to access a Type 1 or a Type 2 target. These requirements are the same whether the target is an RFC 1918 IP address and you're using standard routing or if you choose private routing:

  • Firewall configuration for 35.199.192.0/19

    For Type 1 targets, create an ingress allow firewall rule for TCP and UDP port 53 traffic, applicable to your forwarding targets in each authorized VPC network. For Type 2 targets, configure an on-premises network firewall and similar equipment to permit TCP and UDP port 53.

  • Route to the forwarding target

    For Type 1 targets, Cloud DNS uses a subnet route to access the target in the VPC network authorized to use the forwarding zone. For Type 2 name targets, Cloud DNS uses either custom dynamic or custom static routes, except for tagged static routes, to access the forwarding target.

  • Return route to 35.199.192.0/19 through the same VPC network

    For Type 1 targets, Google Cloud automatically adds a special return route for the 35.199.192.0/19 destination. For Type 2 targets, your on-premises network must have a route for the 35.199.192.0/19 destination, whose next hop is in the same VPC network where the request originated, through a Cloud VPN tunnel or VLAN attachment for Cloud Interconnect.. For information about how to meet this requirement, see return route strategies for Type 2 targets.

  • Direct response from target

    Cloud DNS requires that the forwarding target that receives packets be the one that sends replies to 35.199.192.0/19. If your forwarding target sends the request to a different name server, and that other name server responds to 35.199.192.0/19, Cloud DNS ignores the response. For security reasons, Google Cloud expects the source address of each target name server's DNS reply to match the IP address of the forwarding target.

Return route strategies for Type 2 targets

Cloud DNS cannot send responses from Type 2 forwarding targets over the internet or through a different VPC network. Responses must return to the same VPC network, although they can use any Cloud VPN tunnel or VLAN attachment in that same network.

  • For Cloud VPN tunnels that use static routing, manually create a route in your on-premises network whose destination is 35.199.192.0/19 and whose next hop is the Cloud VPN tunnel. For Cloud VPN tunnels that use policy-based routing, configure the Cloud VPN's local traffic selector and the on-premises VPN gateway's remote traffic selector to include 35.199.192.0/19.
  • For Cloud VPN tunnels that use dynamic routing or for Cloud Interconnect, configure a custom route advertisement for 35.199.192.0/19 on the BGP session of the Cloud Router that manages the tunnel or VLAN attachment.

Type 3 targets

When Cloud DNS uses standard routing to access an external IP address, it expects the forwarding target to be either a system on the internet, publicly accessible, or an external IP address of a Google Cloud resource.

For example, a Type 3 target includes the external IP address of a VM in a different VPC network.

Private routing to Type 3 targets is not supported.

What's next