Quick-Start¶

Workspace¶

Running through the following commands will install the latest release of octoDNS and set up a place for your config files to live. To determine if provider specific requirements are necessary see the providers table below.

$ mkdir dns
$ cd dns
$ python -m venv env
...
$ source env/bin/activate
# provider-specific-requirements would be things like: octodns-route53 octodns-azure
$ pip install octodns <provider-specific-requirements>
$ mkdir config

Installing a specific commit SHA¶

If you’d like to install a version that has not yet been released in a repeatable/safe manner you can do the following. In general octoDNS is fairly stable in between releases thanks to the plan and apply process, but care should be taken regardless.

$ pip install -e git+https://git@github.com/octodns/octodns.git@<SHA>#egg=octodns

Config¶

We start by creating a config file to tell octoDNS about our providers and the zone(s) we want it to manage. Below we’re setting up a YamlProvider to source records from our config files and both a Route53Provider and DynProvider to serve as the targets for those records. You can have any number of zones set up and any number of sources of data and targets for records for each. You can also have multiple config files, that make use of separate accounts and each manage a distinct set of zones. A good example of this this might be ./config/staging.yaml & ./config/production.yaml. We’ll focus on a config/production.yaml.

Dynamic Zone Config¶

octoDNS supports dynamically building the list of zones it will work with when source providers support it. The most common use of this would be with YamlProvider and a single dynamic entry to in effect use the files that exist in the provider’s directory as the source of truth. Other providers may support the list_zones method and be available to populate zones dynamically as well. This can be especially useful when using octodns-dump to create an initial setup from an existing provider.

An example config would look something like:

---
providers:
  config:
    class: octodns.provider.yaml.YamlProvider
    directory: ./config
    default_ttl: 3600
    enforce_order: True
  ns1:
    class: octodns_ns1.Ns1Provider
    api_key: env/NS1_API_KEY
  route53:
    class: octodns_route53.Route53Provider
    access_key_id: env/AWS_ACCESS_KEY_ID
    secret_access_key: env/AWS_SECRET_ACCESS_KEY

zones:
  # This is a dynamic zone config. The source(s), here `config`, will be
  # queried for a list of zone names and each will dynamically be set up to
  # match the dynamic entry.
  '*':
    sources:
      - config
    targets:
      - ns1
      - route53

Static Zone Config¶

In cases where finer grained control is desired and the configuration of individual zones varies zones can be an explicit list with each configured zone listed along with its specific setup. As exemplified below alias zones can be useful when two zones are exact copies of each other, with the same configuration and records. YAML anchors are also helpful to avoid duplication where zones share config, but not records.

---
manager:
  include_meta: True
  max_workers: 2

providers:
  config:
    class: octodns.provider.yaml.YamlProvider
    directory: ./config
    default_ttl: 3600
    enforce_order: True
  ns1:
    class: octodns_ns1.Ns1Provider
    api_key: env/NS1_API_KEY
  route53:
    class: octodns_route53.Route53Provider
    access_key_id: env/AWS_ACCESS_KEY_ID
    secret_access_key: env/AWS_SECRET_ACCESS_KEY

zones:
  example.com.: &dual_target
    sources:
      - config
    targets:
      - ns1
      - route53

  # these have the same setup as example.com., but will have their own files
  # in the configuration directory for records.
  third.tv.: *dual_target
  fourth.tv.: *dual_target

  example.net.:
    # example.net. is an exact copy of example.com., there will not be an
    # example.net.yaml file in the config directory as `alias` includes
    # duplicating the records of the aliased zone along with its config.
    alias: example.com.

  other.com.:
    lenient: True
    sources:
      - config
    targets:
      - ns1

General Configuration Concepts¶

class is a special key that tells octoDNS what python class should be loaded. Any other keys will be passed as configuration values to that provider. In general any sensitive or frequently rotated values should come from environmental variables. When octoDNS sees a value that starts with env/ it will look for that value in the process’s environment and pass the result along.

Further information can be found in the docstring of each source and provider class.

The include_meta key in the manager section of the config controls the creation of a TXT record at the root of a zone that is managed by octoDNS. If set to True, octoDNS will create a TXT record for the root of the zone with the value provider=<target-provider>. If not specified, the default value for include_meta is False.

The max_workers key in the manager section of the config enables threading to parallelize the planning portion of the sync.

Quick Example Record¶

Now that we have something to tell octoDNS about our providers & zones we need to tell it about our records. We’ll keep it simple for now and just create a single A record at the top-level of the domain.

config/example.com.yaml

