From dffbea201b8ba78c57dacbd84c9aee401e8e559b Mon Sep 17 00:00:00 2001 From: Michael Shen Date: Fri, 16 Aug 2024 18:37:34 -0400 Subject: [PATCH] Add tutorial to DynamoDB registry docs The existing docs described how to configure the DynamoDB registry, but didn't have a tutorial for someone to walk through. Signed-off-by: Michael Shen --- docs/registry/dynamodb.md | 150 ++++++++++++++++++++++++++++++++++---- docs/tutorials/aws.md | 4 + 2 files changed, 139 insertions(+), 15 deletions(-) diff --git a/docs/registry/dynamodb.md b/docs/registry/dynamodb.md index 8f5cc4b438..895cc57930 100644 --- a/docs/registry/dynamodb.md +++ b/docs/registry/dynamodb.md @@ -1,19 +1,11 @@ # The DynamoDB registry -The DynamoDB registry stores DNS record metadata in an AWS DynamoDB table. - -## The DynamoDB Table - -By default, the DynamoDB registry stores data in the table named `external-dns`. -A different table may be specified using the `--dynamodb-table` flag. -A different region may be specified using the `--dynamodb-region` flag. - -The table must have a partition (hash) key named `k` and string type. -The table must not have a sort (range) key. +As opposed to the default TXT registry, the DynamoDB registry stores DNS record metadata in an AWS DynamoDB table instead of in TXT records in a hosted zone. +This following tutorial extends [Setting up ExternalDNS for Services on AWS](../tutorials/aws.md) to use the DynamoDB registry instead. ## IAM permissions -The ExternalDNS Role must be granted the following permissions: +The ExternalDNS IAM policy from [IAM Policy](../tutorials/aws.md#iam-policy) must additionally be granted the following permissions: ```json { @@ -31,12 +23,140 @@ The ExternalDNS Role must be granted the following permissions: } ``` -The region and account ID may be specified explicitly specified instead of using wildcards. +The region and account ID may be specified explicitly specified instead of using wildcards. + +## Create a DynamoDB Table + +By default, the DynamoDB registry stores data in the table named `external-dns` and it needs to exist before configuring ExternalDNS to use the DynamoDB registry. +If the DynamoDB table has a different name, it may be specified using the `--dynamodb-table` flag. +If the DynamoDB table is in a different region, it may be specified using the `--dynamodb-region` flag. + +The following command creates a DynamoDB table with the name: `external-dns`: + +> The table must have a partition (HASH) key named `k` of type string (`S`) and the table must NOT have a sort (RANGE) key. + +```bash +aws dynamodb create-table \ + --table-name external-dns \ + --attribute-definitions \ + AttributeName=k,AttributeType=S \ + --key-schema \ + AttributeName=k,KeyType=HASH \ + --provisioned-throughput \ + ReadCapacityUnits=5,WriteCapacityUnits=5 \ + --table-class STANDARD +``` + +## Set up a hosted zone + +Follow [Set up a hosted zone](../tutorials/aws.md#set-up-a-hosted-zone) + +## Modify ExternalDNS deployment + +The ExternalDNS deployment from [Deploy ExternalDNS](../tutorials/aws.md#deploy-externaldns) needs the following modifications: + +* `--registry=txt` should be changed to `--registry=dynamodb` +* Add `--dynamodb-table=external-dns` to specify the name of the DynamoDB table, its value defaults to `external-dns` +* Add `--dynamodb-region=us-east-1` to specify the region of the DynamoDB table + +For example: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: external-dns + labels: + app.kubernetes.io/name: external-dns +spec: + strategy: + type: Recreate + selector: + matchLabels: + app.kubernetes.io/name: external-dns + template: + metadata: + labels: + app.kubernetes.io/name: external-dns + spec: + containers: + - name: external-dns + image: registry.k8s.io/external-dns/external-dns:v0.14.1 + args: + - --source=service + - --source=ingress + - --domain-filter=example.com # will make ExternalDNS see only the hosted zones matching provided domain, omit to process all available hosted zones + - --provider=aws + - --policy=upsert-only # would prevent ExternalDNS from deleting any records, omit to enable full synchronization + - --aws-zone-type=public # only look at public hosted zones (valid values are public, private or no value for both) + - --registry=dynamodb # previously, --registry=txt + - --dynamodb-table=external-dns # defaults to external-dns + - --dynamodb-region=us-east-1 # set to the region the DynamoDB table in + - --txt-owner-id=my-hostedzone-identifier + env: + - name: AWS_DEFAULT_REGION + value: us-east-1 # change to region where EKS is installed + # # Uncomment below if using static credentials + # - name: AWS_SHARED_CREDENTIALS_FILE + # value: /.aws/credentials + # volumeMounts: + # - name: aws-credentials + # mountPath: /.aws + # readOnly: true + # volumes: + # - name: aws-credentials + # secret: + # secretName: external-dns +``` + +## Validate ExternalDNS works + +Create either a [Service](../tutorials/aws.md#verify-externaldns-works-service-example) or an [Ingress](../tutorials/aws.md#verify-externaldns-works-ingress-example) and + +After roughly two minutes, check that the corresponding entry was created in the DynamoDB table: + +```bash +aws dynamodb scan --table-name external-dns +``` + +This will show something like: +``` +{ + "Items": [ + { + "k": { + "S": "nginx.example.com#A#" + }, + "o": { + "S": "my-identifier" + }, + "l": { + "M": { + "resource": { + "S": "service/default/nginx" + } + } + } + } + ], + "Count": 1, + "ScannedCount": 1, + "ConsumedCapacity": null +} +``` + +## Clean up + +In addition to the clean up steps in [Setting up ExternalDNS for Services on AWS](../tutorials/aws.md#clean-up), delete the DynamoDB table that was used as a registry. + +```bash +aws dynamodb delete-table \ + --table-name external-dns +``` ## Caching -The DynamoDB registry can optionally cache DNS records read from the provider. This can mitigate -rate limits imposed by the provider. +The DynamoDB 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. @@ -48,4 +168,4 @@ the metadata therein to the DynamoDB table. If any such TXT records exist, any p must be supplied. If TXT records are in the set of managed record types specified by `--managed-record-types`, -it will then delete the ownership TXT records on a subsequent reconciliation. \ No newline at end of file +it will then delete the ownership TXT records on a subsequent reconciliation. diff --git a/docs/tutorials/aws.md b/docs/tutorials/aws.md index e836e6739a..2c303588c1 100644 --- a/docs/tutorials/aws.md +++ b/docs/tutorials/aws.md @@ -856,6 +856,10 @@ env: key: {{ YOUR_SECRET_KEY }} ``` +## DynamoDB Registry + +If you would like to leverage the DynamoDB registry instead of the TXT registry, see [The DynamoDB Registry](../registry/dynamodb.md) for modifications needed to do so. + ## Clean up Make sure to delete all Service objects before terminating the cluster so all load balancers get cleaned up correctly.