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.

require "gcloud"

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

For more information, see Managing Zones.

Defined Under Namespace

Classes: List, Transaction

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Zone

Create an empty Zone object.



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

def initialize #:nodoc:
  @connection = nil
  @gapi = {}
end

Instance Attribute Details

#connection ⇒ Object

The Connection object.



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

def connection
  @connection
end

#gapi ⇒ Object

The Google API Client object.



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

def gapi
  @gapi
end

Class Method Details

.from_gapi(gapi, conn) ⇒ Object

New Zone from a Google API Client object.



835
836
837
838
839
840
 
# File 'lib/gcloud/dns/zone.rb', line 835

def self.from_gapi gapi, conn #:nodoc:
  new.tap do |f|
    f.gapi = gapi
    f.connection = conn
  end
end

Instance Method Details

#add(name, type, ttl, data, options = {}) ⇒ Object

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

The owner of the record. For example: example.com.. (String)

type

The identifier of a supported record type. For example: A, AAAA, CNAME, MX, or TXT. (String)

ttl

The number of seconds that the record can be cached by resolvers. (Integer)

data

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.. (String or Array of String)

options

An optional Hash for controlling additional behavior. (Hash)

options[:skip_soa]

Do not automatically update the SOA record serial number. See #update for details. (Boolean)

options[:soa_serial]

A value (or a lambda or Proc returning a value) for the new SOA record serial number. See #update for details. (Integer, lambda, or Proc)

Returns

Gcloud::Dns::Change

Example

require "gcloud"

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



652
653
654
 
# File 'lib/gcloud/dns/zone.rb', line 652

def add name, type, ttl, data, options = {}
  update [record(name, type, ttl, data)], [], options
end

#change(change_id) ⇒ Object Also known as: find_change, get_change

Retrieves an existing change by id.

Parameters

change_id

The id of a change. (String)

Returns

Gcloud::Dns::Change or nil if the change does not exist

Example

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



208
209
210
211
212
213
214
215
216
 
# File 'lib/gcloud/dns/zone.rb', line 208

def change change_id
  ensure_connection!
  resp = connection.get_change id, change_id
  if resp.success?
    Change.from_gapi resp.data, self
  else
    nil
  end
end

#changes(options = {}) ⇒ Object Also known as: find_changes

Retrieves the list of changes belonging to the zone.

Parameters

options

An optional Hash for controlling additional behavior. (Hash)

options[:token]

A previously-returned page token representing part of the larger set of results to view. (String)

options[:max]

Maximum number of changes to return. (Integer)

options[:order]

Sort the changes by change sequence. (Symbol or String)

Acceptable values are:

  • asc - Sort by ascending change sequence

  • desc - Sort by descending change sequence

Returns

Array of Gcloud::Dns::Change (Gcloud::Dns::Change::List)

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

If you have a significant number of changes, you may need to paginate through them: (See Gcloud::Dns::Change::List)

require "gcloud"

gcloud = Gcloud.new
dns = gcloud.dns
zone = dns.zone "example-com"
changes = zone.changes
loop do
  changes.each do |change|
    puts "#{change.name} - #{change.status}"
  end
  break unless changes.next?
  changes = changes.next
end



281
282
283
284
285
286
287
288
289
290
291
292
293
 
# File 'lib/gcloud/dns/zone.rb', line 281

def changes options = {}
  ensure_connection!
  # Fix the sort options
  options[:order] = adjust_change_sort_order options[:order]
  options[:sort]  = "changeSequence" if options[:order]
  # Continue with the API call
  resp = connection.list_changes id, options
  if resp.success?
    Change::List.from_response resp, self
  else
    fail ApiError.from_response(resp)
  end
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!



178
179
180
181
182
 
# File 'lib/gcloud/dns/zone.rb', line 178

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["creationTime"]
rescue
  nil
end

#delete(options = {}) ⇒ Object

Permanently deletes the zone.

Parameters

options

An optional Hash for controlling additional behavior. (Hash)

options[:force]

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. (Boolean)

Returns

true if the zone was deleted.

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



153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/gcloud/dns/zone.rb', line 153

def delete options = {}
  clear! if options[:force]

  ensure_connection!
  resp = connection.delete_zone id
  if resp.success?
    true
  else
    fail ApiError.from_response(resp)
  end
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["dnsName"]
end

#export(path) ⇒ Object

Exports the zone to a local DNS zone file.

Parameters

path

The path on the local file system to write the data to. The path provided must be writable. (String)

Returns

::File object on the local file system

Examples

require "gcloud"

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

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



430
431
432
433
434
 
# File 'lib/gcloud/dns/zone.rb', line 430

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

#fqdn(domain_name) ⇒ Object

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.

Parameters

domain_name

The name to convert to a fully qualified domain name. (String)

Returns

A fully qualified domain name. (String)

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



829
830
831
 
# File 'lib/gcloud/dns/zone.rb', line 829

def fqdn domain_name
  Connection.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, options = {}) ⇒ Object

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

The path to a zone file on the filesystem, or an IO instance from which zone file data can be read. (String or IO)

options

An optional Hash for controlling additional behavior. (Hash)

options[:only]

Include only records of this type or types. (String or Array)

options[:except]

Exclude records of this type or types. (String or Array)

options[:skip_soa]

Do not automatically update the SOA record serial number. See #update for details. (Boolean)

options[:soa_serial]

A value (or a lambda or Proc returning a value) for the new SOA record serial number. See #update for details. (Integer, lambda, or Proc)

