mirror/github-octodns
1
0
Fork 0
mirror of https://github.com/github/octodns.git synced 2024-05-11 05:55:00 +00:00
Code Issues Releases Activity

Pass at documenting dynamic record support

Browse Source 
Bit of general doc cleanup and refactoring while I'm in here.
This commit is contained in:
Ross McFarland
2019-05-03 09:16:06 -07:00
parent 65ee60491e
commit 470daa8843
3 changed files with 230 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files

126
docs/dynamic_records.md Normal file
View File

@@ -0,0 +1,126 @@
## 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
```yaml
---
test:
# This is a dynamic record when used with providers that support it
dynamic:
# These are the pools of records that can be referenced and thus used by rules
pools:
apac:
# An optional fallback, if all of the records in this pool fail this pool should be tried
fallback: na
# One or more values for this pool
values:
- value: 1.1.1.1
- value: 2.2.2.2
eu:
fallback: na
values:
- value: 3.3.3.3
# Weight for this value, if omitted the default is 1
weight: 2
- value: 4.4.4.4
weight: 3
na:
# Implicit fallback to the default pool (below)
values:
- value: 5.5.5.5
- value: 6.6.6.6
- value: 7.7.7.7
# Rules that assign queries to pools
rules:
- geos:
# Geos used in matching queries
- AS
- OC
# The pool to service the query from
pool: apac
- geos:
- AF
- EU
pool: eu
# No geos means match all queries
- pool: na
ttl: 60
type: A
# These values become a non-healthchecked default pool
values:
- 5.5.5.5
- 6.6.6.6
- 7.7.7.7
```
#### Geo Codes
Geo codes consist of one to three parts depending on the scope of the area being targeted. Examples of these look like:
* 'NA-US-KY' - North America, United States, Kentucky
* 'NA-US' - North America, United States
* 'NA' - North America
The first portion is the continent:
* 'AF': 14, # Continental Africa
* 'AN': 17, # Continental Antarctica
* 'AS': 15, # Continental Asia
* 'EU': 13, # Continental Europe
* 'NA': 11, # Continental North America
* 'OC': 16, # Continental Australia/Oceania
* 'SA': 12, # Continental South America
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.
### Health Checks
octoDNS will automatically configure the provider to monitor each IP and check for a 200 response for **https://<ip_address>/_dns**.
These checks can be customized via the `healthcheck` configuration options.
```yaml
---
test:
...
octodns:
healthcheck:
host: my-host-name
path: /dns-health-check
port: 443
protocol: HTTPS
...
```
| Key | Description | Default |
|--|--|--|
| host | FQDN for host header and SNI | - |
| path | path to check | _dns |
| port | port to check | 443 |
| protocol | HTTP/HTTPS | HTTPS |
#### Route53 Healtch Check Options
| Key | Description | Default |
|--|--|--|
| measure_latency | Show latency in AWS console | true |
```yaml
---
octodns:
healthcheck:
host: my-host-name
path: /dns-health-check
port: 443
protocol: HTTPS
route53:
healthcheck:
measure_latency: false
```

101
docs/geo_records.md Normal file
View File

@@ -0,0 +1,101 @@
## Geo Record Support
Note: Geo DNS records are still supported for the time being, but it is still strongy encouraged that you look at [Dynamic Records](/docs/dynamic_records.md) instead as they are a superset of functionality.
GeoDNS is currently supported for `A` and `AAAA` records on the Dyn (via Traffic Directors) and Route53 providers. Records with geo information pushed to providers without support for them will be managed as non-geo records using the base values.
Configuring GeoDNS is complex and the details of the functionality vary widely from provider to provider. OctoDNS has an opinionated view of how GeoDNS should be set up and does its best to map that to each provider's offering in a way that will result in similar behavior. 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.
The following is an example of GeoDNS with three entries NA-US-CA, NA-US-NY, OC-AU. Octodns creates another one labeled 'default' with the details for the actual A record, This default record is the failover record if the monitoring check fails.
```yaml
---
? ''
: type: TXT
value: v=spf1 -all
test:
geo:
NA-US-NY:
- 111.111.111.1
NA-US-CA:
- 111.111.111.2
OC-AU:
- 111.111.111.3
EU:
- 111.111.111.4
ttl: 300
type: A
value: 111.111.111.5
```
The geo labels breakdown based on:
1.
- 'AF': 14, # Continental Africa
- 'AN': 17, # Continental Antarctica
- 'AS': 15, # Continental Asia
- 'EU': 13, # Continental Europe
- 'NA': 11, # Continental North America
- 'OC': 16, # Continental Australia/Oceania
- 'SA': 12, # Continental South America
2. ISO Country Code https://en.wikipedia.org/wiki/ISO_3166-2
3. 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) * these may not always be supported depending on the provider.
So the example is saying:
- North America - United States - New York: gets served an "A" record of 111.111.111.1
- North America - United States - California: gets served an "A" record of 111.111.111.2
- Oceania - Australia: Gets served an "A" record of 111.111.111.3
- Europe: gets an "A" record of 111.111.111.4
- Everyone else gets an "A" record of 111.111.111.5
### Health Checks
Octodns will automatically set up monitors check for a 200 response for **https://<ip_address>/_dns**.
These checks can be configured by adding a `healthcheck` configuration to the record:
```yaml
---
test:
geo:
AS:
- 1.2.3.4
EU:
- 2.3.4.5
octodns:
healthcheck:
host: my-host-name
path: /dns-health-check
port: 443
protocol: HTTPS
```
| Key | Description | Default |
|--|--|--|
| host | FQDN for host header and SNI | - |
| path | path to check | _dns |
| port | port to check | 443 |
| protocol | HTTP/HTTPS | HTTPS |
#### Route53 Healtch Check Options
| Key | Description | Default |
|--|--|--|
| measure_latency | Show latency in AWS console | true |
```yaml
---
octodns:
healthcheck:
host: my-host-name
path: /dns-health-check
port: 443
protocol: HTTPS
route53:
healthcheck:
measure_latency: false
```

