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.

Unlike custom macros, the AWS::Include transform doesn't require special permissions to use it because it is hosted by AWS CloudFormation. It can be used by templates in any account within AWS CloudFormation. Also, there is no charge incurred when using this transform. AWS CloudFormation treats the AWS::Include transform the same as any other macro in terms of evaluation order and scope. For more information about macros, see Using AWS CloudFormation Macros to Perform Custom Processing on 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.

{
   "Transform" : {
       "Name" : "AWS::Include",
       "Parameters" : {
           "Location" : "s3://MyAmazonS3BucketName/MyFileName.json"
        }
    }
}

Transform:
  Name: 'AWS::Include'
  Parameters:
    Location: 's3://MyAmazonS3BucketName/MyFileName.yaml'

Syntax When the Transform Is Embedded Within a Section of a Template

To include a transform that is embedded within a section, use the Fn::Transform intrinsic function and the following syntax.

{
   "Fn::Transform" : {
       "Name" : "AWS::Include",
       "Parameters" : {
           "Location" : "s3://MyAmazonS3BucketName/MyFileName.json"
        }
    }
}

'Fn::Transform':
  Name: 'AWS::Include'
  Parameters:
    Location: s3://MyAmazonS3BucketName/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

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 MyAmazonS3BucketName.

WebServerWaitHandle:
  Type: 'AWS::CloudFormation::WaitConditionHandle'

{
   "Resources": {
      "MyWaitHandle": {
         "Type": "AWS::CloudFormation::WaitConditionHandle"
      },
      "Fn::Transform": {
         "Name": "AWS::Include",
         "Parameters": {
            "Location": "s3://MyAmazonS3BucketName/single_wait_condition.yaml"
         }
      }
   }
}

Resources:
  MyWaitHandle:
    Type: 'AWS::CloudFormation::WaitConditionHandle'
  'Fn::Transform':
    Name: 'AWS::Include'
    Parameters:
      Location : "s3://MyAmazonS3BucketName/single_wait_condition.yaml"

On this page:

• Usage
• Parameters
• Remarks
• Example