diff --git a/packages/@aws-cdk/aws-ssm/README.md b/packages/@aws-cdk/aws-ssm/README.md index 820a2fe2931be..406bab8b9f804 100644 --- a/packages/@aws-cdk/aws-ssm/README.md +++ b/packages/@aws-cdk/aws-ssm/README.md @@ -20,6 +20,56 @@ your CDK app by using `ssm.StringParameter.fromStringParameterAttributes`: [using SSM parameter](test/integ.parameter-store-string.lit.ts) +### 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. + +```ts +const stringValue = ssm.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()` + +```ts +const arnLookup = ssm.StringParameter.valueFromLookup(this, '/my/topic/arn'); +sns.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: + +```ts +const arnLookup = ssm.StringParameter.valueFromLookup(this, '/my/topic/arn'); +let arnLookupValue: string; +if (arnLookup.includes('dummy-value')) { + arnLookupValue = this.formatArn({ + service: 'sns', + resource: 'topic', + resourceName: arnLookup, + }); + +} else { + arnLookupValue = arnLookup; +} + +sns.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. + +```ts +const arnLookup = ssm.StringParameter.valueFromLookup(this, '/my/role/arn'); +iam.Role.fromRoleArn(this, 'role', Lazy.string({ produce: () => arnLookup })); +``` + ## Creating new SSM Parameters in your CDK app You can create either `ssm.StringParameter` or `ssm.StringListParameter`s in @@ -43,3 +93,4 @@ new ssm.StringParameter(this, 'Parameter', { 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. + diff --git a/packages/@aws-cdk/aws-ssm/rosetta/default.ts-fixture b/packages/@aws-cdk/aws-ssm/rosetta/default.ts-fixture index 66143d00d0bff..de86c8c95a2da 100644 --- a/packages/@aws-cdk/aws-ssm/rosetta/default.ts-fixture +++ b/packages/@aws-cdk/aws-ssm/rosetta/default.ts-fixture @@ -1,7 +1,9 @@ // Fixture with packages imported, but nothing else import { Construct } from 'constructs'; -import { Stack } from '@aws-cdk/core'; +import { Stack, Lazy } from '@aws-cdk/core'; import * as ssm from '@aws-cdk/aws-ssm'; +import * as sns from '@aws-cdk/aws-sns'; +import * as iam from '@aws-cdk/aws-iam'; class Fixture extends Stack { constructor(scope: Construct, id: string) {