---
'':
  ttl: 60
  type: A
  values:
    - 1.2.3.4
    - 1.2.3.5

Further information can be found in Records Documentation.

Noop¶

We’re ready to do a dry-run with our new setup to see what changes it would make. Since we’re pretending here we’ll act like there are no existing records for example.com. in our accounts on either provider.

$ octodns-sync --config-file=./config/production.yaml
...
********************************************************************************
* example.com.
********************************************************************************
* route53 (Route53Provider)
*   Create <ARecord A 60, example.com., [u'1.2.3.4', '1.2.3.5']>
*   Summary: Creates=1, Updates=0, Deletes=0, Existing Records=0
* dyn (DynProvider)
*   Create <ARecord A 60, example.com., [u'1.2.3.4', '1.2.3.5']>
*   Summary: Creates=1, Updates=0, Deletes=0, Existing Records=0
********************************************************************************
...

There will be other logging information presented on the screen, but successful runs of sync will always end with a summary like the above for any providers & zones with changes. If there are no changes a message saying so will be printed instead. Above we’re creating a new zone in both providers so they show the same change, but that doesn’t always have to be the case. If, to start, one of them had a different state, you would see the changes octoDNS intends to make to sync them up.

Making changes¶

WARNING: octoDNS assumes ownership of any domain you point it to. When you tell it to act it will do whatever is necessary to try and match up states including deleting any unexpected records. Be careful when playing around with octoDNS. It’s best to experiment with a fake zone or one without any data that matters until you’re comfortable with the system.

Now it’s time to tell octoDNS to make things happen. We’ll invoke it again with the same options and add a --doit on the end to tell it this time we actually want it to try and make the specified changes.

$ octodns-sync --config-file=./config/production.yaml --doit
...

The output here would be the same as before with a few more log lines at the end as it makes the actual changes. After which the config in Route53 and Dyn should match what’s in the yaml file.

Workflow¶

In the above case we manually ran octoDNS from the command line. That works and it’s better than heading into the provider GUIs and making changes by clicking around, but octoDNS is designed to be run as part of a deploy process. The implementation details are well beyond the scope of this README, but here is an example of the workflow we use at GitHub. It follows the way GitHub itself is branch deployed.

The first step is to create a PR with your changes.

GitHub user interface of a pull request

Assuming the code tests and config validation statuses are green the next step is to do a noop deploy and verify that the changes octoDNS plans to make are the ones you expect.

Output of a noop deployment command

After that comes a set of reviews. One from a teammate who should have full context on what you’re trying to accomplish and visibility into the changes you’re making to do it. The other is from a member of the team here at GitHub that owns DNS, mostly as a sanity check and to make sure that best practices are being followed. As much of that as possible is baked into octodns-validate.

After the reviews it’s time to branch deploy the change.

Output of a deployment command

If that goes smoothly, you again see the expected changes, and verify them with dig and/or octodns-report you’re good to hit the merge button. If there are problems you can quickly do a .deploy dns/main to go back to the previous state.

Bootstrapping config files¶

Very few situations will involve starting with a blank slate which is why there’s tooling built in to pull existing data out of providers into a matching config file.

$ octodns-dump --config-file=config/production.yaml --output-dir=tmp/ example.com. route53
2017-03-15T13:33:34  INFO  Manager __init__: config_file=tmp/production.yaml
2017-03-15T13:33:34  INFO  Manager dump: zone=example.com., sources=('route53',)
2017-03-15T13:33:36  INFO  Route53Provider[route53] populate:   found 64 records
2017-03-15T13:33:36  INFO  YamlProvider[dump] plan: desired=example.com.
2017-03-15T13:33:36  INFO  YamlProvider[dump] plan:   Creates=64, Updates=0, Deletes=0, Existing Records=0
2017-03-15T13:33:36  INFO  YamlProvider[dump] apply: making changes

The above command pulled the existing data out of Route53 and placed the results into tmp/example.com.yaml. That file can be inspected and moved into config/ to become the new source. If things are working as designed a subsequent noop sync should show zero changes.

Note that a Dynamic Zone Config and be really powerful in combination with octodns-dump allowing you to quickly create a set of octoDNS zone files for all the zones configured in your sources.

$ octodns-dump --config-file=config/production.yaml --output-dir=tmp/ '*' route53
...

It is important to review any WARNING log lines printed out during an octodns-dump invocation as it will give you information about records that aren’t supported fully or at all by octoDNS and thus won’t be exact matches or included in the dumps. Generally records that cannot be converted are either of a type that octoDNS does not support or those that include “dynamic” functionality that doesn’t match octoDNS’s behaviors.