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.
- If you don't already have one, sign up for a Google Account.
- Enable the Cloud DNS API in the Cloud Console. You can choose an existing Compute Engine or App Engine project, or you can create a new project.
- If you need to make requests to the REST API, you need to create an OAuth 2.0 ID: Setting up OAuth 2.0.
- 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 Cloud Console. You could also ask your user to provide the project name that they want to use in your app.
-
The client ID (
If you have not run the gcloud
command-line tool previously, you must
run the following command to specify the project name and authenticate with
the 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.
Creating 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.
Creating a public zone
To create a new managed zone, complete the following steps.
Console
In the Cloud Console, go to the Create a DNS zone page.
For the Zone type, select Public.
Enter a Zone name such as
my-new-zone
.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
.Under DNSSEC, select Off, On, or Transfer. For more information, see Enabling DNSSEC for existing managed zones.
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 zoneDESCRIPTION
: a description for your zoneDNS_SUFFIX
: the DNS suffix for your zone, such asexample.com
LABELS
: an optional comma-delimited list of key-value pairs such asdept=marketing
orproject=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 createdNAME
: a name for your zoneDESCRIPTION
: a description for your zoneDNS_NAME
: the DNS suffix for your zone, such asexample.com
Creating 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
In the Cloud Console, go to the Create a DNS zone page.
For the Zone type, select Private.
Enter a Zone name such as
my-new-zone
.Enter a DNS name suffix for the private zone. All records in the zone share this suffix, for example:
example.private
.Optional: Add a description.
Under Options, select Default (private).
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.
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 zoneDESCRIPTION
: a description for your zoneDNS_SUFFIX
: the DNS suffix for your zone, such asexample.private
VPC_NETWORK_LIST
: a comma-delimited list of VPC networks that are authorized to query the zone; these networks must be in the same project as the zoneLABELS
: an optional comma-delimited list of key-value pairs such asdept=marketing
orproject=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 createdNAME
: a name for your zoneDESCRIPTION
: a description for your zoneDNS_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 query records in this zone. You can add multiple VPC networks as indicated. To determine the URL for a VPC network, use the followinggcloud
command, replacingVPC_NETWORK_NAME
with the network's name:gcloud compute networks describe VPC_NETWORK_NAME \ --format="get(selfLink)"
Creating 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.
Creating 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.
To create a new managed reverse lookup private zone, complete the following steps.
Console
In the Cloud Console, go to the Create a DNS zone page.
For the Zone type, select Private.
Enter a Zone name such as
my-new-zone
.Enter a DNS name suffix for the zone. The suffix must end with
in-addr.arpa
to be a reverse zone. This DNS name must match the reverse lookup name of the non-RFC 1918 PTR records that you are trying to resolve through Cloud DNS. For example, if you are trying to match the PTR record for20.20.1.2
, you must create a reverse lookup zone with the DNS name of2.1.20.20.in-addr.arpa
.Optional: Add a description.
Under Options, select Managed reverse lookup zone.
Select the networks to which the private zone must be visible.
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 \ --visibility=private \ --managed-reverse-lookup=true
Replace the following:
NAME
: a name for your zoneDESCRIPTION
: a description for your zoneDNS_SUFFIX
: the DNS suffix for your reverse zone that must end in.in-addr.arpa
; typically, reverse zones take the form${ip_block_in_reverse}.in-addr.arpa
VPC_NETWORK_LIST
: a comma-delimited list of VPC networks that contain the Google Cloud resources to whichPTR
records resolve
Creating a forwarding zone
To create a new managed private forwarding zone, complete the following steps.
Before you begin, ensure that you understand the following:
- The differences between standard and private routing as shown in Forwarding targets and routing methods
- The network requirements for forwarding targets
Console
In the Cloud Console, go to the Create a DNS zone page.
For the Zone type, select Private.
Enter a Zone name such as
my-new-zone
.Enter a DNS name suffix for the private zone. All records in the zone share this suffix. For example,
example.private
.Optional: Add a description.
Under Options, select Forward queries to another server.
Select the networks to which the private zone must be visible.
To add the IPv4 addresses of a forwarding target, click Add item. You can add multiple IP addresses.
To force private routing to the forwarding target, under Private forwarding, select the Enable checkbox.
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 \ --forwarding-targets=FORWARDING_TARGETS_LIST \ --private-forwarding-targets=PRIVATE_FORWARDING_TARGETS_LIST \ --visibility=private
Replace the following:
NAME
: a name for your zoneDESCRIPTION
: a description for your zoneDNS_SUFFIX
: the DNS suffix for your zone, such asexample.private
VPC_NETWORK_LIST
: a comma-delimited list of VPC networks that are authorized to query the zone; these networks must be in the same project as the zoneFORWARDING_TARGETS_LIST
: a comma-delimited list of IP addresses to which queries are sent. RFC 1918 IP addresses specified with this flag must be located in your VPC network or in an on-premises network connected to Google Cloud using Cloud VPN or Cloud Interconnect. Non-RFC 1918 IP addresses specified with this flag must be internet accessible.PRIVATE_FORWARDING_TARGETS_LIST
: a comma-delimited list of IP addresses to which queries are sent. Any IP address specified with this flag must be located in your VPC network or in an on-premises network connected to Google Cloud using Cloud VPN or Cloud Interconnect.
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 }, .... ] }, "forwardingConfig": { "kind": "dns#managedZoneForwardingConfig", "targetNameServers": [{ "kind": "dns#managedZoneForwardingConfigNameServerTarget", "ipv4Address": FORWARDING_TARGET_1 }, { "kind": "dns#managedZoneForwardingConfigNameServerTarget", "ipv4Address": FORWARDING_TARGET_2 }, .... ] }, }
Replace the following:
PROJECT_ID
: the ID of the project where the managed zone is createdNAME
: a name for your zoneDESCRIPTION
: a description for your zoneDNS_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 are able to query records in this zone. You can add multiple VPC networks as indicated. To determine the URL for a VPC network, describe the network with the followinggcloud
command, replacingVPC_NETWORK_NAME
with the network's name:gcloud compute networks describe VPC_NETWORK_NAME
--format="get(selfLink)"FORWARDING_TARGET_1
andFORWARDING_TARGET_2
: IP addresses of forwarding target name servers. You can add multiple forwarding targets as indicated. RFC 1918 IP addresses specified here must be located in your VPC network or in an on-premises network connected to Google Cloud using Cloud VPN or Cloud Interconnect. Non-RFC 1918 IP addresses specified with this flag must be internet accessible.
Creating a peering zone
Create a new managed private peering zone when you need one VPC network (the consumer network) to query the VPC name resolution order of another VPC network (the producer network). For important background information, see DNS peering.
Console
In the Cloud Console, go to the Create a DNS zone page.
For the Zone type, select Private.
Enter a Zone name such as
my-new-zone
.Enter a DNS name suffix for the private zone. All records in the zone share this suffix, for example:
example.private
.Optional: Add a description.
Select the networks to which the private zone must be visible.
Under DNS peering, select the Enable DNS peering checkbox.
In Peer project, select a peer project.
In Peer network, select a peer network.
Click Create.
gcloud
In the project that contains the consumer VPC network, identify or create a service account.
Grant the DNS Peer role to the service account (from the previous step) in the project that contains the producer VPC network.
gcloud projects add-iam-policy-binding PRODUCER_PROJECT_ID \ --member=SERVICE_ACCOUNT \ --role=roles/dns.peer
Replace the following:
PRODUCER_PROJECT_ID
: the ID of the project that contains the producer VPC networkSERVICE_ACCOUNT
: the service account in the project that contains the consumer VPC network that was identified or created in step 1
In the project that contains the consumer VPC network, create a new managed private peering zone by running the
dns managed-zones create
command:gcloud dns managed-zones create NAME \ --description=DESCRIPTION \ --dns-name=DNS_SUFFIX \ --networks=CONSUMER_VPC_NETWORK \ --account=SERVICE_ACCOUNT \ --target-network=PRODUCER_VPC_NETWORK \ --target-project=PRODUCER_PROJECT_ID \ --visibility=private
Replace the following:
NAME
: a name for your zoneDESCRIPTION
: a description for your zoneDNS_SUFFIX
: the DNS suffix for your zone, such asexample.com
CONSUMER_VPC_NETWORK
: the name of the consumer VPC networkSERVICE_ACCOUNT
: the service account in the project that contains the consumer VPC network, identified in step 1; if omitted, thegcloud
tool uses the currently active IAM member, as indicated bygcloud auth list
PRODUCER_VPC_NETWORK
: the name of the producer VPC networkPRODUCER_PROJECT_ID
: the ID of the project that contains the producer VPC network
Updating managed zones
Cloud DNS lets you modify certain attributes of your managed public or managed private zone.
Updating public zones
You can change the description or DNSSEC configuration of a public zone.
Console
In the Cloud Console, go to the Cloud DNS zones page.
Click the public zone that you want to update.
Click
Edit.To change DNSSEC settings, under DNSSEC, select Off, On, or Transfer. For more information, see Enabling DNSSEC for existing managed zones.
Optional: Update the description.
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 zoneDESCRIPTION
: a description for your zoneSTATE
: a DNSSEC setting such asOff
,On
, orTransfer
To modify the VPC networks to which a private zone is visible:
Console
In the Cloud Console, go to the Cloud DNS zones page.
Click the private zone that you want to update.
Click
Edit.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.
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 zoneDESCRIPTION
: a description for your zoneVPC_NETWORK_LIST
: a comma-delimited list of VPC networks that are authorized to query the zone; these networks must be in the same project as the zone
Updating 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 zoneLABELS
: an optional comma-delimited list of key-value pairs such asdept=marketing
orproject=project1
; for more information, see the SDK documentation
Listing and describing managed zones
The following sections show how to list or describe a managed zone.
Listing managed zones
To list all of your managed zones within a project, complete the following steps.
Console
In the Cloud Console, go to the Cloud DNS zones page.
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"
Describing a managed zone
To view the attributes of a managed zone, complete the following steps.
Console
In the Cloud Console, go to the Cloud DNS zones page.
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.
Deleting a managed zone
To delete a managed zone, complete the following steps.
Console
In the Cloud Console, go to the Cloud DNS zones page.
Click the managed zone that you want to delete.
Remove all records in the zone except for the
SOA
andNS
records. For more information, see Removing a record.Click Delete zone.
gcloud
Remove all records in the zone except for the
SOA
andNS
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.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 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. |
Cloud DNS uses the |
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 port53
.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 networkFor 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 the35.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 to35.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 include35.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
- To find solutions for common issues that you might encounter when using Cloud DNS, see Troubleshooting.
- To configure Cloud DNS server policies and use them with VPC networks, see Applying Cloud DNS server policies.
- To use IDNs with Cloud DNS, see Creating zones with internationalized domain names.
- To display an audit log of operations, see Viewing operations on managed zones.