Cloud DNS API - Class Google::Cloud::Dns::Zone (v1.0.0)

Reference documentation and code samples for the Cloud DNS API class Google::Cloud::Dns::Zone.

DNS Zone

The managed zone is the container for DNS records for the same DNS name suffix and has a set of name servers that accept and responds to queries. A project can have multiple managed zones, but they must each have a unique name.

Inherits

  • Object

Example

require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
zone.records.each do |record|
  puts record.name
end

Methods

#add

def add(name, type, ttl, data, skip_soa: nil, soa_serial: nil) -> Google::Cloud::Dns::Change

Adds a record to the Zone. In order to update existing records, or add and delete records in the same transaction, use #update.

This operation automatically updates the SOA record serial number unless prevented with the skip_soa option. See #update for details.

Parameters
  • name (String) — The owner of the record. For example: example.com..
  • type (String) — The identifier of a supported record type. For example: A, AAAA, CNAME, MX, or TXT.
  • ttl (Integer) — The number of seconds that the record can be cached by resolvers.
  • data (String, Array<String>) — The resource record data, as determined by type and defined in RFC 1035 (section 5) and RFC 1034 (section 3.6.1). For example: 192.0.2.1 or example.com..
  • skip_soa (Boolean) (defaults to: nil) — Do not automatically update the SOA record serial number. See #update for details.
  • soa_serial (Integer+, lambda, Proc) (defaults to: nil) — A value (or a lambda or Proc returning a value) for the new SOA record serial number. See #update for details.
Returns
Example 
require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
change = zone.add "example.com.", "A", 86400, ["1.2.3.4"]

#change

def change(change_id) -> Google::Cloud::Dns::Change, nil
Aliases

Retrieves an existing change by id.

Parameter
  • change_id (String) — The id of a change.
Returns
Example 
require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
change = zone.change "2"
if change
  puts "#{change.id} - #{change.started_at} - #{change.status}"
end

#changes

def changes(token: nil, max: nil, order: nil) -> Array<Google::Cloud::Dns::Change>
Aliases

Retrieves the list of changes belonging to the zone.

Parameters
  • token (String) (defaults to: nil) — A previously-returned page token representing part of the larger set of results to view.
  • max (Integer) (defaults to: nil) — Maximum number of changes to return.
  • order (Symbol, String) (defaults to: nil) —

    Sort the changes by change sequence.

    Acceptable values are:

    • asc - Sort by ascending change sequence
    • desc - Sort by descending change sequence
Returns
Examples 
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

The changes can be sorted by change sequence:

require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
changes = zone.changes order: :desc

