feat(cfn-include): allow passing Parameters to the included template

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

@@ -131,6 +131,20 @@ and any changes you make to it will be reflected in the resulting template:
 param.default = 'MyDefault';
 ```
 
+You can also provide values for them:
+
+```typescript
+new inc.CfnInclude(stack, 'includeTemplate', {
+  templateFile: 'path/to/my/template'
+  parameterValues: {
+    MyParam: 'my-value',
+  },
+});
+```
+
+This will replace all references to `MyParam` with the string 'my-value',
+and `MyParam` will be removed from the Parameters section of the template.
+
 ## Conditions
 
 If your template uses [CloudFormation Conditions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/conditions-section-structure.html),

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

@@ -23,8 +23,18 @@ export interface CfnIncludeProps {
    * If you include a stack here with an ID that isn't in the template,
    * or is in the template but is not a nested stack,
    * template creation will fail and an error will be thrown.
+   * @default {}
    */
   readonly nestedStacks?: { [stackName: string]: CfnIncludeProps };
+
+  /**
+   * Specifies parameters to be replaced by the values in this mapping.
+   * Any parameters in the template that aren't specified here will be left unmodified.
+   * If you include a parameter here with an ID that isn't in the template,
+   * template creation will fail and an error will be thrown.
+   * @default {}
+   */
+  readonly parameters?: { [parameterName: string]: any };
 }
 
 /**
@@ -55,6 +65,7 @@ export class CfnInclude extends core.CfnElement {
   private readonly conditionsScope: core.Construct;
   private readonly resources: { [logicalId: string]: core.CfnResource } = {};
   private readonly parameters: { [logicalId: string]: core.CfnParameter } = {};
+  private readonly parameterValues: { [parameterName: string]: any };
   private readonly outputs: { [logicalId: string]: core.CfnOutput } = {};
   private readonly nestedStacks: { [logicalId: string]: IncludedNestedStack } = {};
   private readonly nestedStacksToInclude: { [name: string]: CfnIncludeProps };
@@ -64,12 +75,21 @@ export class CfnInclude extends core.CfnElement {
   constructor(scope: core.Construct, id: string, props: CfnIncludeProps) {
     super(scope, id);
 
+    this.parameterValues = props.parameters || {};
+
     // read the template into a JS object
     this.template = futils.readYamlSync(props.templateFile);
 
     // ToDo implement preserveLogicalIds=false
     this.preserveLogicalIds = true;
 
+    // check if all user specified parameter values exist in the template
+    for (const logicalId of Object.keys(this.parameterValues)) {
+      if (!(logicalId in (this.template.Parameters || {}))) {
+        throw new Error(`Parameter with logical ID '${logicalId}' was not found in the template`);
+      }
+    }
+
     // instantiate all parameters
     for (const logicalId of Object.keys(this.template.Parameters || {})) {
       this.createParameter(logicalId);
@@ -204,16 +224,27 @@ export class CfnInclude extends core.CfnElement {
 
     for (const section of Object.keys(this.template)) {
       // render all sections of the template unchanged,
-      // except Conditions, Resources, Parameters, and Outputs which will be taken care of by the created L1s
-      if (section !== 'Conditions' && section !== 'Resources' && section !== 'Parameters' && section !== 'Outputs') {
+      // except Conditions, Resources, Parameters,  and Outputs, which will be taken care of by the created L1s
+      // Metadata and Transform are handled below
+      if (section !== 'Conditions' && section !== 'Resources' && section !== 'Parameters' && section !== 'Outputs'
+        && section !== 'Metadata' && section !== 'Transform') {
         ret[section] = this.template[section];
       }
     }
 
+    // Parameters cannot be referenced from the Mappings, Description, or AWSTemplateFormatVersion sections.
+    const metaTransform = this.createTransformAndMetadata();
+    ret.Metadata = metaTransform.Metadata;
+    ret.Transform = metaTransform.Transform;
+
     return ret;
   }
 
   private createParameter(logicalId: string): void {
+    if (logicalId in (this.parameterValues)) {
+      return;
+    }
+
     const expression = new cfn_parse.CfnParser({
       finder: {
         findResource() { throw new Error('Using GetAtt expressions in Parameter definitions is not allowed'); },
@@ -253,6 +284,7 @@ export class CfnInclude extends core.CfnElement {
           return undefined;
         },
       },
+      parameters: this.parameterValues,
     }).parseValue(this.template.Outputs[logicalId]);
     const cfnOutput = new core.CfnOutput(scope, logicalId, {
       value: outputAttributes.Value,
@@ -294,6 +326,7 @@ export class CfnInclude extends core.CfnElement {
         },
       },
       context: cfn_parse.CfnParsingContext.CONDITIONS,
+      parameters: this.parameterValues,
     });
     const cfnCondition = new core.CfnCondition(this.conditionsScope, conditionName, {
       expression: cfnParser.parseValue(this.template.Conditions[conditionName]),
@@ -348,6 +381,7 @@ export class CfnInclude extends core.CfnElement {
     };
     const cfnParser = new cfn_parse.CfnParser({
       finder,
+      parameters: this.parameterValues,
     });
 
     let l1Instance: core.CfnResource;
@@ -356,13 +390,10 @@ export class CfnInclude extends core.CfnElement {
     } else {
       const l1ClassFqn = cfn_type_to_l1_mapping.lookup(resourceAttributes.Type);
       if (l1ClassFqn) {
-        const options: core.FromCloudFormationOptions = {
-          finder,
-        };
         const [moduleName, ...className] = l1ClassFqn.split('.');
         const module = require(moduleName);  // eslint-disable-line @typescript-eslint/no-require-imports
         const jsClassFromModule = module[className.join('.')];
-        l1Instance = jsClassFromModule.fromCloudFormation(this, logicalId, resourceAttributes, options);
+        l1Instance = jsClassFromModule._fromCloudFormation(this, logicalId, resourceAttributes, cfnParser);
       } else {
         l1Instance = new core.CfnResource(this, logicalId, {
           type: resourceAttributes.Type,
@@ -416,4 +447,30 @@ export class CfnInclude extends core.CfnElement {
 
     return nestedStackResource;
   }
+
+  private createTransformAndMetadata(): { [element: string]: any } {
+    const ret: { [element: string]: any } = {};
+    const self = this;
+    const finder: core.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];
+      },
+    };
+
+    const cfnParser = new cfn_parse.CfnParser({
+      finder,
+      parameters: this.parameterValues,
+    });
+
+    ret.Metadata = cfnParser.parseValue(this.template.Metadata);
+    ret.Transform = cfnParser.parseValue(this.template.Transform);
+
+    return ret;
+  }
 }

packages/@aws-cdk/cloudformation-include/test/test-templates/bucket-with-parameters.json

@@ -45,4 +45,4 @@
       }
     }
   }
-}
+}

packages/@aws-cdk/cloudformation-include/test/test-templates/fn-sub-parameter-shadow.json

@@ -0,0 +1,22 @@
+{
+  "Parameters": {
+    "MyParam": {
+      "Type": "String"
+    }
+  },
+  "Resources": {
+    "Bucket": {
+      "Type": "AWS::S3::Bucket",
+      "Properties": {
+        "BucketName": { 
+          "Fn::Sub": [ 
+            "${MyParam}", 
+            { 
+              "MyParam": { "Ref" : "MyParam" }
+            } 
+          ]
+        }
+      }
+    }
+  }
+}

packages/@aws-cdk/cloudformation-include/test/test-templates/fn-sub-parameters.json

@@ -0,0 +1,22 @@
+{
+  "Parameters": {
+    "MyParam": {
+      "Type": "String"
+    }
+  },
+  "Resources": {
+    "Bucket": {
+      "Type": "AWS::S3::Bucket",
+      "Properties": {
+        "BucketName": { 
+          "Fn::Sub": [ 
+            "${MyParameter}-${MyParam}", 
+            { 
+              "MyParameter": { "Ref" : "MyParam" }
+            } 
+          ]
+        }
+      }
+    }
+  }
+}

packages/@aws-cdk/cloudformation-include/test/test-templates/parameter-references.json

@@ -0,0 +1,54 @@
+{
+  "Transform" : {
+    "Name" : "AWS::Include",
+    "Parameters" : {
+      "Location" : {
+        "Ref": "MyParam"
+      }
+    }
+  },
+  "Parameters": {
+    "MyParam": {
+      "Type": "String",
+      "Default": "MyValue"
+    }
+  },
+  "Conditions": {
+    "AlwaysFalse": {
+      "Fn::Equals": [ { "Ref": "MyParam" }, "Invalid?BucketName"]
+    }
+  },
+  "Metadata": {
+    "Field": {
+      "Fn::If": [
+        "AlwaysFalse",
+        "AWS::NoValue",
+        {
+          "Ref": "MyParam"
+        }
+      ]
+    }
+  },
+  "Resources": {
+    "Bucket": {
+      "Type": "AWS::S3::Bucket",
+      "Metadata": {
+        "Field": {
+          "Ref": "MyParam"
+        }
+      },
+      "Properties": {
+        "BucketName": {
+          "Ref": "MyParam"
+        }
+      }
+    }
+  },
+  "Outputs": {
+    "MyOutput": {
+      "Value": {
+        "Ref": "MyParam"
+      }
+    }
+  }
+}