Module: Google::Cloud::Dns

Defined in:
lib/google/cloud/dns.rb,
lib/google/cloud/dns/zone.rb,
lib/google/cloud/dns/change.rb,
lib/google/cloud/dns/record.rb,
lib/google/cloud/dns/project.rb,
lib/google/cloud/dns/service.rb,
lib/google/cloud/dns/version.rb,
lib/google/cloud/dns/importer.rb,
lib/google/cloud/dns/zone/list.rb,
lib/google/cloud/dns/change/list.rb,
lib/google/cloud/dns/credentials.rb,
lib/google/cloud/dns/record/list.rb,
lib/google/cloud/dns/zone/transaction.rb

Overview

Google Cloud DNS

Google Cloud DNS is a high-performance, resilient, global DNS service that provides a cost-effective way to make your applications and services available to your users. This programmable, authoritative DNS service can be used to easily publish and manage DNS records using the same infrastructure relied upon by Google. To learn more, read What is Google Cloud DNS?.

The goal of google-cloud is to provide an API that is comfortable to Rubyists. Your authentication credentials are detected automatically in Google Cloud Platform environments such as Google Compute Engine, Google App Engine and Google Kubernetes Engine. In other environments you can configure authentication easily, either directly in your code or via environment variables. Read more about the options for connecting in the Authentication Guide.

Enabling Logging

To enable logging for this library, set the logger for the underlying Google API Client library. The logger that you set may be a Ruby stdlib Logger as shown below, or a Google::Cloud::Logging::Logger that will write logs to Stackdriver Logging.

If you do not set the logger explicitly and your application is running in a Rails environment, it will default to Rails.logger. Otherwise, if you do not set the logger and you are not using Rails, logging is disabled by default.

Configuring a Ruby stdlib logger:

require "logger"

my_logger = Logger.new $stderr
my_logger.level = Logger::WARN

# Set the Google API Client logger
Google::Apis.logger = my_logger

Creating Zones

To get started with Google Cloud DNS, use your DNS Project to create a new Zone. The second argument to Project#create_zone must be a unique domain name for which you can verify ownership. Substitute a domain name of your own (ending with a dot to signify that it is fully qualified) as you follow along with these examples.

require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.create_zone "example-com", "example.com."
puts zone.id # unique identifier defined by the server

For more information, see Managing Zones.

Listing Zones

You can retrieve all the zones in your project.

require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zones = dns.zones
zones.each do |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.new
zone = dns.zone "example-com"

Listing Records

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

require "google/cloud/dns"

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

Note that Record#data returns an array. The Cloud DNS service only allows the zone to have one Record instance for each name and type combination. It supports multiple "resource records" (in this case, the four nameserver addresses) via this data collection.

Managing Records

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

require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = 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's start of authority (SOA) record should be updated with a higher serial number. The google-cloud library automates this update for you, deleting the old SOA record and adding an updated one, as shown in the example above. You can disable or modify this behavior, of course. See Zone#update for details.

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

require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
records = zone.records "www", "A"
records.first.name #=> "www.example.com."

You can use Zone#replace to update the ttl and data for a record.

require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
change = zone.replace "www", "A", 86400, ["5.6.7.8"]

Or, you can use Zone#modify to update just the ttl or data, without the risk of inadvertently changing values that you wish to leave unchanged.

require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
change = zone.modify "www", "A" do |r|
  r.ttl = 3600 # change only the TTL
end

You can also delete records by name and type.

require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = 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 single transaction is to call Zone#update with a block. See Zone::Transaction.

require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
change = zone.update do |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 TTL
  end
end

Finally, you can add and delete records by reference, using Zone#update.

require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
to_add = zone.record "www", "AAAA", 86400, ["2607:f8b0:400a:801::1005"]
to_delete = zone.records "www", "A"
change = zone.update to_add, to_delete

Listing Changes

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

require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
changes = zone.changes
changes.each do |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 allows the zone to have one Record instance for each name and type combination, lines may be merged as needed into records with multiple data values.

