AWS CDK v1 CloudFormation Constructs

Common errors

• ModuleNotFoundError: No module named 'aws_cdk_lib'

  cause You are attempting to use AWS CDK v2 (`aws_cdk_lib`) imports, but only AWS CDK v1 packages like `aws-cdk.aws-cloudformation` are installed.
  fix Either install AWS CDK v2 via `pip install aws-cdk-lib` (and adapt your code) or stick to v1 imports (e.g., `from aws_cdk import core`, `from aws_cdk.aws_cloudformation import ...`).

• ModuleNotFoundError: No module named 'aws_cdk.aws_cloudformation'

  cause The `aws-cdk.aws-cloudformation` package is not installed in your Python environment or you are trying to import it in a v2 context without the correct v2 import path.
  fix For AWS CDK v1, install the package with `pip install aws-cdk.aws-cloudformation`. For AWS CDK v2, the `aws_cloudformation` module is part of `aws_cdk_lib`, so use `from aws_cdk_lib import aws_cloudformation`.

• TypeError: Expected type str, got None

  cause A required property for a CDK construct, such as `template_url` for `CfnStack`, was not provided or evaluated to `None`.
  fix Ensure all required properties for the construct are explicitly provided with valid string values. Double-check environment variables or configuration values if they are used to populate properties.

• jsii.errors.JavaScriptError: Error: Stack 'MyCfnStackApp' cannot be deployed, as its 'templateUrl' does not point to a valid template in S3.

  cause The `template_url` provided to `CfnStack` is either incorrect, inaccessible, or does not point to a well-formed CloudFormation template in an S3 bucket.
  fix Verify the S3 URL is correct and publicly accessible, or that your CDK deployment role has `s3:GetObject` permissions for that bucket and object. Ensure the S3 object is a valid CloudFormation template.

Warnings

• breaking AWS CDK v1 (`aws-cdk.aws-cloudformation`) is in maintenance mode. Active development, new features, and most bug fixes are concentrated on AWS CDK v2 (`aws-cdk-lib`). Migrating to v2 is highly recommended as v1 will eventually reach end-of-life.
  Fix: Plan a migration to AWS CDK v2 by installing `aws-cdk-lib` and updating your code to use the consolidated module imports (e.g., `from aws_cdk_lib import aws_cloudformation`). Refer to the official CDK v1 to v2 migration guide.
• gotcha When using `CfnCustomResource`, you are responsible for providing the full implementation details, including the Lambda function code, execution role, and service token. This is a lower-level construct.
  Fix: For a higher-level abstraction and simpler custom resource creation, consider using the `CustomResource` construct from `aws_cdk.custom_resources` (part of `aws-cdk.custom-resources` for v1) which handles much of the boilerplate for you.
• gotcha The `CfnStack` construct deploys a CloudFormation template. The AWS account and IAM role used for CDK deployment must have permissions to read the `template_url` (if from S3) and to deploy all resources defined within that CloudFormation template.
  Fix: Ensure the CDK deployment role (often provisioned by `cdk bootstrap`) has `s3:GetObject` permissions for the template S3 bucket and all necessary permissions for the resources declared in the referenced CloudFormation template.
• gotcha Mixing raw CloudFormation definitions via `CfnStack` with high-level CDK constructs in the same stack can sometimes lead to unexpected behavior or resource ownership conflicts if not carefully managed.
  Fix: Prefer using CDK's native constructs where possible. Use `CfnStack` for deploying existing templates or when a specific CloudFormation resource lacks a direct CDK construct. Be mindful of resource logical IDs and potential overwrites if the same resource is defined both natively and via `CfnStack`.

Install

• pip install aws-cdk.aws-cloudformation Install v1

Imports

• CfnStack
  wrong:

  from aws_cdk_lib.aws_cloudformation import CfnStack

  correct:

  from aws_cdk.aws_cloudformation import CfnStack

  This package is for AWS CDK v1; v2 uses `aws_cdk_lib`.
• CfnCustomResource

  from aws_cdk.aws_cloudformation import CfnCustomResource

Quickstart

This quickstart demonstrates how to use `aws_cdk.aws_cloudformation.CfnStack` to deploy an existing CloudFormation template from an S3 URL. It sets up a basic AWS CDK v1 application, defines a stack, and then includes a `CfnStack` construct. For a real deployment, ensure `CFN_TEMPLATE_URL`, `CDK_DEFAULT_ACCOUNT`, and `CDK_DEFAULT_REGION` environment variables are set.

import os
from aws_cdk import App, Stack, Environment
from aws_cdk.aws_cloudformation import CfnStack
from constructs import Construct

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

        # This construct deploys an existing CloudFormation template from an S3 URL.
        # Replace with a valid S3 URL to your CloudFormation template.
        # Ensure the deployment role has permissions to read from this S3 location.
        template_url = os.environ.get('CFN_TEMPLATE_URL', 'https://s3.amazonaws.com/your-bucket/your-template.yaml')
        if not template_url.startswith('https://'):
            print("WARNING: CFN_TEMPLATE_URL is not set or invalid. Using a placeholder.")

        cfn_stack = CfnStack(self, "MyExistingCloudFormationStack",
            template_url=template_url,
            parameters={
                "EnvironmentName": "Dev",
                "Project": "MyCDKApp"
            },
            tags={
                "ManagedBy": "CDK"
            }
        )

app = App()
MyCfnStackExample(app, "MyCfnStackApp",
    env=Environment(account=os.environ.get("CDK_DEFAULT_ACCOUNT"),
                    region=os.environ.get("CDK_DEFAULT_REGION"))
)
app.synth()