Merge pull request #3652 from johngmyers/registry-doc

Improve registry documentation

README.md

@@ -63,11 +63,10 @@ ExternalDNS allows you to keep selected zones (via `--domain-filter`) synchroniz
 * [Plural](https://www.plural.sh/)
 * [Pi-hole](https://pi-hole.net/)
 
-From this release, ExternalDNS can become aware of the records it is managing (enabled via `--registry=txt`), therefore ExternalDNS can safely manage non-empty hosted zones. We strongly encourage you to use `v0.5` (or greater) with `--registry=txt` enabled and `--txt-owner-id` set to a unique value that doesn't change for the lifetime of your cluster. You might also want to run ExternalDNS in a dry run mode (`--dry-run` flag) to see the changes to be submitted to your DNS Provider API.
+ExternalDNS is, by default, aware of the records it is managing, therefore it can safely manage non-empty hosted zones. We strongly encourage you to set `--txt-owner-id` to a unique value that doesn't change for the lifetime of your cluster. You might also want to run ExternalDNS in a dry run mode (`--dry-run` flag) to see the changes to be submitted to your DNS Provider API.
 
 Note that all flags can be replaced with environment variables; for instance,
-`--dry-run` could be replaced with `EXTERNAL_DNS_DRY_RUN=1`, or
-`--registry txt` could be replaced with `EXTERNAL_DNS_REGISTRY=txt`.
+`--dry-run` could be replaced with `EXTERNAL_DNS_DRY_RUN=1`.
 
 ## Status of providers
 
@@ -237,17 +236,17 @@ If the service is not of type Loadbalancer you need the --publish-internal-servi
 Locally run a single sync loop of ExternalDNS.
 
 ```console
-external-dns --registry txt --txt-owner-id my-cluster-id --provider google --google-project example-project --source service --once --dry-run
+external-dns --txt-owner-id my-cluster-id --provider google --google-project example-project --source service --once --dry-run
 ```
 
 This should output the DNS records it will modify to match the managed zone with the DNS records you desire. It also assumes you are running in the `default` namespace. See the [FAQ](docs/faq.md) for more information regarding namespaces.
 
-Note: TXT records will have `my-cluster-id` value embedded. Those are used to ensure that ExternalDNS is aware of the records it manages.
+Note: TXT records will have the `my-cluster-id` value embedded. Those are used to ensure that ExternalDNS is aware of the records it manages.
 
 Once you're satisfied with the result, you can run ExternalDNS like you would run it in your cluster: as a control loop, and **not in dry-run** mode:
 
 ```console
-external-dns --registry txt --txt-owner-id my-cluster-id --provider google --google-project example-project --source service
+external-dns --txt-owner-id my-cluster-id --provider google --google-project example-project --source service
 ```
 
 Check that ExternalDNS has created the desired DNS record for your Service and that it points to its load balancer's IP. Then try to resolve it:

docs/registry/registry.md

@@ -0,0 +1,16 @@
+# Registries
+
+A registry persists metadata pertaining to DNS records.
+
+The most important metadata is the owning external-dns deployment.
+This is specified using the `--txt-owner-id` flag, specifying a value unique to the
+deployment of external-dns and which doesn't change for the lifetime of the deployment.
+Deployments in different clusters but sharing a DNS zone need to use different owner IDs.
+
+The registry implementation is specified using the `--registry` flag.
+
+## Supported registries
+
+* [txt](txt.md) (default) - Stores in TXT records in the same provider
+* noop - Passes metadata directly to the provider. For most providers, this means the metadata is not persisted.
+* aws-sd - Stores metadata in AWS Service Discovery. Only usable with the `aws-sd` provider.

docs/registry/txt.md

@@ -0,0 +1,97 @@
+# The TXT registry
+
+The TXT registry is the default registry.
+It stores DNS record metadata in TXT records, using the same provider.
+
+## Prefixes and Suffixes
+
+In order to avoid having the registry TXT records collide with
+TXT or CNAME records created from sources, you can configure a fixed prefix or suffix
+to be added to the first component of the domain of all registry TXT records.
+
+The prefix or suffix may not be changed after initial deployment,
+lest the registry records be orphaned and the metadata be lost.
+
+The prefix or suffix may contain the substring `%{record_type}`, which is replaced with
+the record type of the DNS record for which it is storing metadata.
+
+The prefix is specified using the `--txt-prefix` flag and the suffix is specified using
+the `--txt-suffix` flag. The two flags are mutually exclusive.
+
+## Wildcard Replacement
+
+The `--txt-wildcard-replacement` flag specifies a string to use to replace the "*" in
+registry TXT records for wildcard domains. Without using this, registry TXT records for
+wildcard domains will have invalid domain syntax and be rejected by most providers.
+
+## Encryption
+
+Registry TXT records may contain information, such as the internal ingress name or namespace, considered sensitive, , which attackers could exploit to gather information about your infrastructure. 
+By encrypting TXT records, you can protect this information from unauthorized access.
+
+Encryption is enabled by using the `--txt-encrypt-enabled` flag. The 32-byte AES-256-GCM encryption
+key must be specified in URL-safe base64 form, using the `--txt-encrypt-aes-key` flag.
+
+Note that the key used for encryption should be a secure key and properly managed to ensure the security of your TXT records.
+
+### Generating the TXT Encryption Key
+Python
+```python
+python -c 'import os,base64; print(base64.urlsafe_b64encode(os.urandom(32)).decode())'
+```
+
+Bash
+```shell
+dd if=/dev/urandom bs=32 count=1 2>/dev/null | base64 | tr -d -- '\n' | tr -- '+/' '-_'; echo
+```
+
+OpenSSL
+```shell
+openssl rand -base64 32 | tr -- '+/' '-_'
+```
+
+PowerShell
+```powershell
+# Add System.Web assembly to session, just in case
+Add-Type -AssemblyName System.Web
+[Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes([System.Web.Security.Membership]::GeneratePassword(32,4))).Replace("+","-").Replace("/","_")
+```
+
+Terraform
+```hcl
+resource "random_password" "txt_key" {
+  length           = 32
+  override_special = "-_"
+}
+```
+
+### Manually Encrypting/Decrypting TXT Records
+
+In some cases you might need to edit registry TXT records. The following example Go code encrypts and decrypts such records.
+
+```go
+package main
+
+import (
+	"fmt"
+	"sigs.k8s.io/external-dns/endpoint"
+)
+
+func main() {
+	key := []byte("testtesttesttesttesttesttesttest")
+	encrypted, _ := endpoint.EncryptText(
+		"heritage=external-dns,external-dns/owner=example,external-dns/resource=ingress/default/example",
+		key,
+		nil,
+	)
+	decrypted, _, _ := endpoint.DecryptText(encrypted, key)
+	fmt.Println(decrypted)
+}
+```
+
+## Caching
+
+The TXT registry can optionally cache DNS records read from the provider. This can mitigate
+rate limits imposed by the provider.
+
+Caching is enabled by specifying a cache duration with the `--txt-cache-interval` flag.

mkdocs.yml

@@ -6,19 +6,22 @@ repo_url: https://github.com/kubernetes-sigs/external-dns/
 
 nav:
   - index.md
+  - About:
+      - FAQ: faq.md
+      - Out of Incubator: 20190708-external-dns-incubator.md
+      - Code of Conduct: code-of-conduct.md
+      - License: LICENSE.md
   - Tutorials: tutorials/
+  - Registries:
+    - About: registry/registry.md
+    - TXT: registry/txt.md
   - Advanced Topics:
       - Initial Design: initial-design.md
       - TTL: ttl.md
   - Contributing:
       - Kubernetes Contributions: CONTRIBUTING.md
       - Release: release.md
       - contributing/*
-  - About:
-      - FAQ: faq.md
-      - Out of Incubator: 20190708-external-dns-incubator.md
-      - Code of Conduct: code-of-conduct.md
-      - License: LICENSE.md
 
 theme:
   name: material