Tools for managing DNS across multiple providers
In the vein of infrastructure as code octoDNS provides a set of tools & patterns that make it easy to manage your DNS records across multiple providers. The resulting config can live in a repository and be deployed just like the rest of your code, maintaining a clear history and using your existing review & workflow.
The architecture is pluggable and the tooling is flexible to make it applicable to a wide variety of use-cases. Effort has been made to make adding new providers as easy as possible. In the simple case that involves writing of a single class and a couple hundred lines of code, most of which is translating between the provider’s schema and octoDNS’s.
Documentation
Providers
The table below lists the providers octoDNS supports. They are maintained in their own repositories and released as independent modules.
Provider |
Module |
Notes |
|---|---|---|
/etc/hosts |
||
Dyn [deprecated] |
||
built-in |
Supports all record types and core functionality |
|
Zonefile |
Sources
Similar to providers, but can only serve to populate records into a zone, cannot be synced to.
Source/Module |
Notes |
|---|---|
read-only environment variable injection |
|
Processors
Processor |
Description |
|---|---|
Useful when processes external to octoDNS are managing acme challenge DNS records, e.g. LetsEncrypt |
|
Processor that ensures ALIAS, CNAME, DNAME, MX, NS, PTR, and SRVs have trailing dots |
|
Filter that errors or warns on planned root/APEX NS records changes. |
|
Filter that IGNORES root/APEX NS records and prevents octoDNS from trying to manage them (where supported.) |
|
Adds a special meta record with timing, UUID, providers, and/or version to aid in debugging and monitoring. |
|
Filter that ONLY manages records that match specified naming patterns, all others will be ignored |
|
Filter that IGNORES records that match specified naming patterns, all others will be managed |
|
Filter that ONLY manages records that match specified value patterns based on rdata_text, all others will be ignored |
|
Filter that IGNORES records that match specified value patterns based on rdata_text, all others will be managed |
|
Processor that implements ownership in octoDNS so that it can manage only the records in a zone in sources and will ignore all others. |
|
Processor that checks SPF values for violations of DNS query limits |
|
Processor that restricts the allow TTL values to a specified range or list of specific values |
|
Filter that ONLY manages records of specified types, all others will be ignored |
|
Filter that IGNORES records of specified types, all others will be managed |
|
SPF Value Management for octoDNS |
Custom Sources and Providers
You can check out the source and provider directories to see what’s currently
supported. Sources act as a source of record information. AxfrSource and
TinyDnsFileSource are currently the only OSS sources, though we have several
others internally that are specific to our environment. These include something
to pull host data from gPanel and a similar provider that sources information
about our network gear to create both A & PTR records for their
interfaces. Things that might make good OSS sources might include an
ElbSource that pulls information about AWS Elastic Load Balancers and
dynamically creates CNAME``s for them, or ``Ec2Source that pulls instance
information so that records can be created for hosts similar to how our
GPanelProvider works.
Most of the things included in octoDNS are providers, the obvious difference being that they can serve as both sources and targets of data. We’d really like to see this list grow over time so if you use an unsupported provider then PRs are welcome. The existing providers should serve as reasonable examples. Those that have no GeoDNS support are relatively straightforward. Unfortunately most of the APIs involved to do GeoDNS style traffic management are complex and somewhat inconsistent so adding support for that function would be nice, but is optional and best done in a separate pass.
The class key in the providers config section can be used to point to
arbitrary classes in the python path so internal or 3rd party providers can
easily be included with no coordination beyond getting them into
PYTHONPATH, most likely installed into the virtualenv with octoDNS.
For examples of building third-party sources and providers, see Related Projects and Resources
Contributing
Please see our contributing document if you would like to participate!
Getting help
If you have a problem or suggestion, please open an issue in this repository, and we will do our best to help.
Please note that this project adheres to the Contributor Covenant Code of Conduct.
License
octoDNS is licensed under the MIT license.
The MIT license grant is not for GitHub’s trademarks, which include the logo designs. GitHub reserves all trademark and copyright rights in and to all GitHub trademarks. GitHub’s logos include, for instance, the stylized designs that include “logo” in the file title in the following folder: https://github.com/octodns/octodns/tree/main/docs/logos/
GitHub® and its stylized versions and the Invertocat mark are GitHub’s Trademarks or registered Trademarks. When using GitHub’s logos, be sure to follow the GitHub logo guidelines.