AWS::Include transform - AWS CloudFormation
UsageParametersRemarksExample

AWS::Include transform

Use the AWS::Include transform, which is a macro hosted by 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, 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 CloudFormation templates.

Usage

You can use the AWS::Include transform anywhere within the 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://amzn-s3-demo-bucket/MyFileName.json"
        }
    }
}

YAML

Transform:
  Name: 'AWS::Include'
  Parameters:
    Location: 's3://amzn-s3-demo-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://amzn-s3-demo-bucket/MyFileName.json"
        }
    }
}

YAML

'Fn::Transform':
  Name: 'AWS::Include'
  Parameters:
    Location: s3://amzn-s3-demo-bucket/MyFileName.yaml

Parameters

Location

The location is an Amazon S3 URI, with a specific file name in an S3 bucket. For example, s3://amzn-s3-demo-bucket/MyFile.yaml.

Remarks

When using AWS::Include, keep the following considerations in mind. For general considerations about using macros, see Considerations.

  • 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 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 uses AWS::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 Replicating objects within and across Regions in the Amazon S3 User Guide.

Example

The following examples show how to use the AWS::Include transform to execute a wait condition handle. Replace amzn-s3-demo-bucket with your actual bucket name. In your S3 bucket, save a YAML file named single_wait_condition.yaml with the following contents:

MyWaitCondition:
  Type: AWS::CloudFormation::WaitCondition
  Properties:
    Handle: !Ref MyWaitHandle
    Timeout: '4500'

JSON

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

YAML

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

For more information, see Create wait conditions in a CloudFormation template.