AWS CDK AWS Systems Manager (SSM) Construct Library (v1)

Common errors

• ModuleNotFoundError: No module named 'aws_cdk.aws_ssm'

  cause 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.
  fix Ensure 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)

  cause 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.
  fix For 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.

  cause 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.
  fix Verify 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.

  cause You are attempting to instantiate a `SecureStringParameter` class, which is not directly supported by AWS CDK for creation.
  fix Use 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]

Warnings

• breaking The `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.
  Fix: Migrate 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]
• breaking In 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.
  Fix: Change 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]
• gotcha AWS 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`.
  Fix: For 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]
• gotcha SSM 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.
  Fix: For 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]
• gotcha Updating 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.
  Fix: Consider 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]

Install

• pip install aws-cdk.aws-ssm For AWS CDK v1 (Deprecated)
• pip install aws-cdk-lib For AWS CDK v2 (Recommended)

Imports

• StringParameter
  wrong:

  import aws_ssm

  correct:

  import aws_cdk.aws_ssm as ssm # For AWS CDK v1
  # OR (Recommended for AWS CDK v2)
  from aws_cdk 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]

Quickstart

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()