Skip navigation links

Package software.amazon.awscdk.services.ssm

AWS Systems Manager Construct Library

See: Description

Package software.amazon.awscdk.services.ssm Description

AWS Systems Manager Construct Library

This module is part of the AWS Cloud Development Kit project.

Using existing SSM Parameters in your CDK app

You can reference existing SSM Parameter Store values that you want to use in your CDK app by using ssm.StringParameter.fromStringParameterAttributes: 

 // Retrieve the latest value of the non-secret parameter
 // with name "/My/String/Parameter".
 String stringValue = StringParameter.fromStringParameterAttributes(this, "MyValue", StringParameterAttributes.builder()
         .parameterName("/My/Public/Parameter")
         .build()).getStringValue();
 String stringValueVersionFromToken = StringParameter.fromStringParameterAttributes(this, "MyValueVersionFromToken", StringParameterAttributes.builder()
         .parameterName("/My/Public/Parameter")
         // parameter version from token
         .version(parameterVersion)
         .build()).getStringValue();
 
 // Retrieve a specific version of the secret (SecureString) parameter.
 // 'version' is always required.
 IStringParameter secretValue = StringParameter.fromSecureStringParameterAttributes(this, "MySecureValue", SecureStringParameterAttributes.builder()
         .parameterName("/My/Secret/Parameter")
         .version(5)
         .build());
 IStringParameter secretValueVersionFromToken = StringParameter.fromSecureStringParameterAttributes(this, "MySecureValueVersionFromToken", SecureStringParameterAttributes.builder()
         .parameterName("/My/Secret/Parameter")
         // parameter version from token
         .version(parameterVersion)
         .build());

You can also reference an existing SSM Parameter Store value that matches an AWS specific parameter type: 

 // Example automatically generated from non-compiling source. May contain errors.
 StringParameter.valueForTypedStringParameterV2(stack, "/My/Public/Parameter", ParameterValueType.AWS_EC2_IMAGE_ID);

To do the same for a SSM Parameter Store value that is stored as a list: 

 // Example automatically generated from non-compiling source. May contain errors.
 StringListParameter.valueForTypedListParameter(stack, "/My/Public/Parameter", ParameterValueType.AWS_EC2_IMAGE_ID);

Lookup existing parameters

You can also use an existing parameter by looking up the parameter from the AWS environment. This method uses AWS API calls to lookup the value from SSM during synthesis. 

 // Example automatically generated from non-compiling source. May contain errors.
 String stringValue = StringParameter.valueFromLookup(stack, "/My/Public/Parameter");

When using valueFromLookup an initial value of 'dummy-value-for-${parameterName}' (dummy-value-for-/My/Public/Parameter in the above example) is returned prior to the lookup being performed. This can lead to errors if you are using this value in places that require a certain format. For example if you have stored the ARN for a SNS topic in a SSM Parameter which you want to lookup and provide to Topic.fromTopicArn() 

 String arnLookup = StringParameter.valueFromLookup(this, "/my/topic/arn");
 Topic.fromTopicArn(this, "Topic", arnLookup);

Initially arnLookup will be equal to dummy-value-for-/my/topic/arn which will cause Topic.fromTopicArn to throw an error indicating that the value is not in arn format.

For these use cases you need to handle the dummy-value in your code. For example: 

 String arnLookup = StringParameter.valueFromLookup(this, "/my/topic/arn");
 String arnLookupValue;
 if (arnLookup.includes("dummy-value")) {
     arnLookupValue = this.formatArn(ArnComponents.builder()
             .service("sns")
             .resource("topic")
             .resourceName(arnLookup)
             .build());
 } else {
     arnLookupValue = arnLookup;
 }
 
 Topic.fromTopicArn(this, "Topic", arnLookupValue);

Alternatively, if the property supports tokens you can convert the parameter value into a token to be resolved after the lookup has been completed. 

 String arnLookup = StringParameter.valueFromLookup(this, "/my/role/arn");
 Role.fromRoleArn(this, "role", Lazy.string(Map.of("produce", () => arnLookup)));

Creating new SSM Parameters in your CDK app

You can create either ssm.StringParameter or ssm.StringListParameters in a CDK app. These are public (not secret) values. Parameters of type SecureString cannot be created directly from a CDK application; if you want to provision secrets automatically, use Secrets Manager Secrets (see the @aws-cdk/aws-secretsmanager package). 

 StringParameter.Builder.create(this, "Parameter")
         .allowedPattern(".*")
         .description("The value Foo")
         .parameterName("FooParameter")
         .stringValue("Foo")
         .tier(ParameterTier.ADVANCED)
         .build();
 

 // Create a new SSM Parameter holding a String
 StringParameter param = StringParameter.Builder.create(stack, "StringParameter")
         // description: 'Some user-friendly description',
         // name: 'ParameterName',
         .stringValue("Initial parameter value")
         .build();
 
 // Grant read access to some Role
 param.grantRead(role);
 
 // Create a new SSM Parameter holding a StringList
 StringListParameter listParameter = StringListParameter.Builder.create(stack, "StringListParameter")
         // description: 'Some user-friendly description',
         // name: 'ParameterName',
         .stringListValue(List.of("Initial parameter value A", "Initial parameter value B"))
         .build();

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.

Skip navigation links

Copyright © 2022. All rights reserved.