102
docs/records.md
View File

@@ -20,106 +20,10 @@ Underlying provider support for each of these varies and some providers have ext
Adding new record types to OctoDNS is relatively straightforward, but will require careful evaluation of each provider to determine whether or not it will be supported and the addition of code in each to handle and test the new type.
## GeoDNS support
GeoDNS is currently supported for `A` and `AAAA` records on the Dyn (via Traffic Directors) and Route53 providers. Records with geo information pushed to providers without support for them will be managed as non-geo records using the base values.
Configuring GeoDNS is complex and the details of the functionality vary widely from provider to provider. OctoDNS has an opinionated view of how GeoDNS should be set up and does its best to map that to each provider's offering in a way that will result in similar behavior. 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.
The following is an example of GeoDNS with three entries NA-US-CA, NA-US-NY, OC-AU. Octodns creates another one labeled 'default' with the details for the actual A record, This default record is the failover record if the monitoring check fails.
```yaml
---
? ''
: type: TXT
value: v=spf1 -all
test:
geo:
NA-US-NY:
- 111.111.111.1
NA-US-CA:
- 111.111.111.2
OC-AU:
- 111.111.111.3
EU:
- 111.111.111.4
ttl: 300
type: A
value: 111.111.111.5
```
The geo labels breakdown based on:
1.
- 'AF': 14, # Continental Africa
- 'AN': 17, # Continental Antarctica
- 'AS': 15, # Continental Asia
- 'EU': 13, # Continental Europe
- 'NA': 11, # Continental North America
- 'OC': 16, # Continental Australia/Oceania
- 'SA': 12, # Continental South America
2. ISO Country Code https://en.wikipedia.org/wiki/ISO_3166-2
3. ISO Country Code Subdevision as per https://en.wikipedia.org/wiki/ISO_3166-2:US (change the code at the end for the country you are subdividing) * these may not always be supported depending on the provider.
So the example is saying:
- North America - United States - New York: gets served an "A" record of 111.111.111.1
- North America - United States - California: gets served an "A" record of 111.111.111.2
- Oceania - Australia: Gets served an "A" record of 111.111.111.3
- Europe: gets an "A" record of 111.111.111.4
- Everyone else gets an "A" record of 111.111.111.5
### Health Checks
Octodns will automatically set up monitors for each IP and check for a 200 response for **https://<ip_address>/_dns**.
These checks can be configured by adding a `healthcheck` configuration to the record:
```yaml
---
test:
geo:
AS:
- 1.2.3.4
EU:
- 2.3.4.5
octodns:
healthcheck:
host: my-host-name
path: /dns-health-check
port: 443
protocol: HTTPS
```
| Key | Description | Default |
|--|--|--|
| host | FQDN for host header and SNI | - |
| path | path to check | _dns |
| port | port to check | 443 |
| protocol | HTTP/HTTPS | HTTPS |
#### Route53 Healtch Check Options
| Key | Description | Default |
|--|--|--|
| measure_latency | Show latency in AWS console | true |
```yaml
---
octodns:
healthcheck:
host: my-host-name
path: /dns-health-check
port: 443
protocol: HTTPS
route53:
healthcheck:
measure_latency: false
```
## Advanced Record Support (GeoDNS, Weighting)
* [Dynamic Records](/docs/dynamic_records.md)
* [Geo Records](/docs/geo_records.md)
## Config (`YamlProvider`)