From 2a876407c66f9b7986f93c3992e7cfe14e896bec Mon Sep 17 00:00:00 2001 From: Ross McFarland Date: Wed, 6 Aug 2025 18:32:33 -0700 Subject: [PATCH] Fix sphinx heading warnings. Remove uneeded globs that were also warnings --- .../559ae3e1ace54db88f122ed7299e11c0.md | 4 ++ CHANGELOG.md | 58 +++++++++---------- docs/auto_arpa.md | 14 ++--- docs/dynamic_records.md | 16 ++--- docs/examples/README.md | 16 +++-- docs/geo_records.md | 6 +- docs/index.md | 3 +- 7 files changed, 59 insertions(+), 58 deletions(-) create mode 100644 .changelog/559ae3e1ace54db88f122ed7299e11c0.md diff --git a/.changelog/559ae3e1ace54db88f122ed7299e11c0.md b/.changelog/559ae3e1ace54db88f122ed7299e11c0.md new file mode 100644 index 0000000..25acec0 --- /dev/null +++ b/.changelog/559ae3e1ace54db88f122ed7299e11c0.md @@ -0,0 +1,4 @@ +--- +type: none +--- +Doc heading fixes \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a23910..eff5631 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -56,7 +56,7 @@ Minor: * Improved handling of present, but empty/None config file values. * Add PlanJson plan_output support * Include `record_type` in Change data - + ## v1.8.0 - 2024-06-10 - Set the records straight * Add support for SVCB and HTTPS records @@ -119,7 +119,7 @@ Minor: ## v1.3.0 - 2023-11-14 - New and improved processors -#### Noteworthy changes +### Noteworthy changes * Added `octodns.__version__` to replace `octodns.__VERSION__` as the former is more of a standard, per pep-8. `__VERSION__` is deprecated and will go away @@ -134,7 +134,7 @@ Minor: bug, but it's possible (non-public) third party providers are susceptible. The most likely place to hit issues in is tests where data and/or copy are abused. -#### Stuff +### Stuff * Added ZoneNameFilter processor to enable ignoring/alerting on type-os like octodns.com.octodns.com @@ -172,7 +172,7 @@ Minor: ## v1.1.0 - 2023-09-13 - More than enough for a minor release -#### Noteworthy changes +### Noteworthy changes * New dynamic zone config support that allows wildcard entries in the octoDNS config to be expanded by the source provider(s). See @@ -198,7 +198,7 @@ Minor: DNS changes. Specifically timestamps/uuid so you can track whether changes that have been pushed to providers have propogated/transferred correctly. -#### Stuff +### Stuff * Add context to general configuration and Record validation, e.g. Some problem at filename.yaml, line 42, column 14. Our custom Yaml Loaders @@ -218,11 +218,11 @@ going away with 2.0 more than specific functionality that has been added or having reached a notable level of stability (beyond what is normal.) It is also long (years) overdue. -#### Noteworthy changes +### Noteworthy changes * `geo` records are deprecated. -#### Stuff +### Stuff * Removal of a Python 3.7 specific import work-around now that it's no longer an active/supported version. Also bumps required minimum version of Python 3.8 @@ -240,7 +240,7 @@ long (years) overdue. ## v1.0.0.rc0 - 2023-05-16 - First of the ones -#### Noteworthy changes +### Noteworthy changes * 1.x Deprecation removals * Provider, Source, and Processor shims removed, they've been warnings for > @@ -271,7 +271,7 @@ long (years) overdue. subnet-only rules must appear before any subnet+geo rules, followed by geo-only rules (and catch-all rule w/o any geos/subnets in the end) -#### Stuff +### Stuff * Added new DsRecord type (provider support will be added over time) * Added simple IgnoreRootNsFilter @@ -286,7 +286,7 @@ long (years) overdue. ## v0.9.20 - 2022-10-05 - International friendly -#### Noteworthy changes +### Noteworthy changes * Added support for automatic handling of IDNA (utf-8) zones. Everything is stored IDNA encoded internally. For ASCII zones that's a noop. For zones with @@ -302,7 +302,7 @@ long (years) overdue. * Support for configuring global processors that apply to all zones with `manager.processors` -#### Stuff +### Stuff * Addressed shortcomings with YamlProvider.SUPPORTS in that it didn't include dynamically registered types, was a static list that could have drifted over @@ -346,7 +346,7 @@ long (years) overdue. ## v0.9.17 - 2022-04-02 - Registration required -#### Noteworthy changes +### Noteworthy changes * The changes in plans are now ordered based on change type prior to considering the record name and type as was previously done. The chosen @@ -364,7 +364,7 @@ long (years) overdue. * New `octodns-versions` command which will log out the version of octodns and any provider/processor/plan_output modules you are using. -#### Stuff +### Stuff * Manager includes the octoDNS version in its init log line * Non-official release installs will now include a bit of the sha to indicate @@ -373,7 +373,7 @@ long (years) overdue. ## v0.9.16 - 2022-03-04 - Manage the root of the problem -#### Noteworthy changes +### Noteworthy changes * Foundational support for root NS record management. * YamlProvider has it enabled and in general everyone should add root NS @@ -387,7 +387,7 @@ long (years) overdue. * Root NS record changes will always require `--force` indicating that they are impactful changes that need a careful :eyes: -#### Stuff +### Stuff * _AggregateTarget has more complete handling of SUPPORTS* functionality, mostly applicable for the compare operation. @@ -396,7 +396,7 @@ long (years) overdue. ## v0.9.15 - 2022-02-07 - Where have all the providers gone? -#### Noteworthy changes +### Noteworthy changes * Providers extracted from octoDNS core into individual repos https://github.com/octodns/octodns/issues/622 & @@ -430,7 +430,7 @@ long (years) overdue. script/update-requirements has been added to help manage the txt files going forward. -#### Prior to extraction +### Prior to extraction * NS1 provider has received improvements to the dynamic record implementation. As a result, if octoDNS is downgraded from this version, any dynamic records @@ -443,7 +443,7 @@ long (years) overdue. will not be read/parsed correctly by the older version and will show a diff. * Transip was updated to their new client api -#### Stuff +### Stuff * Additional FQDN validation to ALIAS/CNAME value, MX exchange, SRV target and tests of the functionality. @@ -452,7 +452,7 @@ long (years) overdue. ## v0.9.14 - 2021-10-10 - A new supports system -#### Noteworthy changes +### Noteworthy changes * Provider `strict_supports` param added, currently defaults to `false`, along with Provider._process_desired_zone this forms the foundations of a new @@ -477,7 +477,7 @@ long (years) overdue. new python versions and hasn't seen a release since 2010. May return with https://github.com/octodns/octodns/pull/762 -#### Stuff +### Stuff * Fully remove python 2.7 support & sims * Dynamic record pool status flag: up/down/obey added w/provider support as @@ -499,7 +499,7 @@ long (years) overdue. ## v0.9.13 - 2021-07-18 - Processors Alpha -#### Noteworthy changes +### Noteworthy changes * Alpha support for Processors has been added. Processors allow for hooking into the source, target, and planing process to make nearly arbitrary changes @@ -513,7 +513,7 @@ long (years) overdue. America list for backwards compatibility reasons. They will be added in the next releaser. -#### Stuff +### Stuff * Lots of progress on the partial/beta support for dynamic records in Azure, still not production ready. @@ -525,13 +525,13 @@ long (years) overdue. ## v0.9.12 - 2021-04-30 - Enough time has passed -#### Noteworthy changes +### Noteworthy changes * Formal Python 2.7 support removed, deps and tooling were becoming unmaintainable * octodns/octodns move, from github/octodns, more to come -#### Stuff +### Stuff * ZoneFileSource supports specifying an extension & no files end in . to better support Windows @@ -548,18 +548,18 @@ long (years) overdue. ## v0.9.11 - 2020-11-05 - We still don't know edition -#### Noteworthy changes +### Noteworthy changes * ALIAS records only allowed at the root of zones - see `leient` in record docs for work-arounds if you really need them. -#### New Providers +### New Providers * Gandi LiveDNS * UltraDNS * easyDNS -#### Stuff +### Stuff * Add support for zones aliases * octodns-compare: Prefix filtering and status code on on mismatch @@ -768,7 +768,7 @@ from our OSS users. There's too much to list out since the previous release was cut, but I'll try to cover the highlights/important bits and promise to do better in the future :fingers_crossed: -#### Major: +### Major: * Complete rework of record validation with lenient mode support added to octodns-dump so that data with validation problems can be dumped to config @@ -784,7 +784,7 @@ better in the future :fingers_crossed: * Ignored record support added, `octodns:\n ignored: True` * Ns1Provider added -#### Miscellaneous +### Miscellaneous * Use a 3rd party lib for natural sorting of keys, rather than my old implementation. Sorting can be disabled in the YamlProvider with diff --git a/docs/auto_arpa.md b/docs/auto_arpa.md index a1f7053..cf67efb 100644 --- a/docs/auto_arpa.md +++ b/docs/auto_arpa.md @@ -1,4 +1,4 @@ -## Automatic PTR Generation With auto_arpa +# Automatic PTR Generation With auto_arpa octoDNS supports the automatic generation of `PTR` records for in-addr.arpa. and ip6.arpa. zones. In order to enable the functionality the `auto_arpa` key needs to be passed to the manager configuration. @@ -48,9 +48,9 @@ In order to add `PTR` records for a zone the `auto-arpa` source should be added The above will add `PTR` records for any `A` records previously seen with IP addresses 10.0.0.*. -### A Complete Example +## A Complete Example -#### config/octodns.yaml +### config/octodns.yaml ```yaml manager: @@ -80,7 +80,7 @@ zones: - route53 ``` -#### config/exxampled.com.yaml +### config/exxampled.com.yaml ```yaml ? '' @@ -96,17 +96,17 @@ fileserver: value: 10.0.0.103 ``` -#### Auto-generated PTRs +### Auto-generated PTRs * 101.0.0.10: exxampled.com. * 102.0.0.10: exxampled.com. * 103.0.0.10: email.exxampled.com., fileserver.exxampled.com. -### Notes +## Notes Automatic `PTR` generation requires a "complete" picture of records and thus cannot be done during partial syncs. Thus syncing `arpa.` zones will throw an error any time filtering of zones, targets, or sources is being done. -#### AutoArpa and Dynamic Zone Config +### AutoArpa and Dynamic Zone Config The AutoArpa provider works with Dynamic Zone Config, but only in the sense that it doesn't stop it from working. It requires another provider to actually generate the list of zones. It could be the Yaml provider like so: diff --git a/docs/dynamic_records.md b/docs/dynamic_records.md index e3e2faf..c0eeebf 100644 --- a/docs/dynamic_records.md +++ b/docs/dynamic_records.md @@ -1,10 +1,10 @@ -## Dynamic Record Support +# Dynamic Record Support Dynamic records provide support for GeoDNS and weighting to records. `A` and `AAAA` are fully supported and reasonably well tested for both Dyn (via Traffic Directors) and Route53. There is preliminary support for `CNAME` records, but caution should be exercised as they have not been thoroughly tested. Configuring GeoDNS is complex and the details of the functionality vary widely from provider to provider. octoDNS has an opinionated view mostly to give a reasonably consistent behavior across providers which is similar to the overall philosophy and approach of octoDNS itself. It may not fit your needs or use cases, in which case please open an issue for discussion. We expect this functionality to grow and evolve over time as it's more widely used. -### An Annotated Example +## An Annotated Example ```yaml @@ -75,9 +75,9 @@ test: - 7.7.7.7 ``` -If you encounter validation errors in dynamic records suggesting best practices that you have specific reasons for not following see [docs/records.md#Lenience](/docs/records.md#Lenience) for how to turn the errors into warnings. Doing so is taking on the burden of thoroughly testing and verifying that what you're doing behaves the way you expect. You may well encounter situations where the octoDNS providers and/or the underlying DNS services do not behave as desired. +If you encounter validation errors in dynamic records suggesting best practices that you have specific reasons for not following see [records.md#Lenience](records.md#Lenience) for how to turn the errors into warnings. Doing so is taking on the burden of thoroughly testing and verifying that what you're doing behaves the way you expect. You may well encounter situations where the octoDNS providers and/or the underlying DNS services do not behave as desired. -#### Visual Representation of the Rules and Pools +### Visual Representation of the Rules and Pools ```mermaid --- @@ -108,7 +108,7 @@ flowchart LR -#### Geo Codes +### Geo Codes Geo codes consist of one to three parts depending on the scope of the area being targeted. Examples of these look like: @@ -128,7 +128,7 @@ The first portion is the continent: The second is the two-letter ISO Country Code https://en.wikipedia.org/wiki/ISO_3166-2 and the third is the ISO Country Code Subdivision as per https://en.wikipedia.org/wiki/ISO_3166-2:US. Change the code at the end for the country you are subdividing. Note that these may not always be supported depending on the providers in use. -#### Subnets +### Subnets Dynamic record rules also support subnet targeting in some providers: @@ -145,7 +145,7 @@ Dynamic record rules also support subnet targeting in some providers: ... ``` -### Rule ordering +## Rule ordering octoDNS has validations in place to ensure that sources have the rules ordered from the most specific match to the least specific match per the following categories: @@ -158,7 +158,7 @@ The first 3 categories are optional, while the last one is mandatory. Subnet targeting is considered more specific than geo targeting. This means that if there is a subnet rule match as well as a geo rule match, subnet match must take precedence. Provider implementations must ensure this behavior of targeting precedence. -### Health Checks +## Health Checks octoDNS will automatically configure the provider to monitor each IP and check for a 200 response for **https:///_dns**. diff --git a/docs/examples/README.md b/docs/examples/README.md index f3adfa1..134632d 100644 --- a/docs/examples/README.md +++ b/docs/examples/README.md @@ -1,11 +1,4 @@ -### This is all a WIP - -This is a WIP and will definitely be rough around the edges, but in the spirit -of not letting perfect get in the way of good enough, or really existing at -all. It's being uploaded as a starting point. PRs/suggestions welcome as are -ideas for other subjects to cover. - -### Examples +# Examples * Getting started with a [basic octoDNS configuration](basic/) - new to octoDNS this is the place to start. It'll walk you through the main pieces of DNS IaC @@ -16,7 +9,12 @@ ideas for other subjects to cover. pull the existing data out of your provider into matching YAML config files on disk. -### Running PowerDNS +This is a WIP and will definitely be rough around the edges, but in the spirit +of not letting perfect get in the way of good enough, or really existing at +all. It's being uploaded as a starting point. PRs/suggestions welcome as are +ideas for other subjects to cover. + +## Running PowerDNS If you'd like to play around with running the examples in this directory interactively you'll need a target for pushing data to. diff --git a/docs/geo_records.md b/docs/geo_records.md index e6486b1..92fa559 100644 --- a/docs/geo_records.md +++ b/docs/geo_records.md @@ -1,4 +1,4 @@ -## Geo Record Support +# Geo Record Support Note: Geo DNS records are still supported for the time being, but it is still strongly encouraged that you look at [Dynamic Records](/docs/dynamic_records.md) instead as they are a superset of functionality. @@ -52,7 +52,7 @@ So the example is saying: - Europe: gets an "A" record of 111.111.111.4 - Everyone else gets an "A" record of 111.111.111.5 -### Health Checks +## Health Checks octoDNS will automatically set up monitors check for a 200 response for **https:///_dns**. @@ -81,7 +81,7 @@ test: | port | port to check | 443 | | protocol | HTTP/HTTPS | HTTPS | -#### Route53 Healtch Check Options +### Route53 Healtch Check Options | Key | Description | Default | |--|--|--| diff --git a/docs/index.md b/docs/index.md index 90f0905..65812cc 100644 --- a/docs/index.md +++ b/docs/index.md @@ -14,6 +14,7 @@ ______________________________________________________________________ :caption: Getting Started: :maxdepth: 1 +examples/README.md examples/basic/README.md examples/migrating-to-octodns/README.md records.md @@ -25,8 +26,6 @@ records.md :glob: [a-q]* -#records.md -[s-z]* ``` ______________________________________________________________________