AWS CDK AWS Certificate Manager Construct Library

1.204.0 · deprecated · verified Thu Apr 16

The `aws-cdk-aws-certificatemanager` package is a Construct Library for the AWS Cloud Development Kit (CDK) v1, providing constructs to provision and manage AWS Certificate Manager (ACM) certificates. ACM handles the complexity of creating, storing, and renewing SSL/TLS X.509 certificates for AWS services like CloudFront and Elastic Load Balancing. This package is part of the AWS CDK v1 ecosystem, which reached End-of-Support on June 1, 2023. Users are strongly encouraged to migrate to AWS CDK v2 for continued support and new features.

Common errors

```
The request has an invalid domain name. The domain name is not a valid DNS name. (ValidationException)
```
cause The `Certificate` construct in CDK v1 may not fully validate the `domainName` property during synthesis, leading to a CloudFormation deployment failure.

fix Carefully review the `domain_name` property passed to the `Certificate` construct. Ensure it's a valid DNS name, including wildcards if intended (e.g., `*.example.com`). Manually test domain name validity if unsure.
```
cdk deploy is stuck on AWS::CertificateManager::Certificate because of nameservers not matching / certificate pending validation
```
cause The Certificate Manager is waiting for domain ownership validation, but the required DNS records (e.g., CNAMEs) are either not created, incorrectly configured, or the Route 53 hosted zone's nameservers do not match the domain registrar's nameservers.

fix Verify that the CNAME records generated by ACM are correctly added to your DNS provider. If using Route 53, ensure the nameservers specified at your domain registrar match the NS records of the hosted zone used for validation. If a new hosted zone was created, its nameservers might differ from the domain's current ones, requiring an update at the registrar.
```
AccessDeniedException: User: arn:aws:iam::xxxxxxxxxxxx:user/your-user is not authorized to perform: acm:RequestCertificate on resource: arn:aws:acm:region:xxxxxxxxxxxx:certificate/*
```
cause The IAM principal (user or role) attempting to deploy the CDK stack lacks the necessary permissions to request or manage ACM certificates.

fix Grant the IAM principal `acm:RequestCertificate`, `acm:DescribeCertificate`, `acm:ListCertificates`, and related permissions (e.g., `route53:ChangeResourceRecordSets` for DNS validation) for the relevant resources.

Warnings

breaking AWS CDK v1 has reached End-of-Support on June 1, 2023. This package (`aws-cdk-aws-certificatemanager`) is no longer being updated, and using it in new projects or continuing with it in existing ones is highly discouraged.
Fix: Migrate your CDK application to AWS CDK v2. This involves installing `aws-cdk-lib` instead of individual service packages, updating import statements (e.g., `from aws_cdk import aws_certificatemanager as acm`), and potentially adjusting construct patterns.
deprecated The `DnsValidatedCertificate` construct is deprecated in AWS CDK v2 (and functionally superseded in later v1 versions) in favor of the more general `Certificate` construct combined with `CertificateValidation.from_dns()`.
Fix: Replace `new acm.DnsValidatedCertificate(...)` with `new acm.Certificate(..., validation=acm.CertificateValidation.from_dns(hosted_zone))`.
gotcha ACM certificates for use with Amazon CloudFront distributions must be requested in the `us-east-1` (N. Virginia) region, regardless of the region your CloudFront distribution or other resources are deployed in.
Fix: Ensure the `Certificate` construct is explicitly created in the `us-east-1` region, typically by specifying `env=cdk.Environment(region='us-east-1')` for the stack or the specific construct.
gotcha CloudFormation deployments involving new ACM certificates with DNS validation will wait for the domain validation process to complete. This can cause deployments to appear 'stuck' or take a long time if DNS records are not propagated quickly or correctly.
Fix: Ensure your DNS records (CNAMEs) are correctly configured in your domain's authoritative DNS (e.g., Route 53) and allow sufficient time for propagation. For manual validation, consider provisioning certificates in a separate stack or manually importing them to avoid long deployment waits for your main application stack.

Install

pip install aws-cdk.aws-certificatemanager Install for CDK v1

Imports

Certificate
wrong:
```
from aws_cdk.aws_certificatemanager import Certificate
```
correct:
```
from aws_cdk import aws_certificatemanager as acm
```
CDK v1 prefers aliasing the module; direct import of classes is more common in CDK v2's `aws-cdk-lib` package.
CertificateValidation
```
from aws_cdk import aws_certificatemanager as acm
```
Accessed as `acm.CertificateValidation` after module import.
DnsValidatedCertificate
wrong:
```
from aws_cdk.aws_certificatemanager import DnsValidatedCertificate
```
correct:
```
from aws_cdk import aws_certificatemanager as acm
```
This construct is deprecated in favor of `acm.Certificate` with `acm.CertificateValidation.from_dns()`.

Quickstart

This quickstart demonstrates creating a wildcard ACM certificate using DNS validation with an existing Route 53 hosted zone. Ensure you have `aws-cdk.aws-route53` installed and `CDK_DEFAULT_ACCOUNT`, `CDK_DEFAULT_REGION`, `DOMAIN_NAME`, and `HOSTED_ZONE_ID` environment variables set. Certificates for CloudFront distributions must be provisioned in the `us-east-1` region.

import os
from aws_cdk import (
    core as cdk,
    aws_certificatemanager as acm,
    aws_route53 as route53
)

class MyCertStack(cdk.Stack):
    def __init__(self, scope: cdk.Construct, id: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)

        # Replace with your actual domain and hosted zone ID
        domain_name = os.environ.get('DOMAIN_NAME', 'example.com')
        hosted_zone_id = os.environ.get('HOSTED_ZONE_ID', 'Z1XXXXXXXXXXXXX')

        # Lookup an existing hosted zone
        # In a real application, you might create the hosted zone in the same stack or another.
        hosted_zone = route53.HostedZone.from_hosted_zone_attributes(
            self, "MyHostedZone",
            hosted_zone_id=hosted_zone_id,
            zone_name=domain_name
        )

        certificate = acm.Certificate(
            self, "MyCertificate",
            domain_name=f"*.{domain_name}",
            validation=acm.CertificateValidation.from_dns(hosted_zone),
            # For CloudFront, certificates must be in us-east-1. Specify region here if needed.
            # env=cdk.Environment(region="us-east-1")
        )

        cdk.CfnOutput(self, "CertificateArn", value=certificate.certificate_arn)

app = cdk.App()
MyCertStack(app, "CertificateStack",
            env=cdk.Environment(account=os.environ.get('CDK_DEFAULT_ACCOUNT'),
                                region=os.environ.get('CDK_DEFAULT_REGION'))
)
app.synth()

view raw JSON →