feat(ssm): allow referencing "latest" version of SSM parameter (#1768)

There are many requests from people to integrate with SSM parameter
store in same way, and in particular to get the latest version of
a parameter.

The mechanisms to get a specific version or the latest version
at deployment time are very different, but both are now supported
by and hidden in the ssm.ParameterStoreString class.

Make the naming around properties that return a (potentially
tokenized) value consistent. All properties of objects that return
a string value are `stringValue`, all properties of objects that
return a list value are `stringListValue`.

Fixes #1587.

BREAKING CHANGE: Rename `parameter.valueAsString` =>
`parameter.stringValue`, rename `parameter.valueAsList` =>
`parameter.stringListValue`, rename `ssmParameter.parameterValue` =>
`ssmParameter.stringValue` or `ssmParameter.stringListValue` depending
on type, rename `secretString.value` => `secretString.stringValue`,
rename `secret.toSecretString()` =>`secret.secretString`

Author: rix0rrr

packages/@aws-cdk/assets-docker/lib/image-asset.ts

@@ -61,7 +61,7 @@ export class DockerImageAsset extends cdk.Construct {
     this.node.addMetadata(cxapi.ASSET_METADATA, asset);
 
     // parse repository name and tag from the parameter (<REPO_NAME>:<TAG>)
-    const components = cdk.Fn.split(':', imageNameParameter.valueAsString);
+    const components = cdk.Fn.split(':', imageNameParameter.stringValue);
     const repositoryName = cdk.Fn.select(0, components).toString();
     const imageTag = cdk.Fn.select(1, components).toString();
 

packages/@aws-cdk/assets/lib/asset.ts

@@ -109,9 +109,9 @@ export class Asset extends cdk.Construct {
       description: `S3 key for asset version "${this.node.path}"`
     });
 
-    this.s3BucketName = bucketParam.value.toString();
-    this.s3Prefix = cdk.Fn.select(0, cdk.Fn.split(cxapi.ASSET_PREFIX_SEPARATOR, keyParam.valueAsString)).toString();
-    const s3Filename = cdk.Fn.select(1, cdk.Fn.split(cxapi.ASSET_PREFIX_SEPARATOR, keyParam.valueAsString)).toString();
+    this.s3BucketName = bucketParam.stringValue;
+    this.s3Prefix = cdk.Fn.select(0, cdk.Fn.split(cxapi.ASSET_PREFIX_SEPARATOR, keyParam.stringValue)).toString();
+    const s3Filename = cdk.Fn.select(1, cdk.Fn.split(cxapi.ASSET_PREFIX_SEPARATOR, keyParam.stringValue)).toString();
     this.s3ObjectKey = `${this.s3Prefix}${s3Filename}`;
 
     this.bucket = s3.Bucket.import(this, 'AssetBucket', {

packages/@aws-cdk/aws-secretsmanager/README.md

@@ -5,15 +5,19 @@ const secretsmanager = require('@aws-cdk/aws-secretsmanager');
 ```
 
 ### Create a new Secret in a Stack
-
-In order to have SecretsManager generate a new secret value automatically, you can get started with the following:
+In order to have SecretsManager generate a new secret value automatically,
+you can get started with the following:
 
 [example of creating a secret](test/integ.secret.lit.ts)
 
-The `Secret` construct does not allow specifying the `SecretString` property of the `AWS::SecretsManager::Secret`
-resource as this will almost always lead to the secret being surfaced in plain text and possibly committed to your 
-source control. If you need to use a pre-existing secret, the recommended way is to manually provision 
-the secret in *AWS SecretsManager* and use the `Secret.import` method to make it available in your CDK Application:
+The `Secret` construct does not allow specifying the `SecretString` property
+of the `AWS::SecretsManager::Secret` resource (as this will almost always
+lead to the secret being surfaced in plain text and possibly committed to
+your source control).
+
+If you need to use a pre-existing secret, the recommended way is to manually
+provision the secret in *AWS SecretsManager* and use the `Secret.import`
+method to make it available in your CDK Application:
 
 ```ts
 const secret = Secret.import(scope, 'ImportedSecret', {
@@ -22,3 +26,6 @@ const secret = Secret.import(scope, 'ImportedSecret', {
   encryptionKey,
 });
 ```
+
+SecretsManager secret values can only be used in select set of properties. For the
+list of properties, see [the CloudFormation Dynamic References documentation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references.htm).

packages/@aws-cdk/aws-secretsmanager/lib/secret-string.ts

@@ -44,7 +44,7 @@ export class SecretString extends cdk.DynamicReference {
   /**
    * Return the full value of the secret
    */
-  public get value(): string {
+  public get stringValue(): string {
     return this.resolveStringForJsonKey('');
   }
 

packages/@aws-cdk/aws-secretsmanager/lib/secret.ts

@@ -20,10 +20,21 @@ export interface ISecret extends cdk.IConstruct {
   readonly secretArn: string;
 
   /**
-   * Returns a SecretString corresponding to this secret, so that the secret value can be referred to from other parts
-   * of the application (such as an RDS instance's master user password property).
+   * Returns a SecretString corresponding to this secret.
+   *
+   * SecretString represents the value of the Secret.
+   */
+  readonly secretString: SecretString;
+
+  /**
+   * Retrieve the value of the Secret, as a string.
    */
-  toSecretString(): SecretString;
+  readonly stringValue: string;
+
+  /**
+   * Interpret the secret as a JSON object and return a field's value from it
+   */
+  jsonFieldValue(key: string): string;
 
   /**
    * Exports this secret.
@@ -97,7 +108,7 @@ export abstract class SecretBase extends cdk.Construct implements ISecret {
   public abstract readonly encryptionKey?: kms.IEncryptionKey;
   public abstract readonly secretArn: string;
 
-  private secretString?: SecretString;
+  private _secretString?: SecretString;
 
   public abstract export(): SecretImportProps;
 
@@ -127,9 +138,17 @@ export abstract class SecretBase extends cdk.Construct implements ISecret {
     }
   }
 
-  public toSecretString() {
-    this.secretString = this.secretString || new SecretString(this, 'SecretString', { secretId: this.secretArn });
-    return this.secretString;
+  public get secretString() {
+    this._secretString = this._secretString || new SecretString(this, 'SecretString', { secretId: this.secretArn });
+    return this._secretString;
+  }
+
+  public get stringValue() {
+    return this.secretString.stringValue;
+  }
+
+  public jsonFieldValue(key: string): string {
+    return this.secretString.jsonFieldValue(key);
   }
 }
 

packages/@aws-cdk/aws-secretsmanager/test/example.app-with-secret.lit.ts

@@ -1,16 +1,26 @@
+import iam = require('@aws-cdk/aws-iam');
 import cdk = require('@aws-cdk/cdk');
 import secretsmanager = require('../lib');
 
-const app = new cdk.App();
-const stack = new cdk.Stack(app, 'aws-cdk-rds-integ');
+class ExampleStack extends cdk.Stack {
+  constructor(scope: cdk.App, id: string) {
+    super(scope, id);
+
+    /// !show
+    const loginSecret = new secretsmanager.SecretString(this, 'Secret', {
+      secretId: 'SomeLogin'
+    });
 
-/// !show
-const loginSecret = new secretsmanager.SecretString(stack, 'Secret', { secretId: 'SomeLogin', });
+    new iam.User(this, 'User', {
+      // Get the 'password' field from the secret that looks like
+      // { "username": "XXXX", "password": "YYYY" }
+      password: loginSecret.jsonFieldValue('password')
+    });
+    /// !hide
 
-// DO NOT ACTUALLY DO THIS, as this will expose your secret.
-// This code only exists to show how the secret would be used.
-new cdk.Output(stack, 'SecretUsername', { value: loginSecret.jsonFieldValue('username') });
-new cdk.Output(stack, 'SecretPassword', { value: loginSecret.jsonFieldValue('password') });
-/// !hide
+  }
+}
 
+const app = new cdk.App();
+new ExampleStack(app, 'aws-cdk-secret-integ');
 app.run();

packages/@aws-cdk/aws-secretsmanager/test/integ.secret.lit.expected.json

@@ -60,6 +60,25 @@
       "Properties": {
         "GenerateSecretString": {}
       }
+    },
+    "User00B015A1": {
+      "Type": "AWS::IAM::User",
+      "Properties": {
+        "LoginProfile": {
+          "Password": {
+            "Fn::Join": [
+              "",
+              [
+                "{{resolve:secretsmanager:",
+                {
+                  "Ref": "SecretA720EF05"
+                },
+                ":SecretString:::}}"
+              ]
+            ]
+          }
+        }
+      }
     }
   }
 }

packages/@aws-cdk/aws-secretsmanager/test/integ.secret.lit.ts

@@ -2,13 +2,23 @@ import iam = require('@aws-cdk/aws-iam');
 import cdk = require('@aws-cdk/cdk');
 import secretsManager = require('../lib');
 
-const app = new cdk.App();
-const stack = new cdk.Stack(app, 'Integ-SecretsManager-Secret');
-const role = new iam.Role(stack, 'TestRole', { assumedBy: new iam.AccountRootPrincipal() });
+class SecretsManagerStack extends cdk.Stack {
+  constructor(scope: cdk.App, id: string) {
+    super(scope, id);
+
+    const role = new iam.Role(this, 'TestRole', { assumedBy: new iam.AccountRootPrincipal() });
 
-/// !show
-const secret = new secretsManager.Secret(stack, 'Secret');
-secret.grantRead(role);
-/// !hide
+    /// !show
+    const secret = new secretsManager.Secret(this, 'Secret');
+    secret.grantRead(role);
 
+    new iam.User(this, 'User', {
+      password: secret.stringValue
+    });
+    /// !hide
+  }
+}
+
+const app = new cdk.App();
+new SecretsManagerStack(app, 'Integ-SecretsManager-Secret');
 app.run();

packages/@aws-cdk/aws-secretsmanager/test/test.secret-string.ts

@@ -13,7 +13,7 @@ export = {
     });
 
     // THEN
-    test.equal(ref.node.resolve(ref.value), '{{resolve:secretsmanager:SomeSecret:SecretString:::}}');
+    test.equal(ref.node.resolve(ref.stringValue), '{{resolve:secretsmanager:SomeSecret:SecretString:::}}');
 
     test.done();
   },

packages/@aws-cdk/aws-secretsmanager/test/test.secret.ts

@@ -224,7 +224,7 @@ export = {
     new cdk.Resource(stack, 'FakeResource', {
       type: 'CDK::Phony::Resource',
       properties: {
-        value: secret.toSecretString().value
+        value: secret.stringValue
       }
     });