refactor(ssm): API cleanups

packages/@aws-cdk/aws-ssm/lib/index.ts

@@ -1,5 +1,4 @@
 export * from './parameter';
-export * from './parameter-store-string';
 
 // AWS::SSM CloudFormation Resources:
 export * from './ssm.generated';

packages/@aws-cdk/aws-ssm/lib/parameter.ts

@@ -1,5 +1,5 @@
 import iam = require('@aws-cdk/aws-iam');
-import { CfnDynamicReference, CfnDynamicReferenceService, Construct, Fn, IResource, Resource, Stack, Token } from '@aws-cdk/cdk';
+import { CfnDynamicReference, CfnDynamicReferenceService, CfnParameter, Construct, Fn, IResource, Resource, Stack, Token } from '@aws-cdk/cdk';
 import ssm = require('./ssm.generated');
 
 /**
@@ -86,9 +86,9 @@ export interface ParameterOptions {
   /**
    * The name of the parameter.
    *
-   * @default a name will be generated by CloudFormation
+   * @default - a name will be generated by CloudFormation
    */
-  readonly name?: string;
+  readonly parameterName?: string;
 }
 
 /**
@@ -145,22 +145,79 @@ abstract class ParameterBase extends Resource implements IParameter {
 }
 
 const STRING_PARAM_TYPE = 'String';
+const SECURE_STRING_PARAM_TYPE = 'SecureString';
 const STRINGLIST_PARAM_TYPE = 'StringList';
 
+export interface StringParameterAttributes {
+  /**
+   * The name of the parameter store value
+   */
+  readonly parameterName: string;
+
+  /**
+   * The version number of the value you wish to retrieve.
+   *
+   * @default The latest version will be retrieved.
+   */
+  readonly version?: number;
+}
+
+export interface SecureStringParameterAttributes {
+  /**
+   * The name of the parameter store value
+   */
+  readonly parameterName: string;
+
+  /**
+   * The version number of the value you wish to retrieve. This is required for secure strings.
+   */
+  readonly version: number;
+}
+
 /**
  * Creates a new String SSM Parameter.
  * @resource AWS::SSM::Parameter
  */
 export class StringParameter extends ParameterBase implements IStringParameter {
 
   /**
-   * Imports an external string parameter.
+   * Imports an external string parameter by name.
    */
   public static fromStringParameterName(scope: Construct, id: string, stringParameterName: string): IStringParameter {
+    return this.fromStringParameterAttributes(scope, id, { parameterName: stringParameterName });
+  }
+
+  /**
+   * Imports an external string parameter with name and optional version.
+   */
+  public static fromStringParameterAttributes(scope: Construct, id: string, attrs: StringParameterAttributes): IStringParameter {
+    if (!attrs.parameterName) {
+      throw new Error(`parameterName cannot be an empty string`);
+    }
+
+    const stringValue = attrs.version
+      ? new CfnDynamicReference(CfnDynamicReferenceService.Ssm, `${attrs.parameterName}:${attrs.version}`).toString()
+      : new CfnParameter(scope, `${id}.Parameter`, { type: 'AWS::SSM::Parameter::Value<String>', default: attrs.parameterName }).valueAsString;
+
     class Import extends ParameterBase {
-      public readonly parameterName = stringParameterName;
+      public readonly parameterName = attrs.parameterName;
       public readonly parameterType = STRING_PARAM_TYPE;
-      public readonly stringValue = new CfnDynamicReference(CfnDynamicReferenceService.Ssm, stringParameterName).toString();
+      public readonly stringValue = stringValue;
+    }
+
+    return new Import(scope, id);
+  }
+
+  /**
+   * Imports a secure string parameter from the SSM parameter store.
+   */
+  public static fromSecureStringParameterAttributes(scope: Construct, id: string, attrs: SecureStringParameterAttributes): IStringParameter {
+    const stringValue = new CfnDynamicReference(CfnDynamicReferenceService.SsmSecure, `${attrs.parameterName}:${attrs.version}`).toString();
+
+    class Import extends ParameterBase {
+      public readonly parameterName = attrs.parameterName;
+      public readonly parameterType = SECURE_STRING_PARAM_TYPE;
+      public readonly stringValue = stringValue;
     }
 
     return new Import(scope, id);
@@ -180,7 +237,7 @@ export class StringParameter extends ParameterBase implements IStringParameter {
     const resource = new ssm.CfnParameter(this, 'Resource', {
       allowedPattern: props.allowedPattern,
       description: props.description,
-      name: props.name,
+      name: props.parameterName,
       type: STRING_PARAM_TYPE,
       value: props.stringValue,
     });
@@ -228,7 +285,7 @@ export class StringListParameter extends ParameterBase implements IStringListPar
     const resource = new ssm.CfnParameter(this, 'Resource', {
       allowedPattern: props.allowedPattern,
       description: props.description,
-      name: props.name,
+      name: props.parameterName,
       type: STRINGLIST_PARAM_TYPE,
       value: props.stringListValue.join(','),
     });

packages/@aws-cdk/aws-ssm/test/integ.parameter-store-string.lit.expected.json

@@ -13,17 +13,22 @@
   },
   {
     "Parameters": {
-      "MyValueParameterCCC58B13": {
+      "MyValueParameter": {
         "Type": "AWS::SSM::Parameter::Value<String>",
         "Default": "/My/Public/Parameter"
       }
     },
+    "Resources": {
+      "Dummy": {
+        "Type": "AWS::SNS::Topic"
+      }
+    },
     "Outputs": {
       "TheValue": {
         "Value": {
-          "Ref": "MyValueParameterCCC58B13"
+          "Ref": "MyValueParameter"
         }
       }
     }
   }
-]
+]

packages/@aws-cdk/aws-ssm/test/integ.parameter-store-string.lit.ts

@@ -7,7 +7,7 @@ class CreatingStack extends cdk.Stack {
     super(scope, id);
 
     new ssm.StringParameter(this, 'String', {
-      name: '/My/Public/Parameter',
+      parameterName: '/My/Public/Parameter',
       stringValue: 'abcdef'
     });
   }
@@ -20,19 +20,20 @@ class UsingStack extends cdk.Stack {
     /// !show
     // Retrieve the latest value of the non-secret parameter
     // with name "/My/String/Parameter".
-    const stringValue = new ssm.ParameterStoreString(this, 'MyValue', {
+    const stringValue = ssm.StringParameter.fromStringParameterAttributes(this, 'MyValue', {
       parameterName: '/My/Public/Parameter',
       // 'version' can be specified but is optional.
     }).stringValue;
 
     // Retrieve a specific version of the secret (SecureString) parameter.
     // 'version' is always required.
-    const secretValue = new ssm.ParameterStoreSecureString({
+    const secretValue = ssm.StringParameter.fromSecureStringParameterAttributes(this, 'MySecureValue', {
       parameterName: '/My/Secret/Parameter',
       version: 5
     });
     /// !hide
 
+    new cdk.CfnResource(this, 'Dummy', { type: 'AWS::SNS::Topic' });
     new cdk.CfnOutput(this, 'TheValue', { value: stringValue });
 
     // Cannot be provisioned so cannot be actually used

packages/@aws-cdk/aws-ssm/test/test.parameter-store-string.ts

@@ -9,7 +9,7 @@ export = {
     const stack = new cdk.Stack();
 
     // WHEN
-    const ref = new ssm.ParameterStoreString(stack, 'Ref', {
+    const ref = ssm.StringParameter.fromStringParameterAttributes(stack, 'Ref', {
       parameterName: '/some/key',
       version: 123
     });
@@ -25,21 +25,21 @@ export = {
     const stack = new cdk.Stack();
 
     // WHEN
-    const ref = new ssm.ParameterStoreString(stack, 'Ref', {
+    const ref = ssm.StringParameter.fromStringParameterAttributes(stack, 'Ref', {
       parameterName: '/some/key',
     });
 
     // THEN
     expect(stack).toMatch({
       Parameters: {
-        RefParameter407AF5C8: {
+        RefParameter: {
           Type: "AWS::SSM::Parameter::Value<String>",
           Default: "/some/key"
         }
       }
     });
 
-    test.deepEqual(stack.resolve(ref.stringValue), { Ref: 'RefParameter407AF5C8' });
+    test.deepEqual(stack.resolve(ref.stringValue), { Ref: 'RefParameter' });
 
     test.done();
   },
@@ -49,10 +49,10 @@ export = {
     const stack = new cdk.Stack();
 
     // WHEN
-    const ref = new ssm.ParameterStoreSecureString({
+    const ref = ssm.StringParameter.fromSecureStringParameterAttributes(stack, 'Ref', {
       parameterName: '/some/key',
       version: 123
-    });
+    }).stringValue;
 
     // THEN
     test.equal(stack.resolve(ref), '{{resolve:ssm-secure:/some/key:123}}');
@@ -66,10 +66,10 @@ export = {
 
     // WHEN
     test.throws(() => {
-      new ssm.ParameterStoreString(stack, 'Ref', {
+      ssm.StringParameter.fromStringParameterAttributes(stack, 'Ref', {
         parameterName: '',
       });
-    }, /parameterName cannot be empty/);
+    }, /parameterName cannot be an empty string/);
 
     test.done();
   },