Skip to content

Commit

Permalink
chore(cfn-include): updates to the ReadMe (#10315)
Browse files Browse the repository at this point in the history 
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*
  • Loading branch information
@skinny85
skinny85 committed Sep 12, 2020
1 parent 65db131 commit 4925e06
Showing 1 changed file with 102 additions and 114 deletions.
216 changes: 102 additions & 114 deletions packages/@aws-cdk/cloudformation-include/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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', {
Expand All @@ -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:

Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 4925e06

Please sign in to comment.