diff --git a/packages/aws-cdk-lib/aws-ssm/README.md b/packages/aws-cdk-lib/aws-ssm/README.md index e70e424f0573b..0f678c449c756 100644 --- a/packages/aws-cdk-lib/aws-ssm/README.md +++ b/packages/aws-cdk-lib/aws-ssm/README.md @@ -1,6 +1,5 @@ # AWS Systems Manager Construct Library - This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project. ## Using existing SSM Parameters in your CDK app @@ -143,3 +142,32 @@ When specifying an `allowedPattern`, the values provided as string literals are validated against the pattern and an exception is raised if a value provided does not comply. +## Using Tokens in parameter name + +When using [CDK Tokens](https://docs.aws.amazon.com/cdk/v2/guide/tokens.html) in parameter name, +you need to explicitly set the `simpleName` property. Setting `simpleName` to an incorrect boolean +value may result in unexpected behaviours, such as having duplicate '/' in the parameter ARN +or missing a '/' in the parameter ARN. + +`simpleName` is used to indicates whether the parameter name is a simple name. A parameter name +without any '/' is considered a simple name, thus you should set `simpleName` to `true`. +If the parameter name includes '/', set `simpleName` to `false`. + +```ts +import * as lambda from 'aws-cdk-lib/aws-lambda'; + +const simpleParameter = new ssm.StringParameter(this, 'StringParameter', { + // the parameter name doesn't contain any '/' + parameterName: 'parameter', + stringValue: 'SOME_VALUE', + simpleName: true, // set `simpleName` to true +}); + +declare const func: lambda.IFunction; +const nonSimpleParameter = new ssm.StringParameter(this, 'StringParameter', { + // the parameter name contains '/' + parameterName: `/${func.functionName}/my/app/param`, + stringValue: 'SOME_VALUE', + simpleName: false, // set `simpleName` to false +}); +``` diff --git a/packages/aws-cdk-lib/aws-ssm/lib/parameter.ts b/packages/aws-cdk-lib/aws-ssm/lib/parameter.ts index 1972b605665fc..f4087515bc724 100644 --- a/packages/aws-cdk-lib/aws-ssm/lib/parameter.ts +++ b/packages/aws-cdk-lib/aws-ssm/lib/parameter.ts @@ -99,8 +99,10 @@ export interface ParameterOptions { readonly parameterName?: string; /** - * Indicates if the parameter name is a simple name (i.e. does not include "/" - * separators). + * Indicates whether the parameter name is a simple name. A parameter name + * without any "/" is considered a simple name. If the parameter name includes + * "/", setting simpleName to true might cause unintended issues such + * as duplicate "/" in the resulting ARN. * * This is required only if `parameterName` is a token, which means we * are unable to detect if the name is simple or "path-like" for the purpose @@ -337,8 +339,10 @@ export interface CommonStringParameterAttributes { readonly parameterName: string; /** - * Indicates if the parameter name is a simple name (i.e. does not include "/" - * separators). + * Indicates whether the parameter name is a simple name. A parameter name + * without any "/" is considered a simple name. If the parameter name includes + * "/", setting simpleName to true might cause unintended issues such + * as duplicate "/" in the resulting ARN. * * This is required only if `parameterName` is a token, which means we * are unable to detect if the name is simple or "path-like" for the purpose