Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(cfn-include): correct the link to CFN docs about Parameters #9420

Merged
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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],
}));
```