Create, modify, and delete zones

This page provides directions for creating, updating, listing, and deletingCloud DNS managed zones. Before you use this page, familiarize yourself withtheCloud DNS overview andKey terms.

Permissions required for this task

To perform this task, you must have been granted the following permissionsor the following IAM roles.

Permissions

  • dns.managedZones.create to create a managed zone
  • dns.managedZones.list to list managed zones
  • dns.networks.bindPrivateDNSZone
  • dns.networks.targetWithPeeringZone
  • dns.gkeClusters.bindPrivateDNSZone
  • dns.managedZones.update
  • dns.managedZones.list
  • dns.managedZones.patch
  • dns.activePeeringZones.getZoneInfo
  • dns.activePeeringZones.list
  • dns.activePeeringZones.deactivate

Roles

  • roles/dns.admin
  • roles/dns.peer

Before you begin

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

If you are creating an application that uses the REST API, you must alsocreate 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. SeeSetting up OAuth 2.0.
  4. In the project, note the following information that you 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 theOverview page in the Google Cloud console. You can 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 mustrun the following command to specify the project name and authenticate withthe Google Cloud console:

gcloud auth login

If you want to run agcloud command on Google Cloud resourcesin another project, specify the--project option for this command and for theothergcloud commands throughout this page.

Create managed zones

Each managed zone that you create is associated with aGoogle Cloud project.The following sections describe how to create the type of managed zone thatCloud 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 theCreate a DNS zone page.

    Go to Create a DNS zone

  2. For theZone type, selectPublic.

  3. Enter aZone name such asmy-new-zone.

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

  5. UnderDNSSEC, selectOff,On, orTransfer. For moreinformation, seeEnable DNSSEC for existing managed zones.

  6. ClickCreate. TheZone details page is displayed.

gcloud

Run thedns managed-zones createcommand:

gcloud dns managed-zones createNAME \    --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 asexample.com
  • LABELS: an optional comma-delimited list of key-valuepairs such asdept=marketing orproject=project1; for moreinformation, see theSDK documentation

Terraform

resource "google_dns_managed_zone" "example_zone" {  name        = "example-zone"  dns_name    = "example-${random_id.rnd.hex}.com."  description = "Example DNS zone"  labels = {    name = "value"  }}resource "random_id" "rnd" {  byte_length = 4}

API

Send aPOST request using themanagedZones.createmethod:

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 managedzone is created
  • NAME: a name for your zone
  • DESCRIPTION: a description for your zone
  • DNS_NAME: the DNS suffix for your zone, such asexample.com
Important: Cloud DNS createsNS andSOA records for youautomatically when you create the zone. Do not change the name of your zone'sNS record, and do not change the list of name servers thatCloud DNS selects for your zone.

Create a private zone

To create a new managed private zone with private DNS records managed byCloud DNS, complete the following steps. For more information,seeBest practices for Cloud DNS privatezones.

Console

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

    Go to Create a DNS zone

  2. For theZone type, selectPrivate.

  3. Enter aZone name such asmy-new-zone.

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

  5. Optional: Add a description.

  6. UnderOptions, selectDefault (private).

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

  8. ClickCreate.

gcloud

Run thedns managed-zones createcommand:

gcloud dns managed-zones createNAME \    --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 asexample.private
  • VPC_NETWORK_LIST: a comma-delimited list ofVPC networks that are authorized to query the zone
  • LABELS: an optional comma-delimited list of key-valuepairs such asdept=marketing orproject=project1; for moreinformation, see theSDK documentation

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}

API

Send aPOST request using themanagedZones.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 iscreated
  • NAME: a name for your zone
  • DESCRIPTION: a description for your zone
  • DNS_NAME: the DNS suffix for your zone, such asexample.private

  • VPC_NETWORK_1 andVPC_NETWORK_2:URLs for VPC networks in the same project that can queryrecords in this zone. You can add multiple VPC networksas indicated. To determine the URL for a VPC network,use the followinggcloud command, replacingVPC_NETWORK_NAME with the network's name:

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

