Class: Gcloud::Dns::Zone

Inherits:
Object
  • Object
show all
Defined in:
lib/gcloud/dns/zone.rb,
lib/gcloud/dns/zone/list.rb,
lib/gcloud/dns/zone/transaction.rb

Overview

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

Examples:

require "gcloud"

gcloud = Gcloud.new
dns = gcloud.dns
zone = dns.zone "example-com"
zone.records.each do |record|
  puts record.name
end

See Also:

Defined Under Namespace

Classes: List, Transaction

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Zone

Returns a new instance of Zone.



56
57
58
59
 
# File 'lib/gcloud/dns/zone.rb', line 56

def initialize
  @service = nil
  @gapi = {}
end

Instance Attribute Details

#gapi ⇒ Object 



52
53
54
 
# File 'lib/gcloud/dns/zone.rb', line 52

def gapi
  @gapi
end

#service ⇒ Object 



48
49
50
 
# File 'lib/gcloud/dns/zone.rb', line 48

def service
  @service
end

Class Method Details

.from_gapi(gapi, conn) ⇒ Object 



701
702
703
704
705
706
 
# File 'lib/gcloud/dns/zone.rb', line 701

def self.from_gapi gapi, conn
  new.tap do |f|
    f.gapi = gapi
    f.service = conn
  end
end

Instance Method Details

#add(name, type, ttl, data, skip_soa: nil, soa_serial: nil) ⇒ Gcloud::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.

Examples:

require "gcloud"

gcloud = Gcloud.new
dns = gcloud.dns
zone = dns.zone "example-com"
change = zone.add "example.com.", "A", 86400, ["1.2.3.4"]

Parameters:

  • name (String) —

    The owner of the record. For example: ‘example.com.`.

  • type (String) —

    The identifier of a [supported record type](cloud.google.com/dns/what-is-cloud-dns). 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)](tools.ietf.org/html/rfc1035#section-5) and [RFC 1034 (section 3.6.1)](tools.ietf.org/html/rfc1034#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:



547
548
549
550
 
# File 'lib/gcloud/dns/zone.rb', line 547

def add name, type, ttl, data, skip_soa: nil, soa_serial: nil
  update [record(name, type, ttl, data)], [],
         skip_soa: skip_soa, soa_serial: soa_serial
end

#change(change_id) ⇒ Gcloud::Dns::Change? Also known as: find_change, get_change

Retrieves an existing change by id.

Examples:

require "gcloud"

gcloud = Gcloud.new
dns = gcloud.dns
zone = dns.zone "example-com"
change = zone.change "2"
if change
  puts "#{change.id} - #{change.started_at} - #{change.status}"
end

Parameters:

  • change_id (String) —

    The id of a change.

Returns:



189
190
191
192
193
194
195
 
# File 'lib/gcloud/dns/zone.rb', line 189

def change change_id
  ensure_service!
  gapi = service.get_change id, change_id
  Change.from_gapi gapi, self
rescue Gcloud::NotFoundError
  nil
end

#changes(token: nil, max: nil, order: nil) ⇒ Array<Gcloud::Dns::Change> Also known as: find_changes

Retrieves the list of changes belonging to the zone.

Examples:

require "gcloud"

gcloud = Gcloud.new
dns = gcloud.dns
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 "gcloud"

gcloud = Gcloud.new
dns = gcloud.dns
zone = dns.zone "example-com"
changes = zone.changes order: :desc

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

require "gcloud"

gcloud = Gcloud.new
dns = gcloud.dns
zone = dns.zone "example-com"
changes = zone.changes
changes.all do |change|
  puts "#{change.name} - #{change.status}"
end

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:



244
245
246
247
248
249
250
251
252
253
 
# File 'lib/gcloud/dns/zone.rb', line 244

def changes token: nil, max: nil, order: nil
  ensure_service!
  # Fix the sort options
  order = adjust_change_sort_order order
  sort  = "changeSequence" if order
  # Continue with the API call
  gapi = service.list_changes id, token: token, max: max,
                                  order: order, sort: sort
  Change::List.from_gapi gapi, self, max, order
end

#clear! ⇒ Object

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

Examples:

require "gcloud"

gcloud = Gcloud.new
dns = gcloud.dns
zone = dns.zone "example-com"
zone.clear!



164
165
166
167
168
 
# File 'lib/gcloud/dns/zone.rb', line 164

def clear!
  non_essential = records.all.reject { |r| %w(SOA NS).include?(r.type) }
  change = update [], non_essential
  change.wait_until_done! unless change.nil?
end

#created_at ⇒ Object

The time that this resource was created on the server.



113
114
115
116
117
 
# File 'lib/gcloud/dns/zone.rb', line 113

def created_at
  Time.parse @gapi.creation_time
rescue
  nil
end

#delete(force: false) ⇒ Boolean

Permanently deletes the zone.

Examples:

require "gcloud"

gcloud = Gcloud.new
dns = gcloud.dns
zone = dns.zone "example-com"
zone.delete

The zone can be forcefully deleted with the ‘force` option:

