Certbot DNS Route53 Authenticator

5.5.0 · active · verified Thu Apr 16

certbot-dns-route53 is a plugin for Certbot that automates the process of completing a DNS-01 challenge using Amazon Web Services (AWS) Route 53. It handles the creation and removal of DNS TXT records required for domain validation with Let's Encrypt. The current version is 5.5.0, and it generally follows the release cadence of the main Certbot project.

Common errors

```
Unable to locate credentials To use certbot-dns-route53, configure credentials as described at https://boto3.readthedocs.io/en/latest/guide/configuration.html#best-practices-for-configuring-credentials and add the necessary permissions for Route53 access.
```
cause Certbot cannot find valid AWS credentials. This often happens when running Certbot with `sudo` while credentials are only configured for the non-root user, or if environment variables are not set.

fix Ensure `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables are correctly set for the user running `certbot`, or place credentials in `~/.aws/credentials` (or `/root/.aws/credentials` if using `sudo`). Using an IAM role on EC2 instances is a recommended best practice.
```
Challenge failed for domain example.com Type: dns Detail: DNS problem: looking up TXT for _acme-challenge.example.com: DNSKEY Missing
```
cause The Certificate Authority failed to verify the DNS TXT records. This can be due to DNSSEC misconfiguration, slow DNS propagation, or an incorrect hosted zone ID preventing record creation/lookup.

fix Verify that DNSSEC is correctly configured for your domain or disabled if not intentionally used. Check that the hosted zone is public and correctly configured in Route 53. If DNS propagation is slow, try increasing the `--dns-route53-propagation-seconds` value.
```
botocore.errorfactory.InvalidChangeBatch: Duplicate Resource Record
```
cause This error occurs when `certbot-dns-route53` attempts to create an identical TXT record twice within the same Route 53 record set, typically when requesting a certificate for both an apex domain and its wildcard simultaneously.

fix This is a known issue. As a workaround, you might need to request certificates for the apex domain and the wildcard domain in separate `certbot` runs, or await an upstream fix from the Certbot project.
```
Certbot failed to authenticate some domains (authenticator: dns-route53). The Certificate Authority reported these problems:...
```
cause A general authentication failure for the DNS-01 challenge. Common causes include insufficient IAM permissions, the domain not being managed by the specified Route 53 hosted zone, or other transient DNS issues.

fix Review your AWS IAM policy to ensure it has all required Route 53 permissions. Double-check that the domain(s) specified in the `certbot` command correspond to a hosted zone managed by your AWS account. Inspect Certbot's debug logs (`/var/log/letsencrypt/letsencrypt.log`) for more specific error details.

Warnings

breaking When upgrading Certbot to major versions (e.g., 5.x.x), underlying changes in Certbot's core or its dependencies might affect plugins. While `certbot-dns-route53` itself often remains stable at the plugin level, ensure your Certbot installation is compatible and update the plugin simultaneously. Specifically, Certbot 5.0.0 removed pyopenssl x509 and PKey objects, which could affect advanced programmatic interactions if you were relying on internal Certbot APIs.
Fix: Always update `certbot` and `certbot-dns-route53` together. Review Certbot's release notes for breaking changes, especially those related to plugin integration or internal API usage.
gotcha Incorrect AWS IAM Permissions: The AWS IAM user or role used by `certbot-dns-route53` must have specific permissions for Route 53. If these permissions are too restrictive or missing, Certbot will fail to create/delete DNS records, leading to authentication failures.
Fix: Ensure the IAM policy includes at least: `route53:ListHostedZones`, `route53:GetChange`, and `route53:ChangeResourceRecordSets`. For `ChangeResourceRecordSets`, it's recommended to restrict the `Resource` to specific hosted zones (`arn:aws:route53:::hostedzone/YOURHOSTEDZONEID`) for least privilege.
gotcha AWS Credentials Not Found (especially with `sudo`): When running `certbot` with `sudo`, it looks for AWS credentials in the `/root/` directory or environment variables for the root user. If your credentials (`~/.aws/credentials` or environment variables) are configured for your non-root user, Certbot will report that it's 'Unable to locate credentials'.
Fix: Avoid using `sudo` if possible by configuring Certbot's directories to be writable by your user. If `sudo` is necessary, ensure AWS credentials are either set as environment variables for the root user or present in `/root/.aws/credentials`. Alternatively, use IAM roles if running on an EC2 instance.
gotcha Duplicate TXT Record Error for Apex + Wildcard Domains: When requesting a certificate for both an apex domain (e.g., `example.com`) and its wildcard (e.g., `*.example.com`), Certbot might attempt to create the same `_acme-challenge` TXT record twice. Route 53 rejects duplicate TXT values within a record set, leading to a `botocore.errorfactory.InvalidChangeBatch: Duplicate Resource Record` error.
Fix: This is an upstream issue (Certbot #10593). Monitor Certbot releases for a fix. A potential workaround might involve requesting the apex and wildcard certificates separately if you encounter this, or manually cleaning up the TXT record between challenge attempts if using manual mode for debugging.
gotcha Slow DNS Propagation or Rate Limits with Many Domains: Requesting certificates for a large number of domains (e.g., 15+) in a single `certbot` command with `certbot-dns-route53` can lead to slow DNS propagation or connection resetting errors. The plugin processes updates sequentially, which can be time-consuming or hit API limits for large batches.
Fix: Consider splitting large requests into smaller batches, especially if domains belong to different hosted zones. If experiencing propagation issues, increase the propagation delay using `--dns-route53-propagation-seconds <seconds>`.

Install

pip install certbot-dns-route53 Install with pip

Imports

certbot-dns-route53
```
This is primarily a Certbot plugin used via the command line and typically not imported directly in Python code for its core functionality.
```
The plugin integrates with Certbot's command-line interface to perform DNS challenges, rather than offering a public Python API for direct application integration.

Quickstart

This quickstart demonstrates how to use `certbot-dns-route53` to obtain a wildcard certificate. It highlights the requirement to set AWS credentials via environment variables (or other `boto3` supported methods) and the basic `certbot` command line usage with the `--dns-route53` authenticator.

import os

# Set AWS credentials as environment variables. For production, consider IAM roles or ~/.aws/credentials.
# Ensure the IAM user/role has the necessary Route 53 permissions (see warnings).
os.environ['AWS_ACCESS_KEY_ID'] = os.environ.get('AWS_ACCESS_KEY_ID', 'YOUR_AWS_ACCESS_KEY_ID')
os.environ['AWS_SECRET_ACCESS_KEY'] = os.environ.get('AWS_SECRET_ACCESS_KEY', 'YOUR_AWS_SECRET_ACCESS_KEY')

# Example command to obtain a certificate for a domain and its wildcard using dns-route53 authenticator
# Replace example.com with your domain.
# For actual use, remove --dry-run to issue a real certificate.
# If running in a CI/CD pipeline, consider --non-interactive and --agree-tos.

print("Run this command in your terminal:")
print(f"certbot certonly --dns-route53 -d example.com -d *.example.com --email user@example.com --agree-tos --non-interactive --dry-run")

# To verify plugin availability, you can run:
# certbot plugins

view raw JSON →