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.
- 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, orTXT. - 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
typeand defined in RFC 1035 (section 5) and RFC 1034 (section 3.6.1) . For example:192.0.2.1orexample.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.
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
Retrieves an existing change by id.
- change_id(String) — The id of a change.
- ( Google::Cloud::Dns::Change
, nil) — Returns
nilif the change does not exist.
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
>
Retrieves the list of changes belonging to the zone.
- 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
-
- (Array< Google::Cloud::Dns::Change >) — (See Change::List )
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.
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.
- force(Boolean) (defaults to: false)
— If
true, ensures the deletion of the zone by first deleting all records. Iffalseand the zone contains non-essential records, the request will fail. Default isfalse.
- (Boolean) — Returns
trueif the zone was deleted.
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 .
- path(String) — The path on the local file system to write the data to. The path provided must be writable.
- (File) — An object on the local file system.
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
Retrieves an existing change by id.
- change_id(String) — The id of a change.
- ( Google::Cloud::Dns::Change
, nil) — Returns
nilif the change does not exist.
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
>
Retrieves the list of changes belonging to the zone.
- 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
-
- (Array< Google::Cloud::Dns::Change >) — (See Change::List )
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
>
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.
- name(String) — Return only records with this domain or subdomain name.
- type(String) — Return only records with this record
type
. If present,
the
nameparameter 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.
- (Array< Google::Cloud::Dns::Record >) — (See Record::List )
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.
- domain_name(String) — The name to convert to a fully qualified domain name.
- (String) — A fully qualified domain name.
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
Retrieves an existing change by id.
- change_id(String) — The id of a change.
- ( Google::Cloud::Dns::Change
, nil) — Returns
nilif the change does not exist.
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.
- 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.
- ( Google::Cloud::Dns::Change ) — A new change adding the imported Record instances.
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.
- 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, orTXT. - 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.
- (record) — a block yielding each matching record
- record( Record ) — the record to be modified
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
Creates a new, unsaved Record that can be added to a Zone. See #update .
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
Creates a new, unsaved Record that can be added to a Zone. See #update .
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
>
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.
- name(String) — Return only records with this domain or subdomain name.
- type(String) — Return only records with this record
type
. If present,
the
nameparameter 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.
- (Array< Google::Cloud::Dns::Record >) — (See Record::List )
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.
- 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, orTXT. - 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.
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.
- 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, orTXT. - 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
typeand defined in RFC 1035 (section 5) and RFC 1034 (section 3.6.1) . For example:192.0.2.1orexample.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.
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.
- 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.
- (tx) — a block yielding a new transaction
- tx( Zone::Transaction ) — the transaction object
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 }
