AWS CDK AWS KMS Constructs (v1)

1.204.0 · maintenance · verified Thu Apr 16

The `aws-cdk-aws-kms` package provides AWS Cloud Development Kit (CDK) constructs for AWS Key Management Service (KMS). This package is part of AWS CDK v1, which is now in maintenance mode. New projects are strongly encouraged to use AWS CDK v2, where KMS constructs are bundled within the `aws-cdk-lib` package. The last published version for v1 is 1.204.0, with frequent updates during its active lifecycle.

Common errors

```
ModuleNotFoundError: No module named 'aws_cdk.aws_kms'
```
cause The `aws-cdk-aws-kms` package (v1) is not installed, or you are trying to use a v1 import path with a v2 installation (`aws-cdk-lib`).

fix If using v1, install it with `pip install aws-cdk.aws-kms aws-cdk.core`. If using v2, change your import to `from aws_cdk_lib import aws_kms as kms`.
```
AttributeError: module 'aws_cdk' has no attribute 'aws_kms'
```
cause You have `aws-cdk-lib` (v2) installed and are trying to use the v1 import `from aws_cdk import aws_kms`.

fix For AWS CDK v2, the correct import is `from aws_cdk_lib import aws_kms as kms`. Remove `from aws_cdk import aws_kms`.
```
TypeError: Expected object of type aws_cdk.core.StackProps, got aws_cdk_lib.StackProps instead
```
cause Your project is mixing AWS CDK v1 (`aws-cdk.core`) and v2 (`aws-cdk-lib`) dependencies.

fix Standardize on either AWS CDK v1 or v2. If migrating to v2, ensure `aws-cdk.core` and other individual v1 construct packages are uninstalled, and only `aws-cdk-lib` is installed.
```
jsii.errors.JavaScriptError: The 'cdk.Stack' construct must be created within the scope of a 'cdk.App' construct
```
cause A CDK Stack was instantiated without being passed a `cdk.App` instance as its scope.

fix Ensure your `Stack` definition is initialized within a `cdk.App` context, for example: `app = cdk.App(); MyKmsStack(app, 'MyKmsStack'); app.synth()`.

Warnings

breaking AWS CDK v1 is in maintenance mode and new projects should use AWS CDK v2. The package structure and import paths are significantly different between v1 and v2.
Fix: For new projects, `pip install aws-cdk-lib` and update your code to use `from aws_cdk_lib import aws_kms as kms` and other v2 constructs. Consult the official CDK v2 upgrade guide.
gotcha Mixing AWS CDK v1 and v2 dependencies in the same project can lead to `TypeError` or `AttributeError` at runtime, especially when dealing with core constructs like `StackProps`.
Fix: Ensure your project uses either all v1 packages (`aws-cdk.core`, `aws-cdk.aws-kms`) or all v2 packages (`aws-cdk-lib`). Do not install both `aws-cdk.core` and `aws-cdk-lib` simultaneously.
gotcha KMS Key destruction behavior: By default, KMS keys cannot be easily destroyed. Using `RemovalPolicy.DESTROY` for `kms.Key` can lead to data loss if not handled carefully, and requires manual waiting periods for key deletion.
Fix: Only use `removal_policy=cdk.RemovalPolicy.DESTROY` for non-production environments or test keys. For production, consider `removal_policy=cdk.RemovalPolicy.RETAIN` or implement custom deletion logic.
deprecated Some KMS properties or constructs available in v1 might have been deprecated or renamed in v2, or have different default behaviors (e.g., key rotation).
Fix: Refer to the AWS CDK v2 API documentation for `aws_cdk.aws_kms` to identify any changes in construct properties or methods.

Install

pip install aws-cdk.aws-kms==1.204.0 aws-cdk.core==1.204.0 For AWS CDK v1 (this specific package)
pip install aws-cdk-lib@latest For AWS CDK v2 (recommended for new projects)

Imports

Key
wrong:
```
from aws_cdk_lib import aws_kms as kms
```
correct:
```
from aws_cdk import aws_kms
```
This import path is specific to AWS CDK v1. For AWS CDK v2, the correct import is `from aws_cdk_lib import aws_kms as kms`.
Alias
wrong:
```
import aws_cdk.aws_kms as kms
```
correct:
```
from aws_cdk import aws_kms
```
While `import aws_cdk.aws_kms as kms` works, direct import of specific symbols like `Key` or `Alias` is common in v1.

Quickstart

This quickstart demonstrates how to create a new KMS Key and an Alias for it using AWS CDK v1 constructs. It outputs the ARN of the created key and its alias.

from aws_cdk import core as cdk
from aws_cdk import aws_kms as kms

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

        # Create a new KMS Key
        key = kms.Key(self, "MyApplicationKey",
            description="My sample KMS key for an application",
            enable_key_rotation=True,
            removal_policy=cdk.RemovalPolicy.DESTROY # Caution: Destroys key on stack deletion
        )

        # Create an alias for the key
        kms.Alias(self, "MyApplicationKeyAlias",
            alias_name="alias/my-app-key",
            target_key=key
        )

        # Output the Key ARN
        cdk.CfnOutput(self, "KeyArn",
            value=key.key_arn,
            description="ARN of the created KMS Key"
        )

        # Output the Key Alias ARN
        cdk.CfnOutput(self, "KeyAliasArn",
            value=f"arn:{{self.partition}}:kms:{{self.region}}:{{self.account}}:alias/my-app-key",
            description="ARN of the KMS Key Alias"
        )

app = cdk.App()
MyKmsStack(app, "MyKmsV1Stack")
app.synth()

view raw JSON →