Retrieve all changes: (See Change::List#all)

require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
changes = zone.changes
changes.all do |change|
  puts "#{change.id} - #{change.status}"
end

#clear!

def clear!()

Removes non-essential records from the zone. Only NS and SOA records will be kept.

Example 
require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
zone.clear!

#created_at

def created_at()

The time that this resource was created on the server.

#delete

def delete(force: false) -> Boolean

Permanently deletes the zone.

Parameter
  • force (Boolean) (defaults to: false) — If true, ensures the deletion of the zone by first deleting all records. If false and the zone contains non-essential records, the request will fail. Default is false.
Returns
  • (Boolean) — Returns true if the zone was deleted.
Examples 
require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
zone.delete

The zone can be forcefully deleted with the force option:

require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
zone.delete force: true

#description

def description()

A string of at most 1024 characters associated with this resource for the user's convenience. Has no effect on the managed zone's function.

#dns

def dns()

The DNS name of this managed zone, for instance "example.com.".

#export

def export(path) -> File

Exports the zone to a local DNS zone file.

Parameter
  • path (String) — The path on the local file system to write the data to. The path provided must be writable.
Returns
  • (File) — An object on the local file system.
Example 
require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"

zone.export "path/to/db.example.com"

#find_change

def find_change(change_id) -> Google::Cloud::Dns::Change, nil
Alias Of: #change

Retrieves an existing change by id.

Parameter
  • change_id (String) — The id of a change.
Returns
Example 
require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
change = zone.change "2"
if change
  puts "#{change.id} - #{change.started_at} - #{change.status}"
end

#find_changes

def find_changes(token: nil, max: nil, order: nil) -> Array<Google::Cloud::Dns::Change>
Alias Of: #changes

Retrieves the list of changes belonging to the zone.

Parameters
  • token (String) (defaults to: nil) — A previously-returned page token representing part of the larger set of results to view.
  • max (Integer) (defaults to: nil) — Maximum number of changes to return.
  • order (Symbol, String) (defaults to: nil) —

    Sort the changes by change sequence.

    Acceptable values are:

    • asc - Sort by ascending change sequence
    • desc - Sort by descending change sequence
Returns
Examples 
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

The changes can be sorted by change sequence:

require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
changes = zone.changes order: :desc

Retrieve all changes: (See Change::List#all)

require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
changes = zone.changes
changes.all do |change|
  puts "#{change.id} - #{change.status}"
end

#find_records

def find_records(name = nil, type = nil, token: nil, max: nil) -> Array<Google::Cloud::Dns::Record>
Alias Of: #records

Retrieves the list of records belonging to the zone. Records can be filtered 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.

Parameters
  • name (String) — Return only records with this domain or subdomain name.
  • type (String) — Return only records with this record type. If present, the name parameter must also be present.
  • token (String) (defaults to: nil) — A previously-returned page token representing part of the larger set of results to view.
  • max (Integer) (defaults to: nil) — Maximum number of records to return.
Returns
Examples 
require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
records = zone.records
records.each do |record|
  puts record.name
end

Records can be filtered by name and type:

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."

Retrieve all records:

require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
records = zone.records "example.com."

records.all do |record|
  puts record.name
end

#fqdn

def fqdn(domain_name) -> String

This helper converts the given domain name or subdomain (e.g., www) fragment to a fully qualified domain name (FQDN) for the zone's #dns. If the argument is already a FQDN, it is returned unchanged.

Parameter
  • domain_name (String) — The name to convert to a fully qualified domain name.
Returns
  • (String) — A fully qualified domain name.
Example 
require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
zone.fqdn "www" #=> "www.example.com."
zone.fqdn "@" #=> "example.com."
zone.fqdn "mail.example.com." #=> "mail.example.com."

#get_change

def get_change(change_id) -> Google::Cloud::Dns::Change, nil
Alias Of: #change

Retrieves an existing change by id.

Parameter
  • change_id (String) — The id of a change.
Returns
Example 
require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
change = zone.change "2"
if change
  puts "#{change.id} - #{change.started_at} - #{change.status}"
end

#id

def id()

Unique identifier for the resource; defined by the server.

#import

def import(path_or_io, only: nil, except: nil, skip_soa: nil, soa_serial: nil) -> Google::Cloud::Dns::Change

Imports resource records from a DNS zone file, adding the new records to the zone, without removing any existing records from the zone.

Because the Google Cloud DNS API only accepts a single resource record for each name and type combination (with multiple data elements), the zone file's records are merged as necessary. During this merge, the lowest ttl of the merged records is used. If none of the merged records have a ttl value, the zone file's global TTL is used for the record.

The zone file's SOA and NS records are not imported, because the zone was given SOA and NS records when it was created. These generated records point to Cloud DNS name servers.

This operation automatically updates the SOA record serial number unless prevented with the skip_soa option. See #update for details.

The Google Cloud DNS service requires that record names and data use fully-qualified addresses. The @ symbol is not accepted, nor are unqualified subdomain addresses like www. If your zone file contains such values, you may need to pre-process it in order for the import operation to succeed.

Parameters
  • path_or_io (String, IO) — The path to a zone file on the filesystem, or an IO instance from which zone file data can be read.
  • only (String, Array<String>) (defaults to: nil) — Include only records of this type or types.
  • except (String, Array<String>) (defaults to: nil) — Exclude records of this type or types.
  • skip_soa (Boolean) (defaults to: nil) — Do not automatically update the SOA record serial number. See #update for details.
  • soa_serial (Integer, lambda, Proc) (defaults to: nil) — A value (or a lambda or Proc returning a value) for the new SOA record serial number. See #update for details.
Returns
Example 
require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
change = zone.import "path/to/db.example.com"

#modify

def modify(name, type, skip_soa: nil, soa_serial: nil, &block) { |record| ... } -> Google::Cloud::Dns::Change

Modifies records on the Zone. Records matching the name and type are yielded to the block where they can be modified.

This operation automatically updates the SOA record serial number unless prevented with the skip_soa option. See #update for details.

Parameters
  • name (String) — The owner of the record. For example: example.com..
  • type (String) — The identifier of a supported record type. For example: A, AAAA, CNAME, MX, or TXT.
  • skip_soa (Boolean) (defaults to: nil) — Do not automatically update the SOA record serial number. See #update for details.
  • soa_serial (Integer+, lambda, Proc) (defaults to: nil) — A value (or a lambda or Proc returning a value) for the new SOA record serial number. See #update for details.
Yields
  • (record) — a block yielding each matching record
Yield Parameter
  • record (Record) — the record to be modified
Returns
Example 
require "google/cloud/dns"

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

#name

def name()

User assigned name for this resource. Must be unique within the project. The name must be 1-32 characters long, must begin with a letter, end with a letter or digit, and only contain lowercase letters, digits or dashes.

#name_server_set

def name_server_set()

Optionally specifies the NameServerSet for this ManagedZone. A NameServerSet is a set of DNS name servers that all host the same ManagedZones. Most users will leave this field unset.

#name_servers

def name_servers()

Delegate your managed_zone to these virtual name servers; defined by the server.

#new_record

def new_record(name, type, ttl, data) -> Google::Cloud::Dns::Record
Alias Of: #record

Creates a new, unsaved Record that can be added to a Zone. See #update.

Returns
Example 
require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
record = zone.record "example.com.", "A", 86400, ["1.2.3.4"]
zone.update record

#record

def record(name, type, ttl, data) -> Google::Cloud::Dns::Record
Aliases

Creates a new, unsaved Record that can be added to a Zone. See #update.

Returns
Example 
require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
record = zone.record "example.com.", "A", 86400, ["1.2.3.4"]
zone.update record

#records

def records(name = nil, type = nil, token: nil, max: nil) -> Array<Google::Cloud::Dns::Record>
Aliases

Retrieves the list of records belonging to the zone. Records can be filtered 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.

Parameters
  • name (String) — Return only records with this domain or subdomain name.
  • type (String) — Return only records with this record type. If present, the name parameter must also be present.
  • token (String) (defaults to: nil) — A previously-returned page token representing part of the larger set of results to view.
  • max (Integer) (defaults to: nil) — Maximum number of records to return.
Returns
Examples 
require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
records = zone.records
records.each do |record|
  puts record.name
end

Records can be filtered by name and type:

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."

Retrieve all records:

require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
records = zone.records "example.com."

records.all do |record|
  puts record.name
end

#remove

def remove(name, type, skip_soa: nil, soa_serial: nil) -> Google::Cloud::Dns::Change

Removes records from the Zone. The records are looked up before they are removed. In order to update existing records, or add and remove records in the same transaction, use #update.

This operation automatically updates the SOA record serial number unless prevented with the skip_soa option. See #update for details.

Parameters
  • name (String) — The owner of the record. For example: example.com..
  • type (String) — The identifier of a supported record type. For example: A, AAAA, CNAME, MX, or TXT.
  • skip_soa (Boolean) (defaults to: nil) — Do not automatically update the SOA record serial number. See #update for details.
  • soa_serial (Integer+, lambda, Proc) (defaults to: nil) — A value (or a lambda or Proc returning a value) for the new SOA record serial number. See #update for details.
Returns
Example 
require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
change = zone.remove "example.com.", "A"

#replace

def replace(name, type, ttl, data, skip_soa: nil, soa_serial: nil) -> Google::Cloud::Dns::Change

Replaces existing records on the Zone. Records matching the name and type are replaced. In order to update existing records, or add and delete records in the same transaction, use #update.

This operation automatically updates the SOA record serial number unless prevented with the skip_soa option. See #update for details.

Parameters
  • name (String) — The owner of the record. For example: example.com..
  • type (String) — The identifier of a supported record type. For example: A, AAAA, CNAME, MX, or TXT.
  • ttl (Integer) — The number of seconds that the record can be cached by resolvers.
  • data (String, Array<String>) — The resource record data, as determined by type and defined in RFC 1035 (section 5) and RFC 1034 (section 3.6.1). For example: 192.0.2.1 or example.com..
  • skip_soa (Boolean) (defaults to: nil) — Do not automatically update the SOA record serial number. See #update for details.
  • soa_serial (Integer+, lambda, Proc) (defaults to: nil) — A value (or a lambda or Proc returning a value) for the new SOA record serial number. See #update for details.
Returns
Example 
require "google/cloud/dns"

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

#update

def update(additions = [], deletions = [], skip_soa: nil, soa_serial: nil) { |tx| ... } -> Google::Cloud::Dns::Change

Adds and removes Records from the zone. All changes are made in a single API request.

The best way to add, remove, and update multiple records in a single transaction is with a block. See Transaction.

If the SOA record for the zone is not present in additions or deletions (and if present in one, it should be present in the other), it will be added to both, and its serial number will be incremented by adding 1. This update to the SOA record can be prevented with the skip_soa option. To provide your own value or behavior for the new serial number, use the soa_serial option.

Parameters
  • additions (Record, Array<Record>) — The Record or array of records to add.
  • deletions (Record, Array<Record>) — The Record or array of records to remove.
  • skip_soa (Boolean) (defaults to: nil) — Do not automatically update the SOA record serial number.
  • soa_serial (Integer, lambda, Proc) (defaults to: nil) — A value (or a lambda or Proc returning a value) for the new SOA record serial number.
Yields
  • (tx) — a block yielding a new transaction
Yield Parameter
Returns
Examples

Using a block:

require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
change = zone.update do |tx|
  tx.add     "example.com.", "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 |cname|
    cname.ttl = 86400 # only change the TTL
  end
end

Or you can provide the record objects to add and remove:

require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
new_record = zone.record "example.com.", "A", 86400, ["1.2.3.4"]
old_record = zone.record "example.com.", "A", 18600, ["1.2.3.4"]
change = zone.update [new_record], [old_record]

Using a lambda or Proc to update current SOA serial number:

require "google/cloud/dns"

dns = Google::Cloud::Dns.new
zone = dns.zone "example-com"
new_record = zone.record "example.com.", "A", 86400, ["1.2.3.4"]
change = zone.update new_record, soa_serial: lambda { |sn| sn + 10 }