AWS Route 53

ddup can manage records in a hosted zone on Amazon Route 53. It needs the ID of the hosted zone, and AWS credentials that are allowed to list and change the zone’s records.

Example#

This configuration uses the credentials that the AWS SDK finds in the environment, such as an IAM role when ddup runs on AWS:

providers:
  route53-main:
    awsRoute53:
      hostedZoneId: "Z0123456789ABCDEFGHIJ"

domains:
  - recordName: "app.example.com"
    provider: "route53-main"
    endpoints:
      - name: "web1"
        url: "http://192.0.2.10/healthz"
        ip: "192.0.2.10"
      - name: "web2"
        url: "http://192.0.2.11/healthz"
        ip: "192.0.2.11"

See Authentication to use an access key instead.

Options#

Each provider entry manages one hosted zone. To manage records in several zones, add an entry for each zone.

Getting the hosted zone ID#

In the Route 53 console, the ID is in the Hosted zone ID column of the list of hosted zones.

With the AWS CLI:

aws route53 list-hosted-zones-by-name \
  --dns-name example.com \
  --query "HostedZones[0].Id" --output text

Both public and private hosted zones work. If you have a public and a private zone with the same name, make sure you pick the right one.

Authentication#

ddup picks how to authenticate based on the options you set:

Whichever method you choose, the identity needs the permissions in Permissions.

At startup, ddup logs which method it’s using: Authenticating to AWS with static credentials or Authenticating to AWS with the default credential chain.

Access key#

Use an access key when ddup runs outside of AWS. Save the policy as ddup-policy.json, then create an IAM user with that policy and an access key:

aws iam create-user --user-name ddup

aws iam put-user-policy \
  --user-name ddup \
  --policy-name ddup-route53 \
  --policy-document file://ddup-policy.json

aws iam create-access-key --user-name ddup

The output of the last command contains the AccessKeyId and the SecretAccessKey:

providers:
  route53-main:
    awsRoute53:
      hostedZoneId: "Z0123456789ABCDEFGHIJ"
      accessKeyId: "AKIAIOSFODNN7EXAMPLE"
      secretAccessKey: !file /run/secrets/aws-secret-access-key

Access keys don’t expire on their own, so anyone who gets the key can use it until you delete it. When ddup runs on AWS, use a role instead.

Default credential chain#

When you don’t set accessKeyId and secretAccessKey, ddup looks for credentials the same way as the AWS CLI and SDKs, in places that include:

• The AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables, plus AWS_SESSION_TOKEN for temporary credentials
• The shared configuration and credentials files in ~/.aws, with the profile in AWS_PROFILE
• IAM roles for service accounts on Amazon EKS
• Task roles on Amazon ECS
• Instance profiles on Amazon EC2

See the AWS documentation for the full list.

For example, to pass an access key as environment variables with Docker:

docker run -d \
  --name ddup \
  --read-only \
  -v $HOME/.ddup:/etc/ddup:ro \
  -e AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE" \
  -e AWS_SECRET_ACCESS_KEY="your-secret-access-key" \
  ghcr.io/italypaleale/ddup:v0

Permissions#

The identity that ddup uses needs permission to list and change the record sets of the hosted zone. Replace <your-zone-id> with the ID of your hosted zone:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "route53:ListResourceRecordSets",
        "route53:ChangeResourceRecordSets"
      ],
      "Resource": "arn:aws:route53:::hostedzone/<your-zone-id>"
    }
  ]
}

This policy allows changing every record in the zone. To allow only the names and record types that ddup manages, add conditions on ChangeResourceRecordSets. List the names in lowercase, without the trailing dot:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "route53:ListResourceRecordSets",
      "Resource": "arn:aws:route53:::hostedzone/Z0123456789ABCDEFGHIJ"
    },
    {
      "Effect": "Allow",
      "Action": "route53:ChangeResourceRecordSets",
      "Resource": "arn:aws:route53:::hostedzone/Z0123456789ABCDEFGHIJ",
      "Condition": {
        "ForAllValues:StringEquals": {
          "route53:ChangeResourceRecordSetsNormalizedRecordNames": [
            "app.example.com"
          ],
          "route53:ChangeResourceRecordSetsRecordTypes": [
            "A",
            "AAAA"
          ]
        }
      }
    }
  ]
}

Things to know#

• Only record sets with simple routing are supported. If the name already has an alias record, or a record set with another routing policy such as weighted, latency, or failover, the update fails with an error.
• The A and AAAA record sets with the domain’s name are replaced, including records you created in the console. See How ddup manages records.