{"id":8889,"library":"cdk-certbot-dns-route53","title":"CDK Certbot DNS Route53","description":"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.","status":"active","version":"2.5.18","language":"en","source_language":"en","source_url":"https://github.com/neilkuan/cdk-certbot-dns-route53.git","tags":["aws-cdk","certbot","let's-encrypt","route53","dns-01","lambda","s3","aws","ssl","tls"],"install":[{"cmd":"pip install cdk-certbot-dns-route53","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core AWS CDK library, required for all CDK constructs.","package":"aws-cdk-lib","optional":false},{"reason":"Required for defining CDK constructs.","package":"constructs","optional":false}],"imports":[{"note":"The main construct is located within the 'constructs' submodule, not directly under the top-level package.","wrong":"from cdk_certbot_dns_route53 import CdkCertbotDnsRoute53","symbol":"CdkCertbotDnsRoute53","correct":"from cdk_certbot_dns_route53.constructs import CdkCertbotDnsRoute53"}],"quickstart":{"code":"import os\nfrom aws_cdk import App, Stack, Environment\nfrom cdk_certbot_dns_route53.constructs import CdkCertbotDnsRoute53\n\n# AWS environment details. For production, ensure these are correctly configured.\n# The AWS account and region for deployment. Using default placeholders for demonstration.\naccount = os.environ.get(\"CDK_DEFAULT_ACCOUNT\", \"123456789012\") # Replace with your AWS Account ID\nregion = os.environ.get(\"CDK_DEFAULT_REGION\", \"us-east-1\") # Replace with your AWS Region\n\napp = App()\n\nenv_config = Environment(account=account, region=region)\n\nstack = Stack(\n    app,\n    \"CertbotStack\",\n    env=env_config,\n    description=\"A stack for managing Certbot with Route53 and S3.\",\n)\n\n# Instantiate the CdkCertbotDnsRoute53 construct\nCdkCertbotDnsRoute53(\n    stack,\n    \"CertbotConstruct\",\n    domain_name=\"your-actual-domain.com\", # REQUIRED: Replace with your actual domain name\n    hosted_zone_id=\"Z1ABCD2EFGHIJ3KLMNO4\", # REQUIRED: Replace with your Hosted Zone ID for the domain\n    certbot_email=\"admin@your-actual-domain.com\", # REQUIRED: Replace with your email for Certbot notifications\n    # sns_topic_arn=\"arn:aws:sns:REGION:ACCOUNT_ID:certbot-notifications\", # OPTIONAL: Uncomment and replace for SNS notifications\n)\n\napp.synth()\n\n# To deploy this stack, navigate to the directory containing this code and run:\n# cdk deploy CertbotStack --require-approval never","lang":"python","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"< 2.0.0 (for this library), all CDK v1 projects."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The IAM principal deploying the CDK stack lacks the necessary permissions to modify Route53 records, which is critical for the DNS-01 challenge.","error":"AccessDeniedException: User: arn:aws:iam::... is not authorized to perform: route53:ChangeResourceRecordSets on resource: arn:aws:route53:::hostedzone/..."},{"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.","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.","error":"Stack deployment failed: Error: The Hosted Zone ID 'YOUR_HOSTED_ZONE_ID' does not exist."},{"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.","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.","error":"ValueError: Domain name cannot be empty. (or similar validation error for required properties)"},{"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.","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.","error":"Function execution failed. For details, see the CloudWatch logs for the Lambda function 'CertbotLambdaFunction...'."}]}