Add includeNestedStack() method.

Author: skinny85

packages/@aws-cdk/cloudformation-include/README.md

@@ -311,6 +311,15 @@ role.addToPolicy(new iam.PolicyStatement({
 }));
 ```
 
+You can also include the nested stack after the `CfnInclude` object was created,
+instead of doing it on construction:
+
+```ts
+parentTemplate.includeNestedStack('ChildTemplate', {
+  templateFile: 'path/to/my-nested-template.json',
+});
+```
+
 ## Vending CloudFormation templates as Constructs
 
 In many cases, there are existing CloudFormation templates that are not entire applications,

packages/@aws-cdk/cloudformation-include/lib/cfn-include.ts

@@ -289,10 +289,62 @@ export class CfnInclude extends core.CfnElement {
     return ret;
   }
 
+  /**
+   * Includes a template for a child stack inside of this parent template.
+   * A child with this logical ID must exist in the template,
+   * and be of type AWS::CloudFormation::Stack.
+   * This is equivalent to specifying the value in the {@link CfnIncludeProps.nestedStacks}
+   * property on object construction.
+   *
+   * @param logicalId the ID of the stack to retrieve, as it appears in the template
+   * @param nestedStackProps the properties of the included child Stack
+   * @returns the same {@link IncludedNestedStack} object that {@link getNestedStack} returns for this logical ID
+   */
+  public includeNestedStack(logicalId: string, nestedStackProps: CfnIncludeProps): IncludedNestedStack {
+    if (logicalId in this.nestedStacks) {
+      throw new Error(`Nested Stack '${logicalId}' was already included in its parent template`);
+    }
+    const cfnStack = this.resources[logicalId];
+    if (!cfnStack) {
+      throw new Error(`Nested Stack with logical ID '${logicalId}' was not found in the template`);
+    }
+    if (cfnStack instanceof core.CfnStack) {
+      // delete the old CfnStack child - one will be created by the NestedStack object
+      this.node.tryRemoveChild(logicalId);
+
+      const self = this;
+      const finder: cfn_parse.ICfnFinder = {
+        findResource(lId): core.CfnResource | undefined {
+          return self.resources[lId];
+        },
+        findRefTarget(elementName: string): core.CfnElement | undefined {
+          return self.resources[elementName] ?? self.parameters[elementName];
+        },
+        findCondition(conditionName: string): core.CfnCondition | undefined {
+          return self.conditions[conditionName];
+        },
+        findMapping(mappingName): core.CfnMapping | undefined {
+          return self.mappings[mappingName];
+        },
+      };
+      const cfnParser = new cfn_parse.CfnParser({
+        finder,
+        parameters: this.parametersToReplace,
+      });
+      // createNestedStack() expects this to be filled
+      this.nestedStacksToInclude[logicalId] = nestedStackProps;
+      this.createNestedStack(logicalId, cfnParser);
+      return this.nestedStacks[logicalId];
+    } else {
+      throw new Error(`Resource with logical ID '${logicalId}' is not a CloudFormation Stack`);
+    }
+  }
+
   /**
    * Returns the NestedStack with name logicalId.
-   * For a nested stack to be returned by this method, it must be specified in the {@link CfnIncludeProps.nestedStacks}
-   * property.
+   * For a nested stack to be returned by this method,
+   * it must be specified either in the {@link CfnIncludeProps.nestedStacks} property,
+   * or through the {@link includeNestedStack} method.
    *
    * @param logicalId the ID of the stack to retrieve, as it appears in the template
    */

packages/@aws-cdk/cloudformation-include/test/nested-stacks.test.ts

@@ -424,6 +424,20 @@ describe('CDK Include for nested stacks', () => {
     });
   });
 
+  test('can lazily include a single child nested stack', () => {
+    const parentTemplate = new inc.CfnInclude(stack, 'ParentStack', {
+      templateFile: testTemplateFilePath('parent-one-child.json'),
+    });
+    const includedChild = parentTemplate.includeNestedStack('ChildStack', {
+      templateFile: testTemplateFilePath('child-no-bucket.json'),
+    });
+
+    expect(includedChild.stack).toMatchTemplate(
+      loadTestFileToJsObject('child-no-bucket.json'),
+    );
+    expect(includedChild.includedTemplate.getResource('GrandChildStack')).toBeDefined();
+  });
+
   describe('for a parent stack with children and grandchildren', () => {
     let assetStack: core.Stack;
     let parentTemplate: inc.CfnInclude;