Install & Compatibility
Where this runs
tested against v1.204.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 0.000s · 480MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 10.4s · import 0.000s · 551MB
555MB installed
● package 555MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
StringParameter
✓ import aws_cdk.aws_ssm as ssm # For AWS CDK v1
# OR (Recommended for AWS CDK v2)
from aws_cdk import aws_ssm
✗ import aws_ssm
CDK v1 used `aws_cdk.aws_ssm` as a separate module. CDK v2 consolidates services under `aws_cdk` in the `aws-cdk-lib` package. [3, 15, 29]
This quickstart demonstrates how to create a new String Parameter and how to look up an existing String Parameter using AWS CDK v2. It defines a simple stack that provisions an SSM parameter and then references another (presumably pre-existing) parameter. For v1, the imports would be `import aws_cdk.aws_ssm as ssm` instead of `from aws_cdk import aws_ssm` and `ssm.StringParameter` etc. [3, 13, 16, 25]
import os
import aws_cdk as cdk
from constructs import Construct
from aws_cdk import aws_ssm
class MySsmStack(cdk.Stack):
def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
super().__init__(scope, construct_id, **kwargs)
# Create a new String Parameter in SSM Parameter Store
aws_ssm.StringParameter(self, "MyParameter",
parameter_name="/my/app/config/value",
string_value="MyParameterValue",
description="A parameter for my application configuration",
tier=aws_ssm.ParameterTier.STANDARD
)
# Look up an existing String Parameter at synthesis time
# Note: This will perform an AWS API call during 'cdk synth'
# and cache the value in cdk.context.json. [3, 22]
existing_param_value = aws_ssm.StringParameter.value_from_lookup(
self, "ExistingParameterLookup", "/path/to/existing/param"
)
# Output the value (for demonstration purposes)
cdk.CfnOutput(self, "ExistingParameterOutput", value=existing_param_value)
app = cdk.App()
MySsmStack(app, "MySsmStack",
env=cdk.Environment(
account=os.environ.get('CDK_DEFAULT_ACCOUNT', ''),
region=os.environ.get('CDK_DEFAULT_REGION', '')
)
)
app.synth()
cdk --version
Debug
Known issues
breakingThe `aws-cdk-aws-ssm` package is part of AWS CDK v1, which reached End-of-Support (EoS) on June 1, 2023. It is no longer being updated. Users are strongly advised to migrate to AWS CDK v2.fixMigrate your CDK application to AWS CDK v2. This involves changing package dependencies from individual service packages (e.g., `aws-cdk.aws-ssm`) to the consolidated `aws-cdk-lib` package and updating import statements. [15, 25, 29]
affects: All versions of `aws-cdk-aws-ssm` (CDK v1).
breakingIn AWS CDK v2, the construct libraries for all stable AWS services are consolidated into a single package, `aws-cdk-lib`. This changes the import paths for SSM constructs.fixChange your import statements from `import aws_cdk.aws_ssm as ssm` (or similar v1 patterns) to `from aws_cdk import aws_ssm` when using `aws-cdk-lib`. [29]
affects: Transitioning from AWS CDK v1 to v2.
gotchaAWS CDK constructs (in both v1 and v2) cannot directly create or manage `SecureString` parameters in SSM Parameter Store. Attempts to provision a `SecureString` will fail or result in a public `StringParameter`.fixFor sensitive data, use AWS Secrets Manager instead, which has dedicated CDK constructs (`aws_cdk.aws_secretsmanager`). Alternatively, manually create `SecureString` parameters in the SSM console or via AWS CLI/SDK and then reference them in CDK using `from_secure_string_parameter_attributes`. [13, 15, 22, 25]
affects: All AWS CDK versions (v1 and v2).
gotchaSSM Parameter Store values are region-specific. Attempting to look up a parameter in a different region from where your CDK stack is deployed will result in an error, as the parameter won't be found.fixFor cross-region parameter lookups, define separate 'inline' CDK stacks, each configured for the specific region of the parameter, to perform the lookup. Pass the retrieved value into your main stack. [19, 20, 22]
affects: All AWS CDK versions (v1 and v2).
gotchaUpdating the `string_value` of an `aws_ssm.StringParameter` construct via a `cdk deploy` can lead to deployment failures if CloudFormation attempts to replace the parameter rather than update its value.fixConsider lifecycle rules for SSM parameters. For values that change frequently, it might be better to manage them outside of CDK or to implement custom update logic. If a direct update fails, a `cdk destroy` followed by `cdk deploy` might be necessary, but this will recreate the parameter and is not ideal for values that need to persist across deployments. Also consider using `cdk.CustomResource` for more granular control over parameter updates. [21]
affects: All AWS CDK versions (v1 and v2).
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'aws_cdk.aws_ssm'
You are likely trying to import `aws_cdk.aws_ssm` (a v1 pattern) while only having `aws-cdk-lib` (v2) installed, or vice-versa, or the specific package is not installed.
fixEnsure you have the correct package installed for your CDK version (`pip install aws-cdk.aws-ssm` for v1 or `pip install aws-cdk-lib` for v2) and your import statements match your installed version. For CDK v2, the import should be `from aws_cdk import aws_ssm` (or `from aws_cdk.aws_ssm import ...`).
The stack named X failed to deploy: UPDATE_ROLLBACK_COMPLETE (or similar CloudFormation deployment error related to SSM parameters)
This often occurs when trying to update or delete an SSM parameter that is referenced by another stack (a 'hard dependency') or when attempting to update a parameter's value directly through a CDK deployment without CloudFormation recognizing it as an update.
fixFor cross-stack references, use softer dependencies like `ssm.StringParameter.value_from_lookup` instead of CloudFormation Exports, or ensure dependent stacks are updated/deleted in the correct order. For parameter value updates, review the warning regarding direct value updates. [21, 26, 28]
CloudFormation Error: Parameter 'YourParameterName' cannot be found. This happens if the parameter doesn't exist, you don't have permissions to access it, or it's in a different region/account.
The SSM parameter you are trying to reference does not exist, or your CDK execution role lacks permissions to read it, or the parameter is in a different AWS region/account than your stack.
fixVerify the parameter name and its existence in the target region and account. Ensure the IAM role used by your CDK deployment has `ssm:GetParameter` permissions. For cross-region parameters, use dedicated lookup stacks. [12, 19, 22]
TypeError: Cannot instantiate 'aws_cdk.aws_ssm.SecureStringParameter' directly.
You are attempting to instantiate a `SecureStringParameter` class, which is not directly supported by AWS CDK for creation.
fixUse AWS Secrets Manager constructs (`aws_cdk.aws_secretsmanager`) for creating and managing secrets. If you need to reference an existing `SecureString` from SSM, use `aws_ssm.StringParameter.from_secure_string_parameter_attributes` (but note this is for *referencing*, not *creating*). [13, 22, 25]
Upgrade
Version history
1.204.0latest on PyPI · released Jun 19, 2023
Audit
Dependencies
aws-cdk.corerequiredCore CDK functionality for v1 packages.
aws-cdk-librequiredThe consolidated construct library for AWS CDK v2, which is the recommended version.
constructsrequiredThe base constructs library, required by both CDK v1 and v2.