AWS::Include
transform
Use the AWS::Include
transform, which is a macro hosted by
AWS CloudFormation, to insert boilerplate content into your templates. The AWS::Include
transform lets you create a reference to a template snippet in an Amazon S3
bucket. When Creating a change set or Updating stacks using change sets, and the templates reference AWS::Include
, AWS CloudFormation inserts the contents of the specified file at
the location of the transform in the template. The AWS::Include
function behaves similarly to an include
, copy
, or import
directive in
programming languages.
For example, you might have a Lambda function that you want to reuse in one or more AWS CloudFormation templates.
Usage
You can use the AWS::Include
transform anywhere within the
AWS CloudFormation template except in the template parameters section or the template version field. For
example, you can use AWS::Include
in the mappings
section.
Syntax at the top level of a template
To include the AWS::Include
transform at the top level of a template, in the Transform
section, use the following syntax.
JSON
{ "Transform" : { "Name" : "AWS::Include", "Parameters" : { "Location" : "s3://
DOC-EXAMPLE-BUCKET
/MyFileName
.json" } } }
YAML
Transform: Name: 'AWS::Include' Parameters: Location: 's3://
DOC-EXAMPLE-BUCKET
/MyFileName.yaml
'
Syntax when the transform is embedded within a section of a template
To include a transform that's embedded within a section, use the Fn::Transform
intrinsic function and
the following syntax.
JSON
{ "Fn::Transform" : { "Name" : "AWS::Include", "Parameters" : { "Location": "s3://
DOC-EXAMPLE-BUCKET
/MyFileName.json
" } } }
YAML
'Fn::Transform': Name: 'AWS::Include' Parameters: Location: s3://
DOC-EXAMPLE-BUCKET
/MyFileName.yaml
Parameters
Location
The location is an Amazon S3 URI, with a specific file name in an S3 bucket. For example,
s3://MyBucketName/MyFile.yaml
.
Remarks
When using AWS::Include
, keep the following considerations
in mind. For general considerations about using macros, see Considerations when creating AWS CloudFormation macro
definitions
We currently support Amazon S3 URI, but no other Amazon S3 format (such as Amazon S3 ARN). It must be an Amazon S3 bucket, as opposed to something like a GitHub repository.
Anyone with access to the Amazon S3 URL can include the snippet in their template.
Your template snippets must be valid YAML or JSON.
Your template snippets must be valid key– objects, for example
"KeyName": "keyValue"
.You can't use
AWS::Include
to reference a template snippet that also usesAWS::Include
.If your snippets change, your stack doesn't automatically pick up those changes. To get those changes, you must update the stack with the updated snippets. If you update your stack, make sure your included snippets haven't changed without your knowledge. To verify before updating the stack, check the change set.
When creating templates and snippets, you can mix YAML and JSON template languages.
We don't currently support using shorthand notations for YAML snippets.
You can provide a cross-region replication Amazon S3 URI with
AWS::Include
. Make sure you check Amazon S3 bucket names when accessing cross-region replication objects. For more information, see Cross-Region replication.
Example
The following example shows how to use the AWS::Include
transform to execute a wait condition handle.
Both the JSON and the YAML versions use the following wait condition snippet. Save the
file as single_wait_condition.yaml
, and store it in an S3 bucket with the
same name as DOC-EXAMPLE-BUCKET
.
WebServerWaitHandle: Type: 'AWS::CloudFormation::WaitConditionHandle'
JSON
{ "Resources": { "MyWaitHandle": { "Type": "AWS::CloudFormation::WaitConditionHandle" }, "Fn::Transform": { "Name": "AWS::Include", "Parameters": { "Location": "s3://
DOC-EXAMPLE-BUCKET
/single_wait_condition.yaml" } } } }
YAML
Resources: MyWaitHandle: Type: 'AWS::CloudFormation::WaitConditionHandle' 'Fn::Transform': Name: 'AWS::Include' Parameters: Location: "s3://
DOC-EXAMPLE-BUCKET
/single_wait_condition.yaml"