Create a zone with specific IAM permissions

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

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

Create a Service Directory DNS zone

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

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

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

Note: You cannot add records to a Service Directory DNS zone directly;the data comes from the Service Directory service registry.

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 thatinstructs Cloud DNS to perform a PTR lookup against Compute EngineDNS data. You must set up managed reverse lookup zones for Cloud DNSto correctly resolve non-RFC 1918 PTR records for your virtual machine (VM)instances.

For instructions on how to create a new managed reverselookup private zone, seeCreate a managed reverse lookupzone.

Create a forwarding zone

Forwarding zones let you target name servers for specific private zones. Forinstructions on how to create a new managed privateforwarding zone, seeCreate a forwardingzone.

Create a peering zone

DNS peering lets you send requests for records that come from one zone'snamespace to another VPC network. For instructions onhow to create a peering zone, seeCreate a peeringzone.

Create a cross-project binding zone

Create a managed private zone that can be bound to a network that is owned by adifferent project within the same organization. For instructions on how tocreate a cross-project binding zone, seeCross-project bindingzones.

Update managed zones

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

Update public zones

You can change the description orDNSSEC configuration of a public zone.

Console

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

    Go to Cloud DNS zones

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

  3. ClickEdit.

  4. To change DNSSEC settings, underDNSSEC, selectOff,On, orTransfer. For more information, seeEnabling DNSSEC for existing managed zones.

    Note: Before you disable DNSSEC for a managed zone that you still wantto use, you must deactivate DNSSEC for your zone at your domain registrarto ensure that DNSSEC-validating resolvers can still resolve names in thezone. For details, seeDisabling DNSSEC for managed zones.

  5. Optional: Update the description.

  6. ClickSave.

gcloud

Run thedns managed-zones updatecommand:

gcloud dns managed-zones updateNAME \    --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 asOff,On,orTransfer

Update private zones

You can modify the VPC networks to which a private zone is visible.

Console

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

    Go to Cloud DNS zones

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

  3. ClickEdit.

  4. Select the VPC networks to which the private zone must bevisible. Only the selected VPC networks are authorizedto query records in the zone.

  5. ClickSave.

gcloud

Run thedns managed-zones updatecommand:

gcloud dns managed-zones updateNAME \    --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 ofVPC networks that are authorized to query the zone

Update labels

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

gcloud

Run thedns managed-zones updatecommand:

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

Replace the following:

  • NAME: a name for your zone
  • LABELS: an optional comma-delimited list of key-valuepairs such asdept=marketing orproject=project1; for moreinformation, see theSDK 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 theCloud DNS zones page.

    Go to Cloud DNS zones

  2. View managed zones in the right pane.

gcloud

Run thedns managed-zones listcommand:

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 theCloud DNS zones page.

    Go to Cloud DNS zones

  2. Click the zone that you want to inspect.

gcloud

Run thedns managed-zones describecommand:

gcloud dns managed-zones describeNAME

ReplaceNAME with the name of your zone.

Delete a managed zone

When you delete a zone, its DNS records are permanently removed;they cannot be recovered. To prevent losing your DNS records, export yourzone data before deletion. For information about how to export zone data,seeImport and export resource record sets.

To delete a managed zone, complete the following steps.

Console

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

    Go to Cloud DNS zones

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

  3. ClickDelete zone.

gcloud

  1. Remove all records in the zone except for theSOA andNS records.For more information, seeRemoving a record.You can quickly empty an entire zone by importing an empty file into arecord set. For more information, seeImporting and exporting recordsets.For example:

    touch empty-filegcloud dns record-sets import -zNAME \   --delete-all-existing \   empty-filerm empty-file

    ReplaceNAME with the name of your zone.

  2. To delete a new managed private zone, run thedns managed-zonesdelete command:

    gcloud dns managed-zones deleteNAME

    ReplaceNAME with the name of your zone.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.