Skip to content

Proposal: gcloud.dns

Jump to bottom Edit New page
JJ Geewax edited this page May 1, 2014 · 2 revisions

High level

Resources

Relationship

                           _____________
                           |  Project  |
                           ‾‾‾‾‾‾|‾‾‾‾‾‾
                         _______/|\_______
                         |  ManagedZone  |
                         ‾‾/‾‾‾‾‾‾‾‾‾‾‾\‾‾
        _________________/|\___     ___/|\______
        |  ResourceRecordSet  |     |  Change  |
        ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾     ‾‾‾‾‾‾‾‾‾‾‾‾

Classes we should create

  1. Project (maybe) to keep track of defaults, quota, etc.
  • We'd need to juggle this across all the other services in gcloud though.
  • Projects would have a list of Zones.
  1. Zone (not ManagedZone).
  • We know what a zone is, not worried about confusion here (even if we expose gcloud.compute.zone).
  • Zones would have a list of Records.
  1. Record for the purpose of building a record string.
  • The record itself boils down just to a string.
  • Note: See if there is a library that already deals with parsing and rendering strings conforming to RFC 1035 (section 5) and RFC 1034 (section 3.6.1).
  1. Change (under the hood only) for the purpose of simplifying API calls.
  • Users shouldn't deal with this class and we shouldn't expose it if at all possible.

Common tasks

Establishing a connection

>>> from gcloud import dns
>>> connection = dns.get_connection(client_email, private_key_path)

Referencing a project

Given a connection

>>> project = connection.get_project(project_id)

Using a shortcut method

>>> from gcloud import dns
>>> project = dns.get_project(project_id, client_email, private_key_path)

Referencing a zone

Given a project

>>> project = ...
>>> zone = project.get_zone('example-zone-name')

Using a shortcut method

>>> from gcloud import dns
>>> zone = dns.get_zone('example-zone-name', project_name, client_email, private_key_path)

Questions

  1. Can a Zone have multiple DNS names?
  2. Can we get a zone by it's DNS name?

Creating a zone

>>> zone = project.create_zone('example-zone-name', 'example.com.')

Building a 'record'

Option 1 (mutable)

>>> record = Record()
>>> record.type('A').name('www')
>>> record.ttl(minutes=60)
>>> record.data(['1.2.3.4', '1.2.3.5'])
>>> record.add_data('1.2.3.6')
>>> print record
www 3600 IN A 1.2.3.4 1.2.3.5 1.2.3.6

Option 2 (immutable)

>>> record = Record()
>>> record = record.type('A').name('www')
>>> record = record.ttl(minutes=60)
>>> record = record.data(['1.2.3.4', '1.2.3.5'])
>>> record = record.add_data('1.2.3.6')
>>> print record
www 3600 IN A 1.2.3.4 1.2.3.5 1.2.3.6

Adding records to a zone

>>> zone = ....  # Get a zone somehow for DNS name = example.org.
>>> zone.add_record(record)  # Record as defined above.
>>> zone.add_cname('home', 'c.storage.googleapis.com.', 600)
>>> print zone
example.org. IN SOA <SOA details here>
www.example.org. 3600 IN A 1.2.3.4 1.2.3.5 1.2.3.6
home.example.org. 600 IN CNAME c.storage.googleapis.com.

Removing records from a zone

>>> zone.remove_record('www')  # Removes all records for `www`.
>>> print zone
example.org. IN SOA <SOA details here>
home.example.org. 600 IN CNAME c.storage.googleapis.com.
>>> zone.remove_record('www', '1.2.3.4')
>>> print zone
example.org. IN SOA <SOA details here>
www.example.org. 3600 IN A 1.2.3.5 1.2.3.6
home.example.org. 600 IN CNAME c.storage.googleapis.com.

Saving a zone

Calling .save() should create a Change under the hood with the deltas from the last persisted state.

>>> zone.save()

What happens if the local version gets out of sync?

For example:

  1. Clients 1 and 2 both load the zone, no records exist.
  2. Client 1 creates a change that adds A 9.9.9.9 to www.
  3. Client 2 creates a change that adds A 1.1.1.1 to www.

What is the state of the zone?

  1. A 1.1.1.1 9.9.9.9 ? (If we reconcile changes.)
  2. A 1.1.1.1 ? (If we overwrite changes.)
  3. A 9.9.9.9 ? (If we reject the second change.)

Client-side error checking

In general, we should try to err on the side of being too permissive on the client side, and catching errors coming back from the Cloud DNS service.

Record types

  • It's probably worthwhile to check that when setting a type of a record, we throw an error if it's invalid.

Invalid characters in data

  • Any character that isn't valid in a DNS name or IP address (v4 or v6) should throw an error.

References

Copyright Google, Inc

Add a custom sidebar

Clone this wiki locally