From 4925e064f341cd46d389e9d643c058484027af8e Mon Sep 17 00:00:00 2001 From: Adam Ruka Date: Fri, 11 Sep 2020 21:03:31 -0700 Subject: [PATCH] chore(cfn-include): updates to the ReadMe (#10315) As discussed during our @aws-cdk/cloudformation-include API review. ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license* --- .../@aws-cdk/cloudformation-include/README.md | 216 +++++++++--------- 1 file changed, 102 insertions(+), 114 deletions(-) diff --git a/packages/@aws-cdk/cloudformation-include/README.md b/packages/@aws-cdk/cloudformation-include/README.md index 09f87f4b0d27e..52da55a585b02 100644 --- a/packages/@aws-cdk/cloudformation-include/README.md +++ b/packages/@aws-cdk/cloudformation-include/README.md @@ -61,9 +61,22 @@ const cfnTemplate = new cfn_inc.CfnInclude(this, 'Template', { }); ``` +**Note**: different YAML parsers sometimes don't agree on what exactly constitutes valid YAML. +If you get a YAML exception when including your template, +try converting it to JSON, and including that file instead. +If you're downloading your template from the CloudFormation AWS Console, +you can easily get it in JSON format by clicking the 'View in Designer' +button on the 'Template' tab - +once in Designer, select JSON in the "Choose template language" +radio buttons on the bottom pane. + This will add all resources from `my-template.json` / `my-template.yaml` into the CDK application, preserving their original logical IDs from the template file. +Note that this including process will _not_ execute any +[CloudFormation transforms](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-macros.html) - +including the [Serverless transform](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/transform-aws-serverless.html). + Any resource from the included template can be retrieved by referring to it by its logical ID from the template. If you know the class of the CDK object that corresponds to that resource, you can cast the returned object to the correct type: @@ -113,25 +126,84 @@ const bucket = s3.Bucket.fromBucketName(this, 'L2Bucket', cfnBucket.ref); // bucket is of type s3.IBucket ``` -## Parameters - -If your template uses [CloudFormation Parameters](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html), -you can retrieve them from your template: - -```typescript -import * as core from '@aws-cdk/core'; - -const param: core.CfnParameter = cfnTemplate.getParameter('MyParameter'); -``` - -The `CfnParameter` object is mutable, -and any changes you make to it will be reflected in the resulting template: - -```typescript -param.default = 'MyDefault'; -``` - -You can also provide values for them when including the template: +## Non-resource template elements + +In addition to resources, +you can also retrieve and mutate all other template elements: + +* [Parameters](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html): + + ```typescript + import * as core from '@aws-cdk/core'; + + const param: core.CfnParameter = cfnTemplate.getParameter('MyParameter'); + + // mutating the parameter + param.default = 'MyDefault'; + ``` + +* [Conditions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/conditions-section-structure.html): + + ```typescript + import * as core from '@aws-cdk/core'; + + const condition: core.CfnCondition = cfnTemplate.getCondition('MyCondition'); + + // mutating the condition + condition.expression = core.Fn.conditionEquals(1, 2); + ``` + +* [Mappings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/mappings-section-structure.html): + + ```typescript + import * as core from '@aws-cdk/core'; + + const mapping: core.CfnMapping = cfnTemplate.getMapping('MyMapping'); + + // mutating the mapping + mapping.setValue('my-region', 'AMI', 'ami-04681a1dbd79675a5'); + ``` + +* [Service Catalog template Rules](https://docs.aws.amazon.com/servicecatalog/latest/adminguide/reference-template_constraint_rules.html): + + ```typescript + import * as core from '@aws-cdk/core'; + + const rule: core.CfnRule = cfnTemplate.getRule('MyRule'); + + // mutating the rule + rule.addAssertion(core.Fn.conditionContains(['m1.small'], myParameter.value), + 'MyParameter has to be m1.small'); + ``` + +* [Outputs](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html): + + ```typescript + import * as core from '@aws-cdk/core'; + + const output: core.CfnOutput = cfnTemplate.getOutput('MyOutput'); + + // mutating the output + output.value = cfnBucket.attrArn; + ``` + +* [Hooks for blue-green deployments](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/blue-green.html): + + ```typescript + import * as core from '@aws-cdk/core'; + + const hook: core.CfnHook = cfnTemplate.getHook('MyOutput'); + + // mutating the hook + const codeDeployHook = hook as core.CfnCodeDeployBlueGreenHook; + codeDeployHook.serviceRole = myRole.roleArn; + ``` + +## Parameter replacement + +If your existing template uses CloudFormation Parameters, +you may want to remove them in favor of build-time values. +You can do that using the `parameters` property: ```typescript new inc.CfnInclude(this, 'includeTemplate', { @@ -142,104 +214,12 @@ new inc.CfnInclude(this, 'includeTemplate', { }); ``` -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), -you can retrieve them from your template: - -```typescript -import * as core from '@aws-cdk/core'; - -const condition: core.CfnCondition = cfnTemplate.getCondition('MyCondition'); -``` - -The `CfnCondition` object is mutable, -and any changes you make to it will be reflected in the resulting template: - -```typescript -condition.expression = core.Fn.conditionEquals(1, 2); -``` - -## Mappings - -If your template uses [CloudFormation Mappings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/mappings-section-structure.html), -you can retrieve them from your template: - -```typescript -import * as core from '@aws-cdk/core'; - -const mapping: core.CfnMapping = cfnTemplate.getMapping('MyMapping'); -``` - -The `CfnMapping` object is mutable, -and any changes you make to it will be reflected in the resulting template: - -```typescript -mapping.setValue('my-region', 'AMI', 'ami-04681a1dbd79675a5'); -``` - -## Rules - -If your template uses [Service Catalog template Rules](https://docs.aws.amazon.com/servicecatalog/latest/adminguide/reference-template_constraint_rules.html), -you can retrieve them from your template: - -```typescript -import * as core from '@aws-cdk/core'; - -const rule: core.CfnRule = cfnTemplate.getRule('MyRule'); -``` - -The `CfnRule` object is mutable, -and any changes you make to it will be reflected in the resulting template: - -```typescript -rule.addAssertion(core.Fn.conditionContains(['m1.small'], myParameter.value), - 'MyParameter has to be m1.small'); -``` - -## Outputs - -If your template uses [CloudFormation Outputs](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html), -you can retrieve them from your template: - -```typescript -import * as core from '@aws-cdk/core'; - -const output: core.CfnOutput = cfnTemplate.getOutput('MyOutput'); -``` - -The `CfnOutput` object is mutable, -and any changes you make to it will be reflected in the resulting template: - -```typescript -output.value = cfnBucket.attrArn; -``` - -## Hooks - -If your template uses [Hooks for blue-green deployments](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/blue-green.html), -you can retrieve them from your template: - -```typescript -import * as core from '@aws-cdk/core'; - -const hook: core.CfnHook = cfnTemplate.getHook('MyOutput'); -``` - -The `CfnHook` object can be mutated, -and any changes you make to it will be reflected in the resulting template: - -```typescript -const codeDeployHook = hook as core.CfnCodeDeployBlueGreenHook; -codeDeployHook.serviceRole = myRole.roleArn; -``` +This will replace all references to `MyParam` with the string `'my-value'`, +and `MyParam` will be removed from the 'Parameters' section of the template. ## Nested Stacks -This module also support templates that use [nested stacks](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-nested-stacks.html). +This module also supports templates that use [nested stacks](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-nested-stacks.html). For example, if you have the following parent template: @@ -282,6 +262,14 @@ const parentTemplate = new inc.CfnInclude(this, 'ParentStack', { }); ``` +Here, `path/to/my-nested-template.json` +represents the path on disk to the downloaded template file from the original template URL of the nested stack +(`https://my-s3-template-source.s3.amazonaws.com/child-stack.json`). +In the CDK application, +this file will be turned into an [Asset](https://docs.aws.amazon.com/cdk/latest/guide/assets.html), +and the `TemplateURL` property of the nested stack resource +will be modified to point to that asset. + The included nested stack can be accessed with the `getNestedStack` method: ```typescript