|
|
|
@ -0,0 +1,257 @@ |
|
|
|
## Migrating to octoDNS via octodns-dump |
|
|
|
|
|
|
|
Importing an existing DNS setup into octoDNS management is a very |
|
|
|
straightforward process and can generally be completed in minutes. |
|
|
|
|
|
|
|
Some relevant documentation for this example is in comments in the YAML configuration files. |
|
|
|
|
|
|
|
* [config/octodns.yaml](config/octodns.yaml) |
|
|
|
* [config/my-domain.com.yaml](config/my-domain.com.yaml) |
|
|
|
* [config/unused-domain.io.yaml](config/unused-domain.io.yaml) |
|
|
|
|
|
|
|
From here on this README focuses on the general process of running octoDNS to |
|
|
|
create your initial config. |
|
|
|
|
|
|
|
## Checking out the code and setting up the environment |
|
|
|
|
|
|
|
You would not normally need to check out octoDNS itself, you instead would have |
|
|
|
a git repo with only your configuration files. Here we're cloning the repo only |
|
|
|
to get a copy of the example files. |
|
|
|
|
|
|
|
```console |
|
|
|
$ git clone https://github.com/octodns/octodns.git |
|
|
|
$ cd octodns/examples/basic/ |
|
|
|
$ python3 -mvenv env |
|
|
|
$ source env/bin/activate |
|
|
|
(env) $ pip install -r requirements.txt |
|
|
|
``` |
|
|
|
|
|
|
|
If you were instead creating a repo for your config from scratch it might look |
|
|
|
something like: |
|
|
|
|
|
|
|
```console |
|
|
|
$ mkdir octodnsed |
|
|
|
$ cd octodnsed |
|
|
|
$ git init -b main |
|
|
|
$ mkdir config |
|
|
|
# Using your editor of choice create the main config file with your customized |
|
|
|
# version of things, examples/basic/config/octodns.yaml is a good place to |
|
|
|
# start. |
|
|
|
$ vim config/octodns.yaml |
|
|
|
# follow the process here and once complete |
|
|
|
$ git add config |
|
|
|
$ git commit -m "Importting existing records into octoDNS" |
|
|
|
$ git push -u origin main |
|
|
|
``` |
|
|
|
|
|
|
|
## Running octodns-dump |
|
|
|
|
|
|
|
Once you have your configuration files and octoDNS installed you're ready to |
|
|
|
dump your zone configs. Here we've assumed that the provider being used supports |
|
|
|
`list_zones`, not all do. If you get an error to that effect see |
|
|
|
[dynamic-zone-config](../dynamic-zone-config) for details on how to explicitly |
|
|
|
list your zones in the config file. |
|
|
|
|
|
|
|
The quoted * below is what tells octodns-dump to dynamically source the list of |
|
|
|
zones and dump config files for all of them. If you would only like to dump a |
|
|
|
specific zone you can replace it with the zone name, e.g. `my-domain.com.`, |
|
|
|
making sure to include the trailing `.` |
|
|
|
|
|
|
|
|
|
|
|
```console |
|
|
|
(env) coho:migrating-to-octodns ross$ octodns-dump --config-file=config/octodns.yaml --output-dir config/ '*' some-provider |
|
|
|
2023-08-25T10:36:00 [4413005312] INFO Manager __init__: config_file=config/octodns.yaml, (octoDNS 1.0.0+6e7f036b) |
|
|
|
2023-08-25T10:36:00 [4413005312] INFO Manager _config_executor: max_workers=1 |
|
|
|
2023-08-25T10:36:00 [4413005312] INFO Manager _config_include_meta: include_meta=False |
|
|
|
2023-08-25T10:36:00 [4413005312] INFO Manager _config_auto_arpa: auto_arpa=False |
|
|
|
2023-08-25T10:36:00 [4413005312] INFO Manager __init__: global_processors=[] |
|
|
|
2023-08-25T10:36:00 [4413005312] INFO Manager __init__: provider=config (octodns.provider.yaml 1.0.0+6e7f036b) |
|
|
|
2023-08-25T10:36:00 [4413005312] INFO Manager __init__: provider=some-provider (octodns.provider.yaml 1.0.0+6e7f036b) |
|
|
|
2023-08-25T10:36:00 [4413005312] INFO Manager dump: zone=*, output_dir=config/, output_provider=None, lenient=False, split=False, sources=['some-provider'] |
|
|
|
2023-08-25T10:36:00 [4413005312] INFO Manager dump: using custom YamlProvider |
|
|
|
2023-08-25T10:36:00 [4413005312] INFO Manager sync: dynamic zone=*, sources=[YamlProvider] |
|
|
|
2023-08-25T10:36:00 [4413005312] INFO Manager sync: adding dynamic zone=my-domain.com. |
|
|
|
2023-08-25T10:36:00 [4413005312] INFO Manager sync: adding dynamic zone=unused-domain.io. |
|
|
|
Traceback (most recent call last): |
|
|
|
File "/Users/ross/octodns/octodns/examples/migrating-to-octodns/env/bin/octodns-dump", line 8, in <module> |
|
|
|
sys.exit(main()) |
|
|
|
^^^^^^ |
|
|
|
File "/Users/ross/octodns/octodns/octodns/cmds/dump.py", line 51, in main |
|
|
|
manager.dump( |
|
|
|
File "/Users/ross/octodns/octodns/octodns/manager.py", line 868, in dump |
|
|
|
source.populate(zone, lenient=lenient) |
|
|
|
File "/Users/ross/octodns/octodns/octodns/provider/yaml.py", line 229, in populate |
|
|
|
self._populate_from_file(filename, zone, lenient) |
|
|
|
File "/Users/ross/octodns/octodns/octodns/provider/yaml.py", line 175, in _populate_from_file |
|
|
|
record = Record.new( |
|
|
|
^^^^^^^^^^^ |
|
|
|
File "/Users/ross/octodns/octodns/octodns/record/base.py", line 76, in new |
|
|
|
raise ValidationError(fqdn, reasons, context) |
|
|
|
octodns.record.exception.ValidationError: Invalid record "my-domain.com.", ./target/my-domain.com.yaml, line 17, column 5 |
|
|
|
- NS value "ns1.some-provider.com" missing trailing . |
|
|
|
- NS value "ns2.some-provider.com" missing trailing . |
|
|
|
- NS value "ns3.some-provider.com" missing trailing . |
|
|
|
- NS value "ns4.some-provider.com" missing trailing . |
|
|
|
``` |
|
|
|
|
|
|
|
We've intentionally configured data in the provider without following |
|
|
|
(octoDNS's) best practices as it's common to run across these sorts of things |
|
|
|
when migrating. In this case the NS values are missing their trailing `.`, |
|
|
|
`ns1.some-provider.com` should be `ns1.some-provider.com.`. |
|
|
|
|
|
|
|
Regardless of whether or not you hit errors it is important to carefully look |
|
|
|
over the output of octodns-dump to ensure that it was able to make sense of and |
|
|
|
import everything it found. It usually can, but you may sometimes run across |
|
|
|
things that it can't make sense of or otherwise doesn't support. |
|
|
|
|
|
|
|
This is especially true if you have any advanced records configured in your |
|
|
|
provider. octoDNS generally cannot convert records with functionality like |
|
|
|
weights and/or geo-coding enabled. It'll generally import a "simple" version of |
|
|
|
that record and indicate it's doing so with a WARNING log message. If you hit |
|
|
|
this situation see [Dynamic Records](/docs/dynamic_records.md). |
|
|
|
|
|
|
|
## Running octodns-dump again, now with --lenient |
|
|
|
|
|
|
|
Back to our example, the missing `.`s aren't a huge deal and octoDNS can be |
|
|
|
asked to ignore them with the `--lenient` argument. |
|
|
|
|
|
|
|
```console |
|
|
|
(env) coho:migrating-to-octodns ross$ octodns-dump --config-file=config/octodns.yaml --output-dir config/ '*' some-provider --lenient |
|
|
|
2023-08-25T10:43:26 [4528057856] INFO Manager __init__: config_file=config/octodns.yaml, (octoDNS 1.0.0+6e7f036b) |
|
|
|
2023-08-25T10:43:26 [4528057856] INFO Manager _config_executor: max_workers=1 |
|
|
|
2023-08-25T10:43:26 [4528057856] INFO Manager _config_include_meta: include_meta=False |
|
|
|
2023-08-25T10:43:26 [4528057856] INFO Manager _config_auto_arpa: auto_arpa=False |
|
|
|
2023-08-25T10:43:26 [4528057856] INFO Manager __init__: global_processors=[] |
|
|
|
2023-08-25T10:43:26 [4528057856] INFO Manager __init__: provider=config (octodns.provider.yaml 1.0.0+6e7f036b) |
|
|
|
2023-08-25T10:43:26 [4528057856] INFO Manager __init__: provider=some-provider (octodns.provider.yaml 1.0.0+6e7f036b) |
|
|
|
2023-08-25T10:43:26 [4528057856] INFO Manager dump: zone=*, output_dir=config/, output_provider=None, lenient=True, split=False, sources=['some-provider'] |
|
|
|
2023-08-25T10:43:26 [4528057856] INFO Manager dump: using custom YamlProvider |
|
|
|
2023-08-25T10:43:26 [4528057856] INFO Manager sync: dynamic zone=*, sources=[YamlProvider] |
|
|
|
2023-08-25T10:43:26 [4528057856] INFO Manager sync: adding dynamic zone=my-domain.com. |
|
|
|
2023-08-25T10:43:26 [4528057856] INFO Manager sync: adding dynamic zone=unused-domain.io. |
|
|
|
2023-08-25T10:43:26 [4528057856] WARNING Record Invalid record "my-domain.com.", ./target/my-domain.com.yaml, line 17, column 5 |
|
|
|
- NS value "ns1.some-provider.com" missing trailing . |
|
|
|
- NS value "ns2.some-provider.com" missing trailing . |
|
|
|
- NS value "ns3.some-provider.com" missing trailing . |
|
|
|
- NS value "ns4.some-provider.com" missing trailing . |
|
|
|
2023-08-25T10:43:26 [4528057856] INFO YamlProvider[some-provider] populate: found 10 records, exists=False |
|
|
|
2023-08-25T10:43:26 [4528057856] INFO YamlProvider[dump] plan: desired=my-domain.com. |
|
|
|
2023-08-25T10:43:26 [4528057856] INFO YamlProvider[dump] plan: Creates=10, Updates=0, Deletes=0, Existing Records=0 |
|
|
|
2023-08-25T10:43:26 [4528057856] INFO YamlProvider[dump] apply: making 10 changes to my-domain.com. |
|
|
|
2023-08-25T10:43:26 [4528057856] INFO YamlProvider[some-provider] populate: found 0 records, exists=False |
|
|
|
2023-08-25T10:43:26 [4528057856] INFO YamlProvider[dump] plan: desired=unused-domain.io. |
|
|
|
2023-08-25T10:43:26 [4528057856] WARNING YamlProvider[dump] root NS record supported, but no record is configured for unused-domain.io. |
|
|
|
2023-08-25T10:43:26 [4528057856] INFO YamlProvider[dump] plan: No changes |
|
|
|
2023-08-25T10:43:26 [4528057856] INFO YamlProvider[dump] apply: making 0 changes to unused-domain.io. |
|
|
|
``` |
|
|
|
|
|
|
|
## Examining the results |
|
|
|
|
|
|
|
We can now take a look in the config/ directory to see the created zone files |
|
|
|
along side our main config. |
|
|
|
|
|
|
|
```console |
|
|
|
(env) coho:migrating-to-octodns ross$ ls -1 config/ |
|
|
|
my-domain.com.yaml |
|
|
|
octodns.yaml |
|
|
|
unused-domain.io.yaml |
|
|
|
``` |
|
|
|
|
|
|
|
If you open up the my-domain.com.yaml file you'll note that the root NS record values are missing |
|
|
|
their trailing `.`s. octoDNS has done its best to dump things as they currently |
|
|
|
are in the provider. That means that if you tried to generate a plan with |
|
|
|
`octodns-sync` now it would fail b/c the configuration doesn't follow best |
|
|
|
practices. |
|
|
|
|
|
|
|
When migrating it's recommended to make as few changes to your config as |
|
|
|
possible initially, that is you want to bring the setup as-is under octoDNS |
|
|
|
management and avoid churn as much as possible. This is the safest approach, |
|
|
|
change as little as possible and incrementally work towards having a fully |
|
|
|
managed and compliant/best practice config. |
|
|
|
|
|
|
|
So for now we'll enable `lenient` on the root NS record. For more details on |
|
|
|
see the [lenience](../lenience/) example. |
|
|
|
|
|
|
|
```yaml |
|
|
|
... |
|
|
|
- octodns: |
|
|
|
lenient: true |
|
|
|
type: NS |
|
|
|
values: |
|
|
|
- ns1.some-provider.com |
|
|
|
- ns2.some-provider.com |
|
|
|
- ns3.some-provider.com |
|
|
|
- ns4.some-provider.com |
|
|
|
... |
|
|
|
``` |
|
|
|
|
|
|
|
## Generating our first plan |
|
|
|
|
|
|
|
We can now ask octoDNS to create a plan to see if anything would change. Since |
|
|
|
we've looked closely at the log output zone configuration files we have a pretty |
|
|
|
good idea the answer is no. |
|
|
|
|
|
|
|
```console |
|
|
|
(env) coho:migrating-to-octodns ross$ octodns-sync --config-file=config/octodns.yaml |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO Manager __init__: config_file=config/octodns.yaml, (octoDNS 1.0.0+6e7f036b) |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO Manager _config_executor: max_workers=1 |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO Manager _config_include_meta: include_meta=False |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO Manager _config_auto_arpa: auto_arpa=False |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO Manager __init__: global_processors=[] |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO Manager __init__: provider=config (octodns.provider.yaml 1.0.0+6e7f036b) |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO Manager __init__: provider=some-provider (octodns.provider.yaml 1.0.0+6e7f036b) |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO Manager sync: eligible_zones=[], eligible_targets=[], dry_run=True, force=False, plan_output_fh=<stdout> |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO Manager sync: sources=['config'] |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO Manager sync: dynamic zone=*, sources=[YamlProvider] |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO Manager sync: adding dynamic zone=my-domain.com. |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO Manager sync: adding dynamic zone=unused-domain.io. |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO Manager sync: zone=my-domain.com. |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO Manager sync: sources=['config'] |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO Manager sync: targets=['some-provider'] |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO Manager sync: zone=unused-domain.io. |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO Manager sync: sources=['config'] |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO Manager sync: targets=['some-provider'] |
|
|
|
2023-08-25T11:07:44 [4644843008] WARNING Record Invalid record "my-domain.com.", ./config/my-domain.com.yaml, line 9, column 5 |
|
|
|
- NS value "ns1.some-provider.com" missing trailing . |
|
|
|
- NS value "ns2.some-provider.com" missing trailing . |
|
|
|
- NS value "ns3.some-provider.com" missing trailing . |
|
|
|
- NS value "ns4.some-provider.com" missing trailing . |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO YamlProvider[config] populate: found 10 records, exists=False |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO YamlProvider[some-provider] plan: desired=my-domain.com. |
|
|
|
2023-08-25T11:07:44 [4644843008] WARNING Record Invalid record "my-domain.com.", ./target/my-domain.com.yaml, line 17, column 5 |
|
|
|
- NS value "ns1.some-provider.com" missing trailing . |
|
|
|
- NS value "ns2.some-provider.com" missing trailing . |
|
|
|
- NS value "ns3.some-provider.com" missing trailing . |
|
|
|
- NS value "ns4.some-provider.com" missing trailing . |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO YamlProvider[some-provider] populate: found 10 records, exists=False |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO YamlProvider[some-provider] plan: No changes |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO YamlProvider[config] populate: found 0 records, exists=False |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO YamlProvider[some-provider] plan: desired=unused-domain.io. |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO YamlProvider[some-provider] populate: found 0 records, exists=False |
|
|
|
2023-08-25T11:07:44 [4644843008] WARNING YamlProvider[some-provider] root NS record supported, but no record is configured for unused-domain.io. |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO YamlProvider[some-provider] plan: No changes |
|
|
|
2023-08-25T11:07:44 [4644843008] INFO Plan |
|
|
|
******************************************************************************** |
|
|
|
No changes were planned |
|
|
|
******************************************************************************** |
|
|
|
``` |
|
|
|
|
|
|
|
If you had unsupported record types or advanced features in use this may not be |
|
|
|
the case. It's completely safe to generate a plan, octoDNS won't make any |
|
|
|
changes. |
|
|
|
|
|
|
|
If you see things in the plan output section it's time to triple check and make |
|
|
|
sure they're, hopefully minimal, modifications your OK with making. |
|
|
|
|
|
|
|
If the changes are due to advanced functionality you'll need to step back and |
|
|
|
plan a careful migration over to [Dynamic Records](/docs/dynamic_records.md) |
|
|
|
which is beyond the scope of this example. |
|
|
|
|
|
|
|
## What's Next |
|
|
|
|
|
|
|
So now you can commit your config and start managing you DNS with octoDNS rather |
|
|
|
than clicking buttons in UIs or using whatever you previous had used. |
|
|
|
|
|
|
|
* Check out [octoDNS basic example](../basic) for an example of how to create zone configuration YAML files from your existing provider's configuration |
|
|
|
* Have a look at [managing SPF values](../managing-spf) for details on the best practices for configuring email related DNS records with octoDNS |
|
|
|
* For a complete list check out the [Examples Directory](../) |
Ross McFarland
2 years ago