Google Cloud DNS is a high-performance, resilient, global DNS service thatprovides a cost-effective way to make your applications and servicesavailable to your users. This programmable, authoritative DNS service canbe used to easily publish and manage DNS records using the sameinfrastructure relied upon by Google. To learn more, readCloud DNSOverview.

The goal of google-cloud is to provide an API that is comfortable to Rubyists.Your authentication credentials are detected automatically in Google CloudPlatform (GCP), including Google Compute Engine (GCE), Google Kubernetes Engine(GKE), Google App Engine (GAE), Google Cloud Functions (GCF) and Cloud Run. Inother environments you can configure authentication easily, either directly inyour code or via environment variables. Read more about the options forconnecting in theAuthentication Guide.

Creating Zones

To get started with Google Cloud DNS, use your DNS Project to create a newZone. The second argument toGoogle::Cloud::Dns::Project#create_zonemust be a unique domain name for which you canverifyownership.Substitute a domain name of your own (ending with a dot to signify that itisfullyqualified) asyou follow along with these examples.

require"google/cloud/dns"dns=Google::Cloud::Dns.newzone=dns.create_zone"example-com","example.com."putszone.id# unique identifier defined by the server

For more information, seeManagingZones.

Listing Zones

You can retrieve all the zones in your project.

require"google/cloud/dns"dns=Google::Cloud::Dns.newzones=dns.zoneszones.eachdo|zone|puts"#{zone.name} -#{zone.dns}"end

You can also retrieve a single zone by either name or id.

require"google/cloud/dns"dns=Google::Cloud::Dns.newzone=dns.zone"example-com"

Listing Records

When you create a zone, the Cloud DNS service automatically creates twoRecord instances for it, providing configuration for Cloud DNSnameservers. Let's take a look at these records.

require"google/cloud/dns"dns=Google::Cloud::Dns.newzone=dns.zone"example-com"records=zone.recordsrecords.count#=> 2records.map&:type#=> ["NS", "SOA"]zone.records.first.data.count#=> 4zone.records.first.data#=> ["ns-cloud-d1.googledomains.com.", ...]

Note thatGoogle::Cloud::Dns::Record#data returns an array. The CloudDNS service only allows the zone to have one Record instance for each nameand type combination. It supports multiple "resource records" (in thiscase, the four nameserver addresses) via thisdata collection.

Managing Records

You can easily add your own records to the zone. Each call toGoogle::Cloud::Dns::Zone#add results in a new Cloud DNS Change instance.

require"google/cloud/dns"dns=Google::Cloud::Dns.newzone=dns.zone"example-com"change=zone.add"www","A",86400,["1.2.3.4"]change.additions.map&:type#=> ["A", "SOA"]change.deletions.map&:type#=> ["SOA"]

Whenever you change the set of records belonging to a zone, the zone'sstart of authority (SOA) record should be updated with a higher serialnumber. The google-cloud library automates this update for you, deletingthe old SOA record and adding an updated one, as shown in the exampleabove. You can disable or modify this behavior, of course. SeeGoogle::Cloud::Dns::Zone#update for details.

You can retrieve records by name and type. The name argument can be asubdomain (e.g.,www) fragment for convenience, but notice that theretrieved record's domain name is always fully-qualified.

require"google/cloud/dns"dns=Google::Cloud::Dns.newzone=dns.zone"example-com"records=zone.records"www","A"records.first.name#=> "www.example.com."

You can useGoogle::Cloud::Dns::Zone#replace to update thettl anddata for a record.

require"google/cloud/dns"dns=Google::Cloud::Dns.newzone=dns.zone"example-com"change=zone.replace"www","A",86400,["5.6.7.8"]

Or, you can useGoogle::Cloud::Dns::Zone#modify to update just thettlordata, without the risk of inadvertently changing values that you wishto leave unchanged.

require"google/cloud/dns"dns=Google::Cloud::Dns.newzone=dns.zone"example-com"change=zone.modify"www","A"do|r|r.ttl=3600# change only the TTLend

You can also delete records by name and type.

require"google/cloud/dns"dns=Google::Cloud::Dns.newzone=dns.zone"example-com"change=zone.remove"www","A"record=change.deletions.first

The best way to add, remove, and update multiple records in a singletransaction is to callGoogle::Cloud::Dns::Zone#update with a block. SeeGoogle::Cloud::Dns::Zone::Transaction.

require"google/cloud/dns"dns=Google::Cloud::Dns.newzone=dns.zone"example-com"change=zone.updatedo|tx|tx.add"www","A",86400,"1.2.3.4"tx.remove"example.com.","TXT"tx.replace"example.com.","MX",86400,["10 mail1.example.com.","20 mail2.example.com."]tx.modify"www.example.com.","CNAME"do|r|r.ttl=86400# only change the TTLendend

Finally, you can add and delete records by reference, usingGoogle::Cloud::Dns::Zone#update.

require"google/cloud/dns"dns=Google::Cloud::Dns.newzone=dns.zone"example-com"to_add=zone.record"www","AAAA",86400,["2607:f8b0:400a:801::1005"]to_delete=zone.records"www","A"change=zone.updateto_add,to_delete

Listing Changes

Because the transactions you execute against your zone do not alwayscomplete immediately, you can retrieve and inspect changes.

require"google/cloud/dns"dns=Google::Cloud::Dns.newzone=dns.zone"example-com"changes=zone.changeschanges.eachdo|change|puts"#{change.id} -#{change.started_at} -#{change.status}"end

Importing and exporting zone files

You can import from a zone file. Because the Cloud DNS service only allowsthe zone to have one Record instance for each name and type combination,lines may be merged as needed into records with multipledata values.

require"google/cloud/dns"dns=Google::Cloud::Dns.newzone=dns.zone"example-com"change=zone.import"path/to/db.example.com"

You can also export to a zone file.

require"google/cloud/dns"dns=Google::Cloud::Dns.newzone=dns.zone"example-com"zone.export"path/to/db.example.com"

Configuring retries and timeout

You can configure how many times API requests may be automaticallyretried. When an API request fails, the response will be inspected to seeif the request meets criteria indicating that it may succeed on retry,such as500 and503 status codes or a specific internal error codesuch asrateLimitExceeded. If it meets the criteria, the request will beretried after a delay. If another error occurs, the delay will beincreased before a subsequent attempt, until theretries limit isreached.

You can also set the requesttimeout value in seconds.

require"google/cloud/dns"dns=Google::Cloud::Dns.newretries:10,timeout:120

Additional information

Google Cloud DNS can be configured to use logging. To learn more, see theLogging guide.