AWS CDK ACMPCA v1 Constructs

Common errors

• ModuleNotFoundError: No module named 'aws_cdk_lib.aws_acmpca'

  cause Attempting to import a CDK v2 module (`aws_cdk_lib`) while using a CDK v1 package (`aws-cdk-aws-acmpca`).
  fix If staying with CDK v1, change import to `from aws_cdk import aws_acmpca`. If migrating to v2, uninstall `aws-cdk-aws-acmpca`, install `aws-cdk-lib`, and use the v2 import `from aws_cdk import aws_acmpca as acmpca`.

• The specified KMS key 'arn:aws:kms:...' does not exist or you do not have permission to access it.

  cause The IAM role deploying the CA lacks permissions to create or access the specified KMS key, or the key ARN is incorrect/missing.
  fix Verify the KMS key ARN is correct and ensure the IAM role used by CDK has `kms:CreateKey`, `kms:DescribeKey`, and `kms:ScheduleKeyDeletion` permissions for the key or relevant resource policy.

• Acmpca.CertificateAuthority requires properties 'key_algorithm', 'signing_algorithm', and 'subject'.

  cause One or more required properties for the `CertificateAuthority` construct were omitted or incorrectly specified.
  fix Ensure all mandatory properties like `key_algorithm`, `signing_algorithm`, `subject`, and `type` are provided with valid values, as shown in the quickstart example.

Warnings

• breaking This package (`aws-cdk-aws-acmpca`) is specific to AWS CDK v1. AWS CDK v2 has consolidated all constructs into a single package, `aws-cdk-lib`. If migrating to CDK v2, you will need to uninstall this package and `aws-cdk.core`, then install `aws-cdk-lib`, and update your imports (e.g., `from aws_cdk import aws_acmpca as acmpca`).
  Fix: For v2, install `aws-cdk-lib` and update imports. For v1, continue using separate `aws-cdk.*` packages and `aws_cdk.core`.
• gotcha An ACMPCA Certificate Authority created via CDK is not automatically 'active'. After deployment, you typically need to manually issue a self-signed certificate for a Root CA or a certificate from its parent for a Subordinate CA, and then import it into the ACMPCA console to transition the CA to the 'ACTIVE' state.
  Fix: Follow AWS ACMPCA documentation for CA activation post-deployment, which often involves generating a CSR, signing it, and importing the certificate.
• gotcha ACMPCA CAs have deletion protection enabled by default. You cannot delete a CA that has issued active certificates or if deletion protection is explicitly set. Trying to `cdk destroy` a CA without first removing issued certificates or disabling protection will fail.
  Fix: Before deleting, ensure all certificates issued by the CA are revoked and deleted. You may also need to manually disable deletion protection in the AWS console or update the CDK construct to set `permanent_deletion_time_in_days` (for L1) or similar property to allow deletion after a grace period.
• gotcha ACMPCA requires proper IAM permissions for the deploying user/role, especially for interacting with KMS keys (for CA key material) and S3 buckets (for CRLs and audit reports). Common errors involve permissions to `kms:CreateKey`, `s3:PutObject`, `acm-pca:*` actions.
  Fix: Ensure the IAM role performing the CDK deployment has comprehensive permissions for ACMPCA, KMS, and S3 resources used by the CA, or narrow down to specific required actions.
• gotcha ACMPCA is not available in all AWS regions. Attempting to deploy an ACMPCA resource in an unsupported region will result in deployment failures.
  Fix: Consult the AWS documentation for ACMPCA region availability and deploy your stack in a supported region (e.g., `us-east-1`, `us-west-2`, `eu-west-1`).

Install

• pip install aws-cdk.core aws-cdk.aws-acmpca Install for CDK v1 projects
• npm install -g aws-cdk Install AWS CDK CLI (recommended)

Imports

• aws_acmpca
  wrong:

  from aws_cdk_lib import aws_acmpca

  correct:

  from aws_cdk import aws_acmpca

  This package is for AWS CDK v1. For v2, use 'from aws_cdk import aws_acmpca as acmpca' after installing 'aws-cdk-lib'.
• CertificateAuthority

  from aws_cdk.aws_acmpca import CertificateAuthority

• CfnCertificateAuthority

  from aws_cdk.aws_acmpca import CfnCertificateAuthority

  The L1 construct, useful for direct CloudFormation property access.

Quickstart

This quickstart demonstrates how to define a basic Root Certificate Authority (CA) using the `aws-cdk-aws-acmpca` v1 constructs. It sets up the necessary properties for a CA. To deploy this, ensure you have the AWS CDK CLI installed globally (`npm install -g aws-cdk`) and your AWS credentials configured, then run `cdk deploy`.

import os
from aws_cdk import core as cdk
from aws_cdk import aws_acmpca as acmpca

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

        # Example: Create a Root Certificate Authority
        # Note: A CA created this way needs to be activated manually
        # by issuing a self-signed certificate and importing it.
        # This construct only provisions the ACMPCA resource.
        acmpca.CertificateAuthority(self, "MyRootCA",
            certificate_authority_name="MyRootCA",
            type=acmpca.CertificateAuthorityType.ROOT,
            key_algorithm=acmpca.KeyAlgorithm.RSA_2048,
            signing_algorithm=acmpca.SigningAlgorithm.SHA256_WITH_RSA,
            subject=acmpca.CfnCertificateAuthority.SubjectProperty(
                country="US",
                state="WA",
                locality="Seattle",
                organization="MyOrg",
                organizational_unit="IT",
                common_name="MyRootCA",
            ),
            # For production, consider enabling S3 bucket for CRLs/audit reports:
            # revocation_configuration=acmpca.CfnCertificateAuthority.RevocationConfigurationProperty(
            #    crl_configuration=acmpca.CfnCertificateAuthority.CrlConfigurationProperty(
            #        enabled=True,
            #        custom_cname="crl.myorg.com",
            #        expiration_in_days=7,
            #        s3_bucket_name="my-crl-bucket"
            #    )
            # )
        )

app = cdk.App()
MyAcmpcaStack(app, "MyAcmpcaStack",
    env=cdk.Environment(
        account=os.environ.get("CDK_DEFAULT_ACCOUNT", "123456789012"), # Replace with your AWS account ID
        region=os.environ.get("CDK_DEFAULT_REGION", "us-east-1") # ACMPCA not available in all regions
    )
)
app.synth()