require "gcloud"

gcloud = Gcloud.new
dns = gcloud.dns
zone = dns.zone "example-com"
zone.delete force: true

Parameters:

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



144
145
146
147
148
149
150
 
# File 'lib/gcloud/dns/zone.rb', line 144

def delete force: false
  clear! if force

  ensure_service!
  service.delete_zone id
  true
end

#description ⇒ Object

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.



89
90
91
 
# File 'lib/gcloud/dns/zone.rb', line 89

def description
  @gapi.description
end

#dns ⇒ Object

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



81
82
83
 
# File 'lib/gcloud/dns/zone.rb', line 81

def dns
  @gapi.dns_name
end

#export(path) ⇒ File

Exports the zone to a local [DNS zone file](en.wikipedia.org/wiki/Zone_file).

Examples:

require "gcloud"

gcloud = Gcloud.new
dns = gcloud.dns
zone = dns.zone "example-com"

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

Parameters:

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



352
353
354
355
356
 
# File 'lib/gcloud/dns/zone.rb', line 352

def export path
  File.open path, "w" do |f|
    f.write to_zonefile
  end
end

#fqdn(domain_name) ⇒ String

This helper converts the given domain name or subdomain (e.g., ‘www`) fragment to a [fully qualified domain name (FQDN)](en.wikipedia.org/wiki/Fully_qualified_domain_name) for the zone’s #dns. If the argument is already a FQDN, it is returned unchanged.

Examples:

require "gcloud"

gcloud = Gcloud.new
dns = gcloud.dns
zone = dns.zone "example-com"
zone.fqdn "www" #=> "www.example.com."
zone.fqdn "@" #=> "example.com."
zone.fqdn "mail.example.com." #=> "mail.example.com."

Parameters:

  • domain_name (String) —

    The name to convert to a fully qualified domain name.

Returns:

  • (String) —

    A fully qualified domain name.



695
696
697
 
# File 'lib/gcloud/dns/zone.rb', line 695

def fqdn domain_name
  Service.fqdn domain_name, dns
end

#id ⇒ Object

Unique identifier for the resource; defined by the server.



64
65
66
 
# File 'lib/gcloud/dns/zone.rb', line 64

def id
  @gapi.id
end

#import(path_or_io, only: nil, except: nil, skip_soa: nil, soa_serial: nil) ⇒ Gcloud::Dns::Change

Imports resource records from a [DNS zone file](en.wikipedia.org/wiki/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.

Examples:

require "gcloud"

gcloud = Gcloud.new
dns = gcloud.dns
zone = dns.zone "example-com"
change = zone.import "path/to/db.example.com"

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:



406
407
408
409
410
411
412
 
# File 'lib/gcloud/dns/zone.rb', line 406

def import path_or_io, only: nil, except: nil,
           skip_soa: nil, soa_serial: nil
  except = (Array(except).map(&:to_s).map(&:upcase) + %w(SOA NS)).uniq
  importer = Gcloud::Dns::Importer.new self, path_or_io
  additions = importer.records only: only, except: except
  update additions, [], skip_soa: skip_soa, soa_serial: soa_serial
end

#modify(name, type, skip_soa: nil, soa_serial: nil) {|record| ... } ⇒ Gcloud::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.

Examples:

require "gcloud"

gcloud = Gcloud.new
dns = gcloud.dns
zone = dns.zone "example-com"
change = zone.modify "example.com.", "MX" do |mx|
  mx.ttl = 3600 # change only the TTL
end

Parameters:

  • name (String) —

    The owner of the record. For example: ‘example.com.`.

  • type (String) —

    The identifier of a [supported record type](cloud.google.com/dns/what-is-cloud-dns). 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 Parameters:

  • record (Record) —

    the record to be modified

Returns:



666
667
668
669
670
671
 
# File 'lib/gcloud/dns/zone.rb', line 666

def modify name, type, skip_soa: nil, soa_serial: nil
  existing = records(name, type).all.to_a
  updated = existing.map(&:dup)
  updated.each { |r| yield r }
  update updated, existing, skip_soa: skip_soa, soa_serial: soa_serial
end

#name ⇒ Object

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.



74
75
76
 
# File 'lib/gcloud/dns/zone.rb', line 74

def name
  @gapi.name
end

#name_server_set ⇒ Object

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.



106
107
108
 
# File 'lib/gcloud/dns/zone.rb', line 106

def name_server_set
  @gapi.name_server_set
end

#name_servers ⇒ Object

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



97
98
99
 
# File 'lib/gcloud/dns/zone.rb', line 97

def name_servers
  Array(@gapi.name_servers)
end

#record(name, type, ttl, data) ⇒ Gcloud::Dns::Record Also known as: new_record

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

Examples:

require "gcloud"

gcloud = Gcloud.new
dns = gcloud.dns
zone = dns.zone "example-com"
record = zone.record "example.com.", "A", 86400, ["1.2.3.4"]
zone.add record

Returns:



329
330
331
 
# File 'lib/gcloud/dns/zone.rb', line 329

def record name, type, ttl, data
  Gcloud::Dns::Record.new fqdn(name), type, ttl, data
end

#records(name = nil, type = nil, token: nil, max: nil) ⇒ Array<Gcloud::Dns::Record> Also known as: find_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.

Examples:

require "gcloud"

gcloud = Gcloud.new
dns = gcloud.dns
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 "gcloud"

gcloud = Gcloud.new
dns = gcloud.dns
zone = dns.zone "example-com"
records = zone.records "www", "A"
records.first.name #=> "www.example.com."

Retrieve all records: (See Record::List#all)

require "gcloud"

gcloud = Gcloud.new
dns = gcloud.dns
zone = dns.zone "example-com"
records = zone.records "example.com."

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

Parameters:

  • name (String) (defaults to: nil) —

    Return only records with this domain or subdomain name.

  • type (String) (defaults to: nil) —

    Return only records with this [record type](cloud.google.com/dns/what-is-cloud-dns). 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:



305
306
307
308
309
310
311
312
 
# File 'lib/gcloud/dns/zone.rb', line 305

def records name = nil, type = nil, token: nil, max: nil
  ensure_service!

  name = fqdn(name) if name

  gapi = service.list_records id, name, type, token: token, max: max
  Record::List.from_gapi gapi, self, name, type, max
end

#remove(name, type, skip_soa: nil, soa_serial: nil) ⇒ Gcloud::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.

Examples:

require "gcloud"

gcloud = Gcloud.new
dns = gcloud.dns
zone = dns.zone "example-com"
change = zone.remove "example.com.", "A"

Parameters:

  • name (String) —

    The owner of the record. For example: ‘example.com.`.

  • type (String) —

    The identifier of a [supported record type](cloud.google.com/dns/what-is-cloud-dns). 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:



581
582
583
584
 
# File 'lib/gcloud/dns/zone.rb', line 581

def remove name, type, skip_soa: nil, soa_serial: nil
  update [], records(name, type).all.to_a,
         skip_soa: skip_soa, soa_serial: soa_serial
end

#replace(name, type, ttl, data, skip_soa: nil, soa_serial: nil) ⇒ Gcloud::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.

Examples:

require "gcloud"

gcloud = Gcloud.new
dns = gcloud.dns
zone = dns.zone "example-com"
change = zone.replace "example.com.", "A", 86400, ["5.6.7.8"]

Parameters:

  • name (String) —

    The owner of the record. For example: ‘example.com.`.

  • type (String) —

    The identifier of a [supported record type](cloud.google.com/dns/what-is-cloud-dns). 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)](tools.ietf.org/html/rfc1035#section-5) and [RFC 1034 (section 3.6.1)](tools.ietf.org/html/rfc1034#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:



623
624
625
626
627
 
# File 'lib/gcloud/dns/zone.rb', line 623

def replace name, type, ttl, data, skip_soa: nil, soa_serial: nil
  update [record(name, type, ttl, data)],
         records(name, type).all.to_a,
         skip_soa: skip_soa, soa_serial: soa_serial
end

#to_zonefile ⇒ Object 



630
631
632
 
# File 'lib/gcloud/dns/zone.rb', line 630

def to_zonefile
  records.all.map(&:to_zonefile_records).flatten.join("\n")
end

#update(additions = [], deletions = [], skip_soa: nil, soa_serial: nil) {|tx| ... } ⇒ Gcloud::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](cloud.google.com/dns/records) 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.

Examples:

Using a block:

require "gcloud"

gcloud = Gcloud.new
dns = gcloud.dns
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 "gcloud"

gcloud = Gcloud.new
dns = gcloud.dns
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 the current SOA serial number:

require "gcloud"

gcloud = Gcloud.new
dns = gcloud.dns
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 }

Parameters:

  • additions (Record, Array<Record>) (defaults to: []) —

    The Record or array of records to add.

  • deletions (Record, Array<Record>) (defaults to: []) —

    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 Parameters:

Returns:



480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
 
# File 'lib/gcloud/dns/zone.rb', line 480

def update additions = [], deletions = [], skip_soa: nil, soa_serial: nil
  # Handle only sending in options
  if additions.is_a?(::Hash) && deletions.empty? && options.empty?
    options = additions
    additions = []
  elsif deletions.is_a?(::Hash) && options.empty?
    options = deletions
    deletions = []
  end

  additions = Array additions
  deletions = Array deletions

  if block_given?
    updater = Zone::Transaction.new self
    yield updater
    additions += updater.additions
    deletions += updater.deletions
  end

  to_add    = additions - deletions
  to_remove = deletions - additions
  return nil if to_add.empty? && to_remove.empty?
  unless skip_soa || detect_soa(to_add) || detect_soa(to_remove)
    increment_soa to_add, to_remove, soa_serial
  end
  create_change to_add, to_remove
end