CDK Certbot DNS Route53

2.5.18 · active · verified Thu Apr 16

This Python AWS CDK construct automates the process of obtaining and renewing Let's Encrypt SSL/TLS certificates using Certbot. It leverages AWS Lambda to run Certbot, Route53 for DNS-01 challenges, and stores the certificates in an S3 bucket. The current version is 2.5.18, with releases occurring periodically to support new CDK features and bug fixes.

Common errors

```
AccessDeniedException: User: arn:aws:iam::... is not authorized to perform: route53:ChangeResourceRecordSets on resource: arn:aws:route53:::hostedzone/...
```
cause The IAM principal deploying the CDK stack lacks the necessary permissions to modify Route53 records, which is critical for the DNS-01 challenge.

fix Ensure the IAM user or role used for `cdk deploy` has permissions such as `route53:ChangeResourceRecordSets`, `route53:ListHostedZones`, `route53:GetHostedZone` for the relevant hosted zone. Also verify permissions for S3, Lambda, and EventBridge.
```
Stack deployment failed: Error: The Hosted Zone ID 'YOUR_HOSTED_ZONE_ID' does not exist.
```
cause The `hosted_zone_id` provided to the `CdkCertbotDnsRoute53` construct does not match any existing Route53 Hosted Zone in the specified AWS account and region.

fix Verify that the `hosted_zone_id` is absolutely correct and belongs to the AWS account and region where you are deploying the stack. You can find hosted zone IDs in the AWS Route53 console.
```
ValueError: Domain name cannot be empty. (or similar validation error for required properties)
```
cause One or more mandatory properties of the `CdkCertbotDnsRoute53` construct (e.g., `domain_name`, `certbot_email`, `hosted_zone_id`) were not provided or were set to an empty string.

fix Review your construct instantiation and ensure all required parameters are passed with valid, non-empty values. Refer to the construct's documentation or quickstart example for required properties.
```
Function execution failed. For details, see the CloudWatch logs for the Lambda function 'CertbotLambdaFunction...'.
```
cause The Certbot Lambda function encountered an error during its execution, likely due to an issue with Certbot itself, network configuration, or an unexpected state during certificate issuance/renewal.

fix Check the detailed logs for the 'CertbotLambdaFunction' in AWS CloudWatch. Common causes include temporary network issues, Let's Encrypt rate limits, incorrect domain configuration, or issues with Lambda's VPC/Security Group setup if provided.

Warnings

breaking This library is built for AWS CDK v2. Attempting to use it with a CDK v1 project will result in breaking changes and deployment failures due to API differences.
Fix: Ensure your project uses `aws-cdk-lib` (CDK v2) and `constructs>=10.0.0`. If migrating from v1, consult the official AWS CDK v2 migration guide.
gotcha The AWS IAM user/role deploying the stack requires specific permissions for Route53 (to manage DNS records), S3 (to store certificates), Lambda (to create and execute the Certbot function), and EventBridge (for scheduled certificate renewal). Missing permissions will cause `cdk deploy` to fail with `AccessDenied` errors.
Fix: Grant the necessary IAM permissions. Refer to the library's GitHub README for a detailed list of required permissions or start with broader permissions (e.g., `Route53FullAccess`, `S3FullAccess`, `LambdaFullAccess`, `EventBridgeFullAccess`) during development and narrow them down for production.
gotcha The `domain_name`, `hosted_zone_id`, and `certbot_email` properties are mandatory. Providing incorrect or non-existent values for `domain_name` or `hosted_zone_id` will lead to deployment errors or certificate issuance failures.
Fix: Double-check that `domain_name` is your actual domain and `hosted_zone_id` corresponds to the correct Route53 hosted zone in your AWS account and region. Ensure a valid email is provided for `certbot_email` to receive renewal notifications from Let's Encrypt.
gotcha Let's Encrypt has strict rate limits for certificate issuance. Repeatedly requesting certificates for the same domain or subdomain in a short period can lead to temporary blocks, especially during development and testing.
Fix: During testing, consider using Let's Encrypt's staging environment if available (not directly supported by this construct out-of-the-box, but a general Certbot consideration), or ensure you are not hitting the rate limits by waiting between attempts or reusing existing certificates for testing purposes.

Install

pip install cdk-certbot-dns-route53 Install with pip

Imports

CdkCertbotDnsRoute53
wrong:
```
from cdk_certbot_dns_route53 import CdkCertbotDnsRoute53
```
correct:
```
from cdk_certbot_dns_route53.constructs import CdkCertbotDnsRoute53
```
The main construct is located within the 'constructs' submodule, not directly under the top-level package.

Quickstart

This quickstart demonstrates how to integrate the `CdkCertbotDnsRoute53` construct into an AWS CDK application. Replace the placeholder values for `domain_name`, `hosted_zone_id`, and `certbot_email` with your actual domain information. The example assumes `CDK_DEFAULT_ACCOUNT` and `CDK_DEFAULT_REGION` are set in your environment, but provides fallback placeholders. After synthesizing, deploy the stack using `cdk deploy CertbotStack`.

import os
from aws_cdk import App, Stack, Environment
from cdk_certbot_dns_route53.constructs import CdkCertbotDnsRoute53

# AWS environment details. For production, ensure these are correctly configured.
# The AWS account and region for deployment. Using default placeholders for demonstration.
account = os.environ.get("CDK_DEFAULT_ACCOUNT", "123456789012") # Replace with your AWS Account ID
region = os.environ.get("CDK_DEFAULT_REGION", "us-east-1") # Replace with your AWS Region

app = App()

env_config = Environment(account=account, region=region)

stack = Stack(
    app,
    "CertbotStack",
    env=env_config,
    description="A stack for managing Certbot with Route53 and S3.",
)

# Instantiate the CdkCertbotDnsRoute53 construct
CdkCertbotDnsRoute53(
    stack,
    "CertbotConstruct",
    domain_name="your-actual-domain.com", # REQUIRED: Replace with your actual domain name
    hosted_zone_id="Z1ABCD2EFGHIJ3KLMNO4", # REQUIRED: Replace with your Hosted Zone ID for the domain
    certbot_email="admin@your-actual-domain.com", # REQUIRED: Replace with your email for Certbot notifications
    # sns_topic_arn="arn:aws:sns:REGION:ACCOUNT_ID:certbot-notifications", # OPTIONAL: Uncomment and replace for SNS notifications
)

app.synth()

# To deploy this stack, navigate to the directory containing this code and run:
# cdk deploy CertbotStack --require-approval never

view raw JSON →