AWS CDK CX-API

2.250.0 · active · verified Thu Apr 16

The `aws-cdk-cx-api` library is a core component of the AWS Cloud Development Kit (CDK), defining the Cloud Executable protocol. It provides interfaces and classes for working with Cloud Assemblies, which are the synthesized artifacts produced by CDK applications. These assemblies contain the CloudFormation templates, assets, and metadata required for deployment. This library is part of CDK v2 and is currently at version 2.250.0, with frequent updates tied to the main CDK release cycle.

Common errors

```
ModuleNotFoundError: No module named 'aws_cdk.cx_api'
```
cause The `aws-cdk-cx-api` package is not installed, or you are trying to use a CDK v1 import style for v2.

fix Run `pip install aws-cdk-cx-api`. If migrating from v1, ensure all imports use the `from aws_cdk.cx_api import ...` pattern.
```
jsii.errors.JavaScriptError: CloudAssembly directory does not exist: '<path_to_cdk.out>'
```
cause The specified directory for `CloudAssembly` (typically `cdk.out`) does not exist or the path is incorrect.

fix Verify that `cdk synth` has been run successfully in your CDK project, creating the `cdk.out` directory. Check the path passed to `CloudAssembly(directory=...)`.
```
jsii.errors.JavaScriptError: Manifest file 'manifest.json' not found in '<path_to_cdk.out>'
```
cause The `cdk.out` directory exists, but it's either empty, corrupted, or does not contain a valid `manifest.json` file, which is crucial for defining the Cloud Assembly.

fix Re-run `cdk synth` to ensure a complete and valid `cdk.out` directory is generated. Check the CDK CLI output for any errors during synthesis.

Warnings

breaking Migration from AWS CDK v1 to v2 consolidated all modules under the `aws_cdk` namespace. This means import paths for `aws-cdk-cx-api` classes changed significantly.
Fix: Update all imports from `aws_cdk.cx_api.ClassName` (or similar v1 patterns like `@aws-cdk/cloud-assembly-schema` in JavaScript) to `from aws_cdk.cx_api import ClassName` for v2.
gotcha The `aws-cdk-cx-api` library is for *inspecting* Cloud Assemblies, not for *defining* CDK applications. It operates on the output of `cdk synth` (the `cdk.out` directory).
Fix: Use `aws-cdk-lib` for defining CDK constructs, stacks, and apps. Use `aws-cdk-cx-api` when you need to programmatically analyze or manipulate the synthesized `cdk.out` output.
gotcha The schema of the Cloud Assembly (`manifest.json`, `tree.json`, etc.) can evolve between minor versions of CDK. Loading an assembly synthesized with a much older or newer CDK CLI version might lead to parsing errors.
Fix: Ensure your `aws-cdk-cx-api` library version and the CDK CLI version used to synthesize the `cdk.out` directory are reasonably compatible. Upgrade both if encountering unexpected parsing failures.

Install

pip install aws-cdk-cx-api Install `aws-cdk-cx-api`

Imports

CloudAssembly
wrong:
```
from @aws-cdk/cloud-assembly-schema import CloudAssembly
```
correct:
```
from aws_cdk.cx_api import CloudAssembly
```
In CDK v2, all core constructs are under `aws_cdk` namespace. `CloudAssembly` is the primary class for loading synthesized assemblies. The `wrong` example shows a common mistake from CDK v1 (JavaScript) or attempting to import schema directly.
CloudAssemblyBuilder
```
from aws_cdk.cx_api import CloudAssemblyBuilder
```
Used to programmatically create or build a Cloud Assembly structure.
ArtifactType
```
from aws_cdk.cx_api import ArtifactType
```
Enum representing different types of artifacts within a Cloud Assembly (e.g., CloudFormation stack, asset).

Quickstart

This quickstart demonstrates how to load and inspect a synthesized AWS CDK Cloud Assembly. It assumes a `cdk.out` directory has been created by running `cdk synth` in a CDK project. It then prints details about the assembly, including its stacks and artifacts. An alternative path is provided to create an empty assembly programmatically if no `cdk.out` is available.

import os
from aws_cdk.cx_api import CloudAssembly, CloudAssemblyBuilder

# Assuming 'cdk.out' exists in the current directory, typically created by 'cdk synth'.
assembly_path = "./cdk.out"

if os.path.isdir(assembly_path):
    print(f"Loading Cloud Assembly from: {assembly_path}")
    try:
        assembly = CloudAssembly(directory=assembly_path)
        print(f"Assembly ID: {assembly.id}")
        print(f"Version: {assembly.version}")
        print("Found stacks:")
        for stack in assembly.stacks:
            print(f"- {stack.stack_name} (Env: {stack.environment.name})")
        print("Artifacts:")
        for artifact in assembly.artifacts:
            print(f"- {artifact.id} (Type: {type(artifact).__name__})")
    except Exception as e:
        print(f"Error loading Cloud Assembly: {e}")
        print("Ensure 'cdk synth' was run successfully and 'cdk.out' is valid.")
else:
    print(f"Directory '{assembly_path}' not found. Please run 'cdk synth' in a CDK project first.")
    print("Alternatively, you can create an empty assembly programmatically:")
    builder = CloudAssemblyBuilder(outdir="temp_cdk_out")
    builder.build()
    print("Created empty assembly in 'temp_cdk_out'.")
    # os.system("rm -rf temp_cdk_out") # Uncomment to clean up automatically

view raw JSON →