Returns

A new Change adding the imported Record instances.

Example

require "gcloud"

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



492
493
494
495
496
497
 
# File 'lib/gcloud/dns/zone.rb', line 492

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

#modify(name, type, options = {}) ⇒ Object

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

The owner of the record. For example: example.com.. (String)

type

The identifier of a supported record type. For example: A, AAAA, CNAME, MX, or TXT. (String)

options

An optional Hash for controlling additional behavior. (Hash)

options[:skip_soa]

Do not automatically update the SOA record serial number. See #update for details. (Boolean)

options[:soa_serial]

A value (or a lambda or Proc returning a value) for the new SOA record serial number. See #update for details. (Integer, lambda, or Proc)

Returns

Gcloud::Dns::Change

Example

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



795
796
797
798
799
800
 
# File 'lib/gcloud/dns/zone.rb', line 795

def modify name, type, options = {}
  existing = records(name: name, type: type).all.to_a
  updated = existing.map(&:dup)
  updated.each { |r| yield r }
  update updated, existing, options
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["nameServerSet"]
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["nameServers"])
end

#record(name, type, ttl, data) ⇒ Object Also known as: new_record

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

Returns

Gcloud::Dns::Record

Example

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



401
402
403
 
# File 'lib/gcloud/dns/zone.rb', line 401

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

#records(name = nil, type = nil, options = {}) ⇒ Object Also known as: find_records

Retrieves the list of records belonging to the zone.

Parameters

name

Return only records with this domain or subdomain name. (String)

type

Return only records with this record type. If present, the name parameter must also be present. (String)

options

An optional Hash for controlling additional behavior. (Hash)

options[:token]

A previously-returned page token representing part of the larger set of results to view. (String)

options[:max]

Maximum number of records to return. (Integer)

Returns

Array of Gcloud::Dns::Record (Gcloud::Dns::Record::List)

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

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

If you have a significant number of records, you may need to paginate through them: (See Gcloud::Dns::Record::List)

require "gcloud"

gcloud = Gcloud.new
dns = gcloud.dns
zone = dns.zone "example-com"
records = zone.records "example.com."
loop do
  records.each do |record|
    puts record.name
  end
  break unless records.next?
  records = records.next
end

Or, instead of paging manually, you can retrieve all of the pages in a single call: (See Gcloud::Dns::Record::List#all)

require "gcloud"

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



370
371
372
373
374
375
376
377
378
379
380
381
 
# File 'lib/gcloud/dns/zone.rb', line 370

def records name = nil, type = nil, options = {}
  ensure_connection!

  options = build_records_options name, type, options

  resp = connection.list_records id, options
  if resp.success?
    Record::List.from_response resp, self
  else
    fail ApiError.from_response(resp)
  end
end

#remove(name, type, options = {}) ⇒ Object

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

The owner of the record. For example: example.com.. (String)

type

The identifier of a supported record type. For example: A, AAAA, CNAME, MX, or TXT. (String)

options

An optional Hash for controlling additional behavior. (Hash)

options[:skip_soa]

Do not automatically update the SOA record serial number. See #update for details. (Boolean)

options[:soa_serial]

A value (or a lambda or Proc returning a value) for the new SOA record serial number. See #update for details. (Integer, lambda, or Proc)

Returns

Gcloud::Dns::Change

Example

require "gcloud"

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



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

def remove name, type, options = {}
  update [], records(name: name, type: type).all.to_a, options
end

#replace(name, type, ttl, data, options = {}) ⇒ Object

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

The owner of the record. For example: example.com.. (String)

type

The identifier of a supported record type. For example: A, AAAA, CNAME, MX, or TXT. (String)

ttl

The number of seconds that the record can be cached by resolvers. (Integer)

data

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.. (String or Array of String)

options

An optional Hash for controlling additional behavior. (Hash)

options[:skip_soa]

Do not automatically update the SOA record serial number. See #update for details. (Boolean)

options[:soa_serial]

A value (or a lambda or Proc returning a value) for the new SOA record serial number. See #update for details. (Integer, lambda, or Proc)

Returns

Gcloud::Dns::Change

Example

require "gcloud"

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



746
747
748
749
750
 
# File 'lib/gcloud/dns/zone.rb', line 746

def replace name, type, ttl, data, options = {}
  update [record(name, type, ttl, data)],
         records(name: name, type: type).all.to_a,
         options
end

#to_zonefile ⇒ Object

:nodoc:



752
753
754
 
# File 'lib/gcloud/dns/zone.rb', line 752

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

#update(additions = [], deletions = [], options = {}) ⇒ Object

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

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

The Record or array of records to add. (Record or Array)

deletions

The Record or array of records to remove. (Record or Array)

options

An optional Hash for controlling additional behavior. (Hash)

options[:skip_soa]

Do not automatically update the SOA record serial number. (Boolean)

options[:soa_serial]

A value (or a lambda or Proc returning a value) for the new SOA record serial number. (Integer, lambda, or Proc)

Returns

Gcloud::Dns::Change

Examples

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

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]

You can provide a lambda or Proc that receives the current SOA record serial number and returns a new 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 }



574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
 
# File 'lib/gcloud/dns/zone.rb', line 574

def update additions = [], deletions = [], options = {}
  # 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 options[:skip_soa] || detect_soa(to_add) || detect_soa(to_remove)
    increment_soa to_add, to_remove, options[:soa_serial]
  end
  create_change to_add, to_remove
end