You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
183 lines
6.1 KiB
183 lines
6.1 KiB
Configuration
|
|
=============
|
|
|
|
Basics
|
|
------
|
|
|
|
This document picks up where :doc:`getting-started` and :doc:`records` leave off,
|
|
discussing details and less common scenarios.
|
|
|
|
YamlProvider
|
|
------------
|
|
|
|
:py:mod:`octodns.provider.yaml` lays out the options for configuring the most commonly
|
|
used source of record data.
|
|
|
|
Dynamic Zone Config
|
|
-------------------
|
|
|
|
In many cases octoDNS's dynamic zone configuration is the best option for
|
|
configuring octoDNS to manage your zones. In its simplest form that 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:
|
|
'*':
|
|
sources:
|
|
- config
|
|
targets:
|
|
- ns1
|
|
- route53
|
|
|
|
This configuration will query both ns1 and route53 for the list of zones they
|
|
are managing and dynamically add them to the list being managed using the
|
|
sources and targets corresponding to the '*' section. See
|
|
:ref:`dynamic-zone-config` for details.
|
|
|
|
Static Zone Config
|
|
------------------
|
|
|
|
In cases where fine 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.
|
|
|
|
``lenient``
|
|
-----------
|
|
|
|
``lenient`` mostly focuses on the details of ``Record``s and standards
|
|
compliance. When set to ``true`` octoDNS will allow non-compliant
|
|
configurations & values where possible. For example CNAME values that don't end
|
|
with a ``.``, label length restrictions, and invalid geo codes on ``dynamic``
|
|
records. When in lenient mode octoDNS will log validation problems at
|
|
``WARNING`` and try and continue with the configuration or source data as it
|
|
exists. See Lenience_ for more information on the concept and how it can be
|
|
configured.
|
|
|
|
.. _Lenience: records.rst#lenience
|
|
|
|
``strict_supports``
|
|
-------------------
|
|
|
|
``strict_supports`` is a ``Provider`` level parameter that comes into play when
|
|
a provider has been asked to create a record that it is unable to support. The
|
|
simplest case of this would be record type, e.g. ``SSHFP`` not being supported
|
|
by ``AzureProvider``. If such a record is passed to an ``AzureProvider`` as a
|
|
target the provider will take action based on the ``strict_supports``. When
|
|
``true`` it will throw an exception saying that it's unable to create the
|
|
record, when set to ``false`` it will log at ``WARNING`` with information about
|
|
what it's unable to do and how it is attempting to work around it. Other
|
|
examples of things that cannot be supported would be ``dynamic`` records on a
|
|
provider that only supports simple or the lack of support for specific geos in
|
|
a provider, e.g. Route53Provider does not support ``NA-CA-*``.
|
|
|
|
It is worth noting that these errors will happen during the plan phase of
|
|
things so that problems will be visible without having to make changes.
|
|
|
|
As of octoDNS 1.x ``strict_supports`` is on by default. You have the choice to
|
|
set ``strict_supports=false`` on a per provider basis to request that things warn
|
|
and continue in a best-effort fashion.
|
|
|
|
Configuring ``strict_supports``
|
|
...............................
|
|
|
|
The ``strict_supports`` parameter is available on all providers and can be
|
|
configured in YAML as follows::
|
|
|
|
providers:
|
|
someprovider:
|
|
class: whatever.TheProvider
|
|
...
|
|
strict_supports: true
|
|
|
|
.. _automatic-ptr-generation:
|
|
|
|
Automatic PTR generation
|
|
------------------------
|
|
|
|
octoDNS supports automatically generating PTR records from the ``A``/``AAAA``
|
|
records it manages. For more information see the :doc:`auto_arpa`
|
|
documentation.
|