require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = 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.new
zone = 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 automatically retried. When an API request fails, the response will be inspected to see if the request meets criteria indicating that it may succeed on retry, such as 500 and 503 status codes or a specific internal error code such as rateLimitExceeded. If it meets the criteria, the request will be retried after a delay. If another error occurs, the delay will be increased before a subsequent attempt, until the retries limit is reached.

You can also set the request timeout value in seconds.

require "google/cloud/dns"

dns = Google::Cloud::Dns.new retries: 10, timeout: 120

Defined Under Namespace

Classes: Change, Credentials, Project, Record, Zone

Constant Summary collapse

VERSION = 
"0.29.1".freeze

Class Method Summary collapse

Class Method Details

.configure {|Google::Cloud.configure.dns| ... } ⇒ Google::Cloud::Config

Configure the Google Cloud DNS library.

The following DNS configuration parameters are supported:

  • project_id - (String) Identifier for a DNS project. (The parameter project is considered deprecated, but may also be used.)
  • credentials - (String, Hash, Google::Auth::Credentials) The path to the keyfile as a String, the contents of the keyfile as a Hash, or a Google::Auth::Credentials object. (See Credentials) (The parameter keyfile is considered deprecated, but may also be used.)
  • scope - (String, Array) The OAuth 2.0 scopes controlling the set of resources and operations that the connection can access.
  • retries - (Integer) Number of times to retry requests on server error.
  • timeout - (Integer) Default timeout to use in requests.

Yields:

Returns:

  • (Google::Cloud::Config) —

    The configuration object the Google::Cloud::Dns library uses.



386
387
388
389
390
 
# File 'lib/google/cloud/dns.rb', line 386

def self.configure
  yield Google::Cloud.configure.dns if block_given?

  Google::Cloud.configure.dns
end

.new(project_id: nil, credentials: nil, scope: nil, retries: nil, timeout: nil, project: nil, keyfile: nil) ⇒ Google::Cloud::Dns::Project

Creates a new Project instance connected to the DNS service. Each call creates a new connection.

For more information on connecting to Google Cloud see the Authentication Guide.

Examples:

require "google/cloud/dns"

dns = Google::Cloud::Dns.new(
        project_id: "my-dns-project",
        credentials: "/path/to/keyfile.json"
      )

zone = dns.zone "example-com"

Parameters:

  • project_id (String) —

    Identifier for a DNS project. If not present, the default project for the credentials is used.

  • credentials (String, Hash, Google::Auth::Credentials) —

    The path to the keyfile as a String, the contents of the keyfile as a Hash, or a Google::Auth::Credentials object. (See Credentials)

  • scope (String, Array<String>) —

    The OAuth 2.0 scopes controlling the set of resources and operations that the connection can access. See Using OAuth 2.0 to Access Google APIs.

    The default scope is:

    • https://www.googleapis.com/auth/ndev.clouddns.readwrite
  • retries (Integer) —

    Number of times to retry requests on server error. The default value is 3. Optional.

  • timeout (Integer) —

    Default timeout to use in requests. Optional.

  • project (String) —

    Alias for the project_id argument. Deprecated.

  • keyfile (String) —

    Alias for the credentials argument. Deprecated.

Returns:

Raises:

  • (ArgumentError) 


344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
 
# File 'lib/google/cloud/dns.rb', line 344

def self.new project_id: nil, credentials: nil, scope: nil, retries: nil,
             timeout: nil, project: nil, keyfile: nil
  project_id ||= (project || default_project_id)
  project_id = project_id.to_s # Always cast to a string
  raise ArgumentError, "project_id is missing" if project_id.empty?

  scope ||= configure.scope
  retries ||= configure.retries
  timeout ||= configure.timeout

  credentials ||= (keyfile || default_credentials(scope: scope))
  unless credentials.is_a? Google::Auth::Credentials
    credentials = Dns::Credentials.new credentials, scope: scope
  end

  Dns::Project.new(
    Dns::Service.new(
      project_id, credentials, retries: retries, timeout: timeout
    )
  )
end