Skip to content

Commit

Permalink
chore(cfn-include): correct the link to CFN docs about Parameters (#9420
Browse files Browse the repository at this point in the history
)

The Markdown had a space between the `[]` and the `()`, which meant it wasn't rendered as a proper link when transforming to HTML.

----

*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 authored Aug 3, 2020
1 parent 072bb66 commit b1b9d23
Showing 1 changed file with 23 additions and 20 deletions.
43 changes: 23 additions & 20 deletions packages/@aws-cdk/cloudformation-include/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,12 @@
This module contains a set of classes whose goal is to facilitate working
with existing CloudFormation templates in the CDK.
It can be thought of as an extension of the capabilities of the
[`CfnInclude` class](../@aws-cdk/core/lib/cfn-include.ts).
[`CfnInclude` class](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_core.CfnInclude.html).

## Basic usage

Assume we have a file with an existing template. It could be in JSON format, in a file `my-template.json`:
Assume we have a file with an existing template.
It could be in JSON format, in a file `my-template.json`:

```json
{
Expand Down Expand Up @@ -52,15 +53,15 @@ const cfnTemplate = new cfn_inc.CfnInclude(this, 'Template', {
});
```

Or, if our template is YAML, we can use
Or, if your template uses YAML:

```typescript
const cfnTemplate = new cfn_inc.CfnInclude(this, 'Template', {
templateFile: 'my-template.yaml',
});
```

This will add all resources from `my-template.json` into the CDK application,
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.

Any resource from the included template can be retrieved by referring to it by its logical ID from the template.
Expand All @@ -74,6 +75,12 @@ const cfnBucket = cfnTemplate.getResource('Bucket') as s3.CfnBucket;
// cfnBucket is of type s3.CfnBucket
```

Note that any resources not present in the latest version of the CloudFormation schema
at the time of publishing the version of this module that you depend on,
including [Custom Resources](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cfn-customresource.html),
will be returned as instances of the class `CfnResource`,
and so cannot be cast to a different resource type.

Any modifications made to that resource will be reflected in the resulting CDK template;
for example, the name of the bucket can be changed:

Expand All @@ -99,20 +106,16 @@ role.addToPolicy(new iam.PolicyStatement({
```

If you need, you can also convert the CloudFormation resource to a higher-level
resource by importing it by its name:
resource by importing it:

```typescript
const bucket = s3.Bucket.fromBucketName(this, 'L2Bucket', cfnBucket.ref);
// bucket is of type s3.IBucket
```

Note that [Custom Resources](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cfn-customresource.html)
will be of type CfnResource, and hence won't need to be casted.
This holds for any resource that isn't in the CloudFormation schema.

## Parameters

If your template uses [CloudFormation Parameters] (https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html),
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
Expand Down Expand Up @@ -176,14 +179,14 @@ For example, if you have the following parent template:
"ChildStack": {
"Type": "AWS::CloudFormation::Stack",
"Properties": {
"TemplateURL": "https://my-s3-template-source.s3.amazonaws.com/child-import-stack.json"
"TemplateURL": "https://my-s3-template-source.s3.amazonaws.com/child-stack.json"
}
}
}
}
```

where the child template pointed to by `https://my-s3-template-source.s3.amazonaws.com/child-import-stack.json` is:
where the child template pointed to by `https://my-s3-template-source.s3.amazonaws.com/child-stack.json` is:

```json
{
Expand All @@ -195,7 +198,7 @@ where the child template pointed to by `https://my-s3-template-source.s3.amazona
}
```

You can include both the parent stack and the nested stack in your CDK Application as follows:
You can include both the parent stack and the nested stack in your CDK application as follows:

```typescript
const parentTemplate = new inc.CfnInclude(stack, 'ParentStack', {
Expand All @@ -208,30 +211,30 @@ const parentTemplate = new inc.CfnInclude(stack, 'ParentStack', {
});
```

Now you can access the ChildStack nested stack and included template with:
The included nested stack can be accessed with the `getNestedStack` method:

```typescript
const includedChildStack = parentTemplate.getNestedStack('ChildStack');
const childStack: core.NestedStack = includedChildStack.stack;
const childStackTemplate: cfn_inc.CfnInclude = includedChildStack.includedTemplate;
const childTemplate: cfn_inc.CfnInclude = includedChildStack.includedTemplate;
```

Now you can reference resources from `ChildStack` and modify them like any other included template:

```typescript
const bucket = childStackTemplate.getResource('MyBucket') as s3.CfnBucket;
bucket.bucketName = 'my-new-bucket-name';
const cfnBucket = childTemplate.getResource('MyBucket') as s3.CfnBucket;
cfnBucket.bucketName = 'my-new-bucket-name';

const bucketReadRole = new iam.Role(childStack, 'MyRole', {
const role = new iam.Role(childStack, 'MyRole', {
assumedBy: new iam.AccountRootPrincipal(),
});

bucketReadRole.addToPolicy(new iam.PolicyStatement({
role.addToPolicy(new iam.PolicyStatement({
actions: [
's3:GetObject*',
's3:GetBucket*',
's3:List*',
],
resources: [bucket.attrArn],
resources: [cfnBucket.attrArn],
}));
```

0 comments on commit b1b9d23

Please sign in to comment.