From a96dff480c162139991d030d4743ec3c9034fed9 Mon Sep 17 00:00:00 2001 From: Ross McFarland Date: Mon, 21 Mar 2022 14:29:39 -0700 Subject: [PATCH] Documentation for dynamic Record type registration --- docs/records.md | 45 ++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 42 insertions(+), 3 deletions(-) diff --git a/docs/records.md b/docs/records.md index f210846..182a109 100644 --- a/docs/records.md +++ b/docs/records.md @@ -124,10 +124,10 @@ If you'd like to enable lenience for a whole zone you can do so with the followi #### Restrict Record manipulations -OctoDNS currently provides the ability to limit the number of updates/deletes on +OctoDNS currently provides the ability to limit the number of updates/deletes on DNS records by configuring a percentage of allowed operations as a threshold. -If left unconfigured, suitable defaults take over instead. In the below example, -the Dyn provider is configured with limits of 40% on both update and +If left unconfigured, suitable defaults take over instead. In the below example, +the Dyn provider is configured with limits of 40% on both update and delete operations over all the records present. ````yaml @@ -136,3 +136,42 @@ dyn: update_pcent_threshold: 0.4 delete_pcent_threshold: 0.4 ```` + +## Provider specific record types + +### Creating and registering + +octoDNS has support for provider specific record types through a dynamic type registration system. This functionality is powered by `Route.register_type` and can be used as follows. + +```python +class _SpecificValue(object): + ... + +class SomeProviderSpecificRecord(ValuesMixin, Record): + _type = 'SomeProvider/SPECIFIC' + _value_type = _SpecificValue + +Record.register_type(SomeProviderSpecificRecord) +``` + +Have a look in [octodns.record](/octodns/record/__init__.py) for examples of how records are implemented. `NsRecord` and `_NsValue` are fairly simple examples to start with. You can also take a look at [`Route53Provider`'s `Route53Provider/ALIAS` type](https://github.com/octodns/octodns-route53/blob/main/octodns_route53/record.py). + +In general this support is intended for record types that only make sense for a single provider. If multiple providers have a similar record it may make sense to implement it in octoDNS core. + +### Naming + +By convention the record type should be prefix with the provider class, e.g. `Route53Provider` followed by a `/` and an all-caps record type name `ALIAS`, e.g. `Route53Provider/ALIAS`. + +### YamlProvider support + +Once the type is registered `YamlProvider` will automatically gain support for it and they can be included in your zone yaml files. + +```yaml +alias: + type: Route53Provider/ALIAS + values: + - name: www + type: A + - name: www + type: AAAA +```