Managing records

Managing DNS records for the Cloud DNS API involves sending change requests to the API. This page describes how to make changes that consist of additions and deletions to a resource record set (ResourceRecordSet) collection. This page also describes how to send the desired changes to the API by using the import, export, and transaction commands.

Before you begin

You must have already created a managed zone and completed the prerequisites for creating a zone.

You can add or remove DNS records in a record set by creating and executing a transaction that specifies the operations that you want to perform. A transaction is a group of one or more record changes that must be propagated together. The entire transaction either succeeds or fails, so your data is never left in an intermediate state.

For more information about DNS record types, see this list of supported DNS record types.

Adding a record

When adding a record, you can add two values or strings to the record set for the same DNS name. When adding record sets, you must add a space between the first value and the second value.

Console

To create a record set, follow these steps:

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

    Go to Cloud DNS zones

  2. Click the name of the managed zone that you want to add the record to.

  3. On the Zone details page, click Add record set.

  4. On the Create record set page, in the DNS name field, enter the subdomain of the DNS zone—for example, mail. The trailing dot is automatically added at the end.

    To create a wildcard DNS record, enter an asterisk—for example, *.example.com.

  5. Select the Resource record type—for example, MX.

  6. In the TTL field, enter a numeric value for the resource record's time to live, which is the amount of time that it can be cached. This value must be a positive integer.

  7. From the TTL unit menu, select the unit of time—for example, 30 minutes.

  8. Depending on the resource record type that you have selected, populate the remaining fields.

  9. To enter additional information, click Add item.

  10. Click Create.

gcloud

  1. To start a transaction, use the gcloud dns record-sets transaction start command:

    gcloud dns record-sets transaction start
       --zone=MANAGED_ZONE
    

    Replace MANAGED_ZONE with the name of the managed zone whose record sets you want to manage—for example, my-zone-name.

  2. To add a record set as part of a transaction, use the gcloud dns record-sets transaction add command:

    gcloud dns record-sets transaction add RR_DATA
       --name=DNS_NAME \
       --ttl=TTL \
       --type=RECORD_TYPE \
       --zone=MANAGED_ZONE
    

    Replace the following:

    • RR_DATA: an arbitrary value associated with the resource record set—for example, 198.51.100.5; you can also enter multiple values, rrdata1 rrdata2 rrdata3—for example, 198.51.100.5 10.2.3.4...
    • DNS_NAME: the DNS or domain name of the record set to add—for example, test.example.com
    • TTL: the time to live (TTL) for the record set in number of seconds—for example, 300
    • RECORD_TYPE: the record type—for example, A
    • MANAGED_ZONE: the name of the managed zone whose record sets you want to manage—for example, my-zone-name
  3. To execute the transaction, use the gcloud dns record-sets transaction execute command:

    gcloud dns record-sets transaction execute
       --zone=MANAGED_ZONE
    
  4. To add a wildcard transaction, use the gcloud dns record-sets transaction add command:

    gcloud dns record-sets transaction add
       --zone=MANAGED_ZONE \
       --name=WILDCARD_DNS_NAME \
       --type=RECORD_TYPE \
       --ttl=TTL
    

    Replace the following:

    • MANAGED_ZONE: the name of the managed zone whose record sets you want to manage—for example, my-zone-name
    • WILDCARD_DNS_NAME: the DNS or domain name of the record set that you want to add—for example, *.example.com. (note the trailing dot)
    • RECORD_TYPE: the record type—for example, CNAME
    • TTL: the TTL for the record set in number of seconds—for example, 300

API

To update a transaction with new resource record sets, use the changes.create method:

POST https://dns.googleapis.com/dns/v1/projects/PROJECT_ID/managedZones/MANAGED_ZONE/changes
{
  "deletions": [
    {
      "name": DNS_NAME,
      "type": RECORD_TYPE,
      "ttl": TTL,
      "rrdatas": [
        RR_DATA
      ]
    }
  ]
  "additions": [
    {
      "name": DNS_NAME,
      "type": RECORD_TYPE,
      "ttl": TTL,
      "rrdatas": [
        RR_DATA
      ]
    }
  ]
}

Replace the following:

  • PROJECT_ID: your project ID
  • MANAGED_ZONE: your managed zone name or ID
  • DNS_NAME: the DNS or domain name of the record set—for example, test.example.com. (note the trailing dot)
  • RECORD_TYPE: the record type
  • TTL: the time to live (TTL) for the record set in number of seconds—for example, 30
  • RR_DATA: an arbitrary value associated with the resource record set—for example, 198.51.100.5; you can also enter multiple values, rrdata1 rrdata2 rrdata3—for example, 198.51.100.5 10.2.3.4...

Removing a record

Console

To remove a record or record set, follow these steps:

  1. In the Cloud Console, go to the Cloud DNS page.

    Go to Cloud DNS

  2. Click the zone name whose record set you want to delete. Records for the zone are listed on the Zone details page.

  3. Next to the record that you want to delete, select the checkbox.

  4. Click Delete record set.

gcloud

To remove a transaction, use the gcloud dns record-sets transaction remove command:

gcloud dns record-sets transaction remove RR_DATA
    --name=DNS_NAME \
    --ttl=TTL \
    --type=RECORD_TYPE \
    --zone=MANAGED_ZONE
  

Replace the following:

  • RR_DATA: an arbitrary value associated with the resource record set—for example, 198.51.100.5; you can also enter multiple values, rrdata1 rrdata2 rrdata3—for example, 198.51.100.5 10.2.3.4...
  • DNS_NAME: the DNS or domain name of the record set to remove—for example, test.example.com
  • TTL: the TTL for the record set in number of seconds—for example, 30
  • RECORD_TYPE: the record type
  • MANAGED_ZONE: the name of the managed zone

To replace an existing record, run the remove command followed by the add command.

API

To update a transaction with deleted resource record sets, use the changes.create method:

POST https://dns.googleapis.com/dns/v1/projects/PROJECT_ID/managedZones/MANAGED_ZONE/changes
{
  "deletions": [
    {
      "name": DNS_NAME,
      "type": RECORD_TYPE,
      "ttl": TTL,
      "rrdatas": [
        RR_DATA
      ]
    }
  ]
  "additions": [
    {
      "name": DNS_NAME,
      "type": RECORD_TYPE,
      "ttl": TTL,
      "rrdatas": [
        RR_DATA
      ]
    }
  ]
}

Replace the following:

  • PROJECT_ID: your project ID
  • MANAGED_ZONE: your managed zone name or ID
  • DNS_NAME: the DNS or domain name of the record set—for example, test.example.com. (note the trailing dot)
  • RECORD_TYPE: the record type
  • TTL: the TTL for the record set in number of seconds—for example, 30
  • RR_DATA: an arbitrary value associated with the resource record set—for example, 198.51.100.5; you can also enter multiple values, rrdata1 rrdata2 rrdata3—for example, 198.51.100.5 10.2.3.4...

Importing and exporting record sets

To copy record sets into and out of a managed zone, you can use import and export. The formats that you can import from and export to are either BIND zone file format or YAML records format.

gcloud

  1. To import a record set, use the dns record-sets import command. The --zone-file-format flag tells import to expect a BIND zone-formatted file. If you omit this flag, import expects a YAML-formatted records file:

    gcloud dns record-sets import -z=examplezonename \
       --zone-file-format path-to-example-zone-file
    

    When you use the gcloud dns record-sets import command, specifying --replace-origin-ns replaces the NS records for the zone with the NS records specified in the zone file. These records must match the name servers assigned by Cloud DNS to host the zone. They must also match the NS records specified in the parent (delegating) zone. By default, Cloud DNS does not overwrite NS records. If you use this flag, you must verify that the NS records are correct. They must come from a prior export of the same zone assigned to the same name server by Cloud DNS.

  2. To export a record set, use the dns record-sets export command. To specify that the record sets are exported into a BIND zone-formatted file, use the --zone-file-format flag. For example:

    example.com. 21600 IN NS ns-gcp-private.googledomains.com.
    example.com. 21600 IN SOA ns-gcp-private.googledomains.com.
    cloud-dns-hostmaster.google.com. 1 21600 3600 259200 300
    host1.example.com. 300 IN A 192.0.2.91
    

    If you omit the --zone-file-format flag, export exports the record set into a YAML-formatted records file:

    gcloud dns record-sets export example.zone -z=examplezonename \
       --zone-file-format
    

    For example:

    ---
    kind: dns#resourceRecordSet
    name: example.com.
    rrdatas:
    - ns-gcp-private.googledomains.com.
    ttl: 21600
    type: NS
    ---
    kind: dns#resourceRecordSet
    name: example.com.
    rrdatas:
    - ns-gcp-private.googledomains.com. cloud-dns-hostmaster.google.com. 1 21600 3600 259200 300
    ttl: 21600
    type: SOA
    ---
    kind: dns#resourceRecordSet
    name: host1.example.com.
    rrdatas:
    - 192.0.2.91
    ttl: 300
    type: A
    

Displaying the current record set

gcloud

To display the current DNS records for your zone, use the gcloud dns record-sets list command:

gcloud dns record-sets list
   --zone="myzonename"

The command outputs the JSON response for the resource record set for the first 100 records. You can specify these additional parameters:

  • --limit: maximum number of record sets to list
  • --name: only list record sets with this exact domain name
  • --type: only list records of this type; if present, the --name parameter must also be present

Python

To display the current DNS records for your zone, run the following:

def list_resource_records(project_id, zone_name):
    client = dns.Client(project=project_id)
    zone = client.zone(zone_name)

    records = zone.list_resource_record_sets()

    return [(record.name, record.record_type, record.ttl, record.rrdatas)
            for record in records]

Creating a resource record set

Console

To create a resource record set, follow these steps:

  1. In the Cloud Console, go to the Cloud DNS page.

    Go to Cloud DNS

  2. Click the zone for which you want to create a resource record set.

  3. On the Zone details page, click Add record set.

  4. Enter the DNS name for the record set—for example, test.example.com.

  5. Select the resource record type.

  6. Enter the time to live (TTL) for the resource record set—for example, 30.

  7. Select the TTL unit—for example, minutes.

  8. Enter the details based on the record type that you have selected.

  9. Click Create.

gcloud

To create a resource record set, use the gcloud beta dns record-sets create command:

gcloud beta dns record-sets create RRSET_NAME
    --rrdatas=RR_DATA \
    --ttl=TTL \
    --type=RRSET_TYPE \
    --zone=MANAGED_ZONE

Replace the following:

  • RRSET_NAME: the DNS name that matches the incoming queries with this zone's DNS name as its suffix—for example, test.example.com
  • RR_DATA: an arbitrary value associated with the resource record set—for example, 198.51.100.5; you can also enter multiple values, rrdata1 rrdata2 rrdata3—for example, 198.51.100.5 10.2.3.4...
  • TTL: the TTL in seconds that the resolver caches this resource record set—for example, 30
  • RRSET_TYPE: the resource record type of this resource record set—for example, A
  • MANAGED_ZONE: the managed zone that this resource record set is affiliated with—for example, my-zone-name; the name of this resource record set must have the DNS name of the managed zone as its suffix

API

To create a resource record set, use the resourceRecordSets.create method:

POST https://www.googleapis.com/dns/v1/projects/PROJECT_ID/managedZones/MANAGED_ZONE/rrsets
{
    "name": RRSET_NAME,
    "type": RRSET_TYPE,
    "ttl": TTL,
    "rrdatas": RR_DATA
}

Replace the following:

  • PROJECT_ID: the ID of the project
  • MANAGED_ZONE: the managed zone that this resource record set is affiliated with—for example, my-zone-name; the name of this resource record set must have the DNS name of the managed zone as its suffix
  • RRSET_NAME: the DNS name that matches the incoming queries with this zone's DNS name as its suffix—for example, test.example.com
  • RRSET_TYPE: the resource record type of this resource record set—for example, A
  • TTL: the TTL in seconds that the resolver caches this resource record set—for example, 30
  • RR_DATA: an arbitrary value associated with the resource record set—for example, 198.51.100.5; you can also enter multiple values, rrdata1 rrdata2 rrdata3—for example, 198.51.100.5 10.2.3.4...

Viewing details of a resource record set

This procedure assumes that you have created a resource record set within the managed zone that uses the same name and type.

Console

To view the details of an existing resource record set, follow these steps:

  1. In the Cloud Console, go to the Cloud DNS zones page.

    Go to Cloud DNS zones

  2. Click the zone for which you want to view the resource record set.

  3. The Zone details page lists the details of all the resource record sets in that zone.

gcloud

To view the details of an existing resource record set, use the gcloud beta dns record-sets describe command:

gcloud beta dns record-sets describe RRSET_NAME
  --type=RRSET_TYPE \
  --zone=MANAGED_ZONE

Replace the following:

  • RRSET_NAME: the DNS name that matches the incoming queries with this zone's DNS name as its suffix—for example, test.example.com
  • RRSET_TYPE: the resource record type of this resource record set—for example, A
  • MANAGED_ZONE: the managed zone that this resource record set is affiliated with—for example, my-zone-name; the name of this resource record set must have the DNS name of the managed zone as its suffix

API

To get the details of an existing resource record set, use the resourceRecordSets.get method:

GET https://www.googleapis.com/dns/v1/projects/PROJECT_ID/managedZones/MANAGED_ZONE/rrsets/RRSET_NAME/RRSET_TYPE

Replace the following:

  • PROJECT_ID: the ID of the project
  • MANAGED_ZONE: the managed zone that this resource record set is affiliated with—for example, my-zone-name; the name of this resource record set must have the DNS name of the managed zone as its suffix
  • RRSET_NAME: the DNS name that matches the incoming queries with this zone's DNS name as its suffix—for example, test.example.com
  • RRSET_TYPE: the resource record type of this resource record set—for example, A

Patching a resource record set

Console

To apply a partial update to an existing resource record set, follow these steps:

  1. In the Cloud Console, go to the Cloud DNS zones page.

    Go to Cloud DNS zones

  2. Click the zone for which you want to update the resource record set.

  3. On the Zone details page, next to the resource record set that you want to update, click Edit.

  4. After making the necessary updates, click Save.

gcloud

To apply a partial update to an existing resource record set, use the gcloud beta dns record-sets update command:

gcloud beta dns record-sets update RRSET_NAME
    --rrdatas=RR_DATA \
    --ttl=TTL \
    --type=RRSET_TYPE \
    --zone=MANAGED_ZONE

Replace the following:

  • RRSET_NAME: the DNS name that matches the incoming queries with this zone's DNS name as its suffix—for example, test.example.com
  • RR_DATA: an arbitrary value associated with the resource record set—for example, 198.51.100.5; you can also enter multiple values, rrdata1 rrdata2 rrdata3—for example, 198.51.100.5 10.2.3.4...
  • TTL: the TTL in seconds that the resolver caches this resource record set—for example, 30
  • RRSET_TYPE: the resource record type of this resource record set—for example, A
  • MANAGED_ZONE: the managed zone that this resource record set is affiliated with—for example, my-zone-name; the name of this resource record set must have the DNS name of the managed zone as its suffix

API

To apply a partial update to an existing resource record set, use the resourceRecordSets.patch method:

PATCH https://www.googleapis.com/dns/v1/projects/PROJECT_ID/managedZones/MANAGED_ZONE/rrsets/RRSET_NAME/RRSET_TYPE
{
  "ttl": TTL,
  "rrdatas": RR_DATA,
  "update_mask": {
      "paths": ["rrset.ttl", "rrset.rrdatas"]
  }
}

Replace the following:

  • PROJECT_ID: the ID of the project
  • MANAGED_ZONE: the managed zone that this resource record set is affiliated with—for example, my-zone-name; the name of this resource record set must have the DNS name of the managed zone as its suffix
  • RRSET_NAME: the DNS name that matches the incoming queries with this zone's DNS name as its suffix—for example, test.example.com
  • RRSET_TYPE: the resource record type of this resource record set—for example, A
  • TTL: the TTL in seconds that the resolver caches this resource record set—for example, 30
  • RR_DATA: an arbitrary value associated with the resource record set—for example, 198.51.100.5; you can also enter multiple values, rrdata1 rrdata2 rrdata3—for example, 198.51.100.5 10.2.3.4...

Deleting a resource record set

Console

To delete an existing resource record set, follow these steps:

  1. In the Cloud Console, go to the Cloud DNS zones page.

    Go to Cloud DNS zones

  2. Click the zone for which you want to delete the resource record set.

  3. On the Zone details page, next to the DNS name of the resource record set that you want to delete, select the checkbox.

  4. Click Delete record sets.

gcloud

To delete an existing resource record set, use the gcloud beta dns record-sets delete command:

gcloud beta dns record-sets delete RRSET_NAME
    --type=RRSET_TYPE \
    --zone=MANAGED_ZONE

Replace the following:

  • RRSET_NAME: the DNS name that matches the incoming queries with this zone's DNS name as its suffix—for example, test.example.com
  • RRSET_TYPE: the resource record type of this resource record set—for example, A
  • MANAGED_ZONE: the managed zone that this resource record set is affiliated with—for example, my-zone-name; the name of this resource record set must have the DNS name of the managed zone as its suffix

API

To delete an existing resource record set, use the resourceRecordSets.delete method:

DELETE https://www.googleapis.com/dns/v1/projects/PROJECT_ID/managedZones/MANAGED_ZONE/rrsets/RRSET_NAME/RRSET_TYPE

Replace the following:

  • PROJECT_ID: the ID of the project
  • MANAGED_ZONE: the managed zone that this resource record set is affiliated with—for example, my-zone-name; the name of this resource record set must have the DNS name of the managed zone as its suffix
  • RRSET_NAME: the DNS name that matches the incoming queries with this zone's DNS name as its suffix—for example, test.example.com
  • RRSET_TYPE: the resource record type of this resource record set—for example, A

Selecting resource record types

For record type Enter
A

The host's numeric IP address, in dotted decimal format.

AAAA

The host's numeric IP address, in IPv6 hexadecimal format.

CAA

The certificate authorities that are authorized to issue certificates for this domain.

CNAME

The canonical name for which the DNS name is an alias.

DNSKEY

The DNSSEC key from another operator for secure transfer. This record set type can only be added to a DNSSEC-enabled zone in Transfer state.

DS

The DNSSEC key fingerprint for a secure delegated zone. This record set type does not activate DNSSEC for a delegated zone unless you enable (and activate) DNSSEC for this zone.

IPSECVPNKEY

The IPsec public VPN key. DNSSEC is recommended when using this record set type, but it is not enabled for this zone.

MX

A number and DNS name of a mail exchange server, indicating priority of the server. Servers with lower numbers are tried first. Make sure that there is a space between the number and the DNS name.

NAPTR

Name authority pointer rules used for mapping Uniform Resource Names.

NS

The DNS name of the authoritative name server. Your NS records must match the name servers for your zone.

PTR

The resource's canonical name, typically used for reverse lookups.

SPF

The SPF record set type is deprecated. Use TXT records starting with v=spf1 instead. SPF type records are not used by modern email software.

SRV

The data that specifies the location, that is, the hostname and port number, of servers for a particular service. For more details, see RFC 2782.

SSHFP

The SSH server algorithm number, fingerprint type number, and key fingerprint. Use this record type if you have enabled DNSSEC for this zone.

TLSA

The DNS-based Authentication of Named Entities (DANE) TLSA Certificate Association information.

TXT

Text data, which can contain arbitrary text and can also be used to define machine-readable data, such as security or abuse prevention information.

A TXT record may contain one or more text strings; the maximum length of each string is 255 characters. Mail agents and other software agents concatenate multiple strings.

Enclose each string in quotation marks. For example:

          "Hello world" "Bye world"
          

What's next