feat(core): weak references

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

@@ -94,8 +94,28 @@ nested stack and referenced using `Fn::GetAtt "Outputs.Xxx"` from the parent.
 
 Nested stacks also support the use of Docker image and file assets.
 
+## Weak References
 
-## Durations
+The CDK automatically wires up cross-stack references within a single app. By default, the CDK uses the CloudFormation's
+[`Fn::ImportValue`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-importvalue.html)
+instrinsic to achieve this. To prevent interruption, CloudFormation restricts modification of any `Output` of a stack
+that is imported via this intrinsic.
+
+In many cases, this can be too restrictive. Some resources guarantee that change to its physical name does not entirely
+delete the resource. Weak references relax this restriction for specific Constructs. Instead of using the
+`Fn::ImportValue` intrinsic, [SSM Parameter
+Types](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html#aws-ssm-parameter-types)
+are used instead.
+
+Enable weak reference for a resource:
+
+```ts
+resource.node.enableWeakReferences();
+```
+
+## CDK Types
+
+### Durations
 
 To make specifications of time intervals unambiguous, a single class called
 `Duration` is used throughout the AWS Construct Library by all constructs
@@ -113,7 +133,7 @@ Duration.days(7)        // 7 days
 Duration.parse('PT5M')  // 5 minutes
 ```
 
-## Size (Digital Information Quantity)
+### Size (Digital Information Quantity)
 
 To make specification of digital storage quantities unambiguous, a class called
 `Size` is available.
@@ -137,7 +157,7 @@ Size.mebibytes(2).toKibibytes()                      // yields 2048
 Size.kibibytes(2050).toMebibyte({ integral: false }) // yields 2
 ```
 
-## Secrets
+### Secrets
 
 To help avoid accidental storage of secrets as plain text, we use the `SecretValue` type to
 represent secrets. Any construct that takes a value that should be a secret (such as

packages/@aws-cdk/core/lib/construct-compat.ts

@@ -267,6 +267,8 @@ export class ConstructNode {
    */
   public readonly _actualNode: constructs.Node;
 
+  private _weakReference: boolean = false;
+
   constructor(host: Construct, scope: IConstruct, id: string) {
     this._actualNode = new constructs.Node(host, scope, id);
 
@@ -477,6 +479,21 @@ export class ConstructNode {
    * @experimental
    */
   public tryRemoveChild(childName: string): boolean { return this._actualNode.tryRemoveChild(childName); }
+
+  /**
+   * Calling this method will mark all cross-stack references to this node as weak references.
+   * See README.md to learn more about weak references.
+   */
+  public enableWeakReference() {
+    this._weakReference = true;
+  }
+
+  /**
+   * Whether this node should use weak references when referred across stacks.
+   */
+  public get weakReference() {
+    return this._weakReference;
+  }
 }
 
 /**

packages/@aws-cdk/core/lib/private/refs.ts

@@ -12,6 +12,7 @@ import { Token } from '../token';
 import { CfnReference } from './cfn-reference';
 import { Intrinsic } from './intrinsic';
 import { findTokens } from './resolve';
+import { SsmStringParameter } from './ssm-parameter';
 import { makeUniqueId } from './uniqueid';
 
 /**
@@ -99,6 +100,10 @@ function resolveValue(consumer: Stack, reference: CfnReference): IResolvable {
   consumer.addDependency(producer,
     `${consumer.node.path} -> ${reference.target.node.path}.${reference.displayName}`);
 
+  if (reference.target.node.weakReference) {
+    return createSsmParameter(consumer, reference);
+  }
+
   return createImportValue(reference);
 }
 
@@ -156,11 +161,36 @@ function findAllReferences(root: IConstruct) {
 // export/import
 // ------------------------------------------------------------------------------------------------
 
+function createSsmParameter(consumer: Stack, reference: CfnReference): Intrinsic {
+  const exportingStack = Stack.of(reference.target);
+  const id = makeUniqueId([ JSON.stringify(exportingStack.resolve(reference)) ]);
+
+  // include the stack name, SSM parameters are not stack-local.
+  // use SSM hierarchy format - https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-su-organize.html
+  const parameterName = `/stacks/${exportingStack.stackName}/${id}`;
+
+  new SsmStringParameter(exportingStack, `SSMExport${id}`, {
+    name: parameterName,
+    value: Token.asString(reference),
+    description: `[cdk] exported from stack "${exportingStack.stackName}" for use as parameter in a different stack`,
+  });
+
+  const parameterId = `SsmParameterValue:${parameterName}:C96584B6-F00A-464E-AD19-53AFF4B05118`;
+  let cfnparameter = consumer.node.tryFindChild(parameterId);
+  if (!cfnparameter) {
+    cfnparameter = new CfnParameter(consumer, parameterId, {
+      type: 'AWS::SSM::Parameter::Value<String>',
+      default: parameterName,
+    });
+  }
+  return new Intrinsic({ Ref: (cfnparameter as CfnElement).logicalId });
+}
+
 /**
  * Imports a value from another stack by creating an "Output" with an "ExportName"
  * and returning an "Fn::ImportValue" token.
  */
-function createImportValue(reference: Reference): Intrinsic {
+function createImportValue(reference: CfnReference): Intrinsic {
   const exportingStack = Stack.of(reference.target);
 
   // Ensure a singleton "Exports" scoping Construct

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

@@ -0,0 +1,33 @@
+import { CfnResource } from '../cfn-resource';
+import { Construct } from '../construct-compat';
+
+export interface SsmStringParameterProps {
+  /**
+   * Name of the ssm string parameter. Should be unique for the AWS account.
+   */
+  readonly name: string;
+  /**
+   * The value stored in SSM
+   */
+  readonly value: string;
+  /**
+   * Optional description
+   */
+  readonly description?: string;
+}
+
+export class SsmStringParameter extends Construct {
+  constructor(scope: Construct, id: string, props: SsmStringParameterProps) {
+    super(scope, id);
+
+    new CfnResource(this, id, {
+      type: 'AWS::SSM::Parameter',
+      properties: {
+        Name: props.name,
+        Description: props.description,
+        Type: 'String',
+        Value: props.value,
+      },
+    });
+  }
+}

packages/@aws-cdk/core/test/private/test.ssm-parameter.ts

@@ -0,0 +1,31 @@
+import { Test } from 'nodeunit';
+import { Stack } from '../../lib';
+import { SsmStringParameter } from '../../lib/private/ssm-parameter';
+import { toCloudFormation } from '../util';
+
+export = {
+  'ssm string parameter construct is correctly rendered'(test: Test) {
+    const stack = new Stack();
+    new SsmStringParameter(stack, 'string-param', {
+      name: 'ParamName',
+      value: 'ParamValue',
+      description: 'ParamDescription',
+    });
+
+    test.deepEqual(toCloudFormation(stack), {
+      Resources: {
+        stringparam5E4312EC: {
+          Type: 'AWS::SSM::Parameter',
+          Properties: {
+            Name: 'ParamName',
+            Description: 'ParamDescription',
+            Type: 'String',
+            Value: 'ParamValue',
+          },
+        },
+      },
+    });
+
+    test.done();
+  },
+};

packages/@aws-cdk/core/test/test.stack.ts

@@ -1,8 +1,8 @@
 import * as cxapi from '@aws-cdk/cx-api';
 import { Test } from 'nodeunit';
 import {
-  App, CfnCondition, CfnInclude, CfnOutput, CfnParameter,
-  CfnResource, Construct, ConstructNode, Lazy, ScopedAws, Stack, Tag, validateString } from '../lib';
+  App, CfnCondition, CfnInclude, CfnOutput,
+  CfnParameter, CfnResource, Construct, ConstructNode, Lazy, ScopedAws, Stack, Tag, validateString } from '../lib';
 import { Intrinsic } from '../lib/private/intrinsic';
 import { PostResolveToken } from '../lib/util';
 import { toCloudFormation } from './util';
@@ -866,6 +866,111 @@ export = {
 
     test.done();
   },
+
+  'weak references across stacks correctly resolve to ssm parameters'(test: Test) {
+    // GIVEN
+    const app = new App();
+    const stack1 = new Stack(app, 'Stack1');
+    const stack2 = new Stack(app, 'Stack2');
+    const resource = new CfnResource(stack1, 'Resource1', {
+      type: 'Foo::Bar',
+    });
+    resource.node.enableWeakReference();
+
+    // WHEN
+    new CfnResource(stack2, 'Resource2', {
+      type: 'Foo::Baz',
+      properties: {
+        Value: resource.ref,
+      },
+    });
+
+    // THEN
+    const assembly = app.synth();
+    const template1 = assembly.getStackByName(stack1.stackName).template;
+    const template2 = assembly.getStackByName(stack2.stackName).template;
+
+    test.deepEqual(template1, {
+      Resources: {
+        Resource1: { Type: 'Foo::Bar' },
+        SSMExportRefResource149D6AE9B: {
+          Type: 'AWS::SSM::Parameter',
+          Properties: {
+            Name: '/stacks/Stack1/RefResource1',
+            Description: '[cdk] exported from stack "Stack1" for use as parameter in a different stack',
+            Type: 'String',
+            Value: { Ref: 'Resource1' },
+          },
+        },
+      },
+    });
+    test.deepEqual(template2, {
+      Resources: {
+        Resource2: {
+          Type: 'Foo::Baz',
+          Properties: {
+            Value: {
+              Ref: 'SsmParameterValuestacksStack1RefResource1C96584B6F00A464EAD1953AFF4B05118',
+            },
+          },
+        },
+      },
+      Parameters: {
+        SsmParameterValuestacksStack1RefResource1C96584B6F00A464EAD1953AFF4B05118: {
+          Type: 'AWS::SSM::Parameter::Value<String>',
+          Default: '/stacks/Stack1/RefResource1',
+        },
+      },
+    });
+
+    test.done();
+  },
+
+  'weak references across stacks with lazy tokens work'(test: Test) {
+    // GIVEN
+    const app = new App();
+    const stack1 = new Stack(app, 'Stack1');
+    const resource = new CfnResource(stack1, 'Resource1', {
+      type: 'Foo::Bar',
+      properties: {
+        Key1: 'Value1',
+      },
+    });
+    resource.node.enableWeakReference();
+    const stack2 = new Stack(app, 'Stack2');
+
+    // WHEN - used in another stack
+    new CfnResource(stack2, 'Resource2', {
+      type: 'Foo::Bar',
+      properties: {
+        Key1: Lazy.stringValue({ produce: () => resource.ref }),
+      },
+    });
+
+    // THEN
+    const assembly = app.synth();
+    const template2 = assembly.getStackByName(stack2.stackName).template;
+    test.deepEqual(template2, {
+      Resources: {
+        Resource2: {
+          Type: 'Foo::Bar',
+          Properties: {
+            Key1: {
+              Ref: 'SsmParameterValuestacksStack1RefResource1C96584B6F00A464EAD1953AFF4B05118',
+            },
+          },
+        },
+      },
+      Parameters: {
+        SsmParameterValuestacksStack1RefResource1C96584B6F00A464EAD1953AFF4B05118: {
+          Type: 'AWS::SSM::Parameter::Value<String>',
+          Default: '/stacks/Stack1/RefResource1',
+        },
+      },
+    });
+
+    test.done();
+  },
 };
 
 class StackWithPostProcessor extends Stack {