# Perform custom processing on CloudFormation templates with template macros
With macros, you can perform custom processing on templates, from simple actions like find-and-replace operations to extensive transformations of entire templates.
To get an idea of the breadth of possibilities, consider the `AWS::Include` and `AWS::Serverless` transforms, which are macros hosted by CloudFormation:
+ [AWS::Include transform](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/transform-aws-include.html) enables you to insert boilerplate template snippets into your templates.
+ [AWS::Serverless transform](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/transform-aws-serverless.html) takes an entire template written in the AWS Serverless Application Model (AWS SAM) syntax and transforms and expands it into a compliant CloudFormation template. For more information about serverless applications and AWS SAM, see [AWS Serverless Application Model Developer Guide](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/what-is-sam.html).
**Topics**
+ [Billing](#template-macros-billing)
+ [Macro examples](#template-macros-examples-list)
+ [Related resources](#template-macros-related-resources)
+ [Overview of CloudFormation macros](template-macros-overview.md)
+ [Create a CloudFormation macro definition](template-macros-author.md)
+ [Example simple string replacement macro](macros-example.md)
+ [Troubleshoot the processed template](template-macros-troubleshoot-processed-template.md)
## Billing
When a macro runs, the owner of the Lambda function is billed for any charges related to the execution of that function.
The `AWS::Include` and `AWS::Serverless` transforms are macros hosted by CloudFormation. There is no charge for using them.
## Macro examples
In addition to the examples in this section, you can find example macros, including source code and templates, in our [GitHub repository](https://github.com/aws-cloudformation/aws-cloudformation-templates/tree/main/CloudFormation/MacrosExamples). These examples are provided 'as-is' for instructional purposes.
## Related resources
+ [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-cloudformation-macro.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-cloudformation-macro.html)
+ [CloudFormation template Transform section](transform-section-structure.md)
+ [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-transform.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-transform.html)
+ [AWS::Serverless transform](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/transform-aws-serverless.html)
+ [AWS::Include transform](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/transform-aws-include.html)
# Overview of CloudFormation macros
There are two major steps to processing templates using macros: creating the macro itself, and then using the macro to perform processing on your templates.
To create a macro definition, you must create the following:
+ A Lambda function to perform the template processing. This Lambda function accepts either a snippet or an entire template, and any additional parameters that you define. It returns the processed template snippet or the entire template as a response.
+ A resource of type [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-cloudformation-macro.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-cloudformation-macro.html), which enables users to call the Lambda function from within CloudFormation templates. This resource specifies the ARN of the Lambda function to invoke for this macro, and additional optional properties to assist with debugging. To create this resource within an account, author a template that includes the `AWS::CloudFormation::Macro` resource, and then create either a stack or stack set with self-managed permissions from the template. CloudFormation StackSets doesn't currently support creating or updating stack sets with service-managed permissions from templates that reference macros.
To use a macro, reference the macro in your template:
+ To process a section, or part, of a template, reference the macro in an `Fn::Transform` function located relative to the template content you want to transform. When using `Fn::Transform`, you can also pass any specified parameters it requires.
+ To process an entire template, reference the macro in the [Transform](transform-section-structure.md) section of the template.
Next, you typically create a change set and then execute it. (Processing macros can add multiple resources that you might not be aware of. To ensure that you're aware of all of the changes introduced by macros, we strongly advise that you use change sets.) CloudFormation passes the specified template content, along with any additional specified parameters, to the Lambda function specified in the macro resource. The Lambda function returns the processed template content, be it a snippet or an entire template.
After all macros in the template have been called, CloudFormation generates a change set that includes the processed template content. After you review the change set, execute it to apply the changes.
![\[Use the Fn::Transform intrinsic function or the Transform section of the template, to pass the template contents and associated parameters to the macro's underlying Lambda function, which returns the processed template contents.\]](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/images/template-macro-use.png)
## How to create stacks directly
To create or update a stack using a template that references macros, you typically create a change set and then execute it. A change set describes the actions CloudFormation will take based on the processed template. Processing macros can add multiple resources that you might not be aware of. To ensure that you're aware of all the changes introduced by macros, we strongly suggest you use change sets. After you review the change set, you can execute it to actually apply the changes.
A macro can add IAM resources to your template. For these resources, CloudFormation requires you to [acknowledge their capabilities](control-access-with-iam.md#using-iam-capabilities). Because CloudFormation can't know which resources are added before processing your template, you might need to acknowledge IAM capabilities when you create the change set, depending on whether the referenced macros contain IAM resources. That way, when you run the change set, CloudFormation has the necessary capabilities to create IAM resources.
To create or update a stack directly from a processed template without first reviewing the proposed changes in a change set, specify the `CAPABILITY_AUTO_EXPAND` capability during a `CreateStack` or `UpdateStack` request. You should only create stacks directly from a stack template that contains macros if you know what processing the macro performs. You can't use change sets with stack set macros; you must update your stack set directly.
For more information, see [https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html) or [https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_UpdateStack.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_UpdateStack.html) in the *AWS CloudFormation API Reference*.
**Important**
If your stack set template references one or more macros, you must create the stack set directly from the processed template, without first reviewing the resulting changes in a change set. Processing macros can add multiple resources that you might not be aware of. Before you create or update a stack set from a template that references macros directly, be sure that you know what processing the macros performs.
To reduce the number of steps for launching stacks from templates that reference macros, you can use the `package` and `deploy` AWS CLI commands. For more information, see [Upload local artifacts to an S3 bucket with the AWS CLI](using-cfn-cli-package.md) and [Create a stack that includes transforms](service_code_examples.md#deploy-sdk).
## Considerations
When working with macros, keep in mind the following notes and limitations:
+ Macros are supported only in AWS Regions where Lambda is available. For a list of Regions where Lambda is available, see [AWS Lambda endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/lambda-service.html).
+ Any processed template snippets must be valid JSON.
+ Any processed template snippets must pass validation checks for a create stack, update stack, create stack set, or update stack set operation.
+ CloudFormation resolves macros first, and then processes the template. The resulting template must be valid JSON and must not exceed the template size limit.
+ Because of the order in which CloudFormation processes elements in a template, a macro can't include modules in the processed template content it returns to CloudFormation. For more information, see [Macro evaluation order](template-macros-author.md#template-macros-order).
+ When using the update rollback feature, CloudFormation uses a copy of the original template. It rolls back to the original template even if the included snippet was changed.
+ Including macros within macros doesn't work because we don't process macros recursively.
+ The `Fn::ImportValue` intrinsic function isn't currently supported in macros.
+ Intrinsic functions included in the template are evaluated after any macros. Therefore, the processed template content your macro returns can include calls to intrinsic functions, and they're evaluated as usual.
+ StackSets doesn't currently support creating or updating stack sets with service-managed permissions from templates that reference CloudFormation macros.
## Macro account scope and permissions
You can use macros only in the account in which they were created as a resource. The name of the macro must be unique within a given account. However, you can make the same functionality available in multiple accounts by enabling cross-account access on the underlying Lambda function, and then creating macro definitions referencing that function in multiple accounts. In the example below, three accounts contain macro definitions that each point to the same Lambda function.
![\[By allowing cross-account access on the Lambda function, AWS enables you to create macros in multiple accounts that reference that function.\]](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/images/template-macro-accounts.png)
To create a macro definition, the user must have permissions to create a stack or stack set within the specified account.
For CloudFormation to successfully run a macro included in a template, the user must have `Invoke` permissions for the underlying Lambda function. To prevent potential escalation of permissions, CloudFormation impersonates the user while running the macro.
For more information, see [Managing permissions in AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/lambda-permissions.html) in the *AWS Lambda Developer Guide* and [Actions, resources, and condition keys for AWS Lambda](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awslambda.html) in the *Service Authorization Reference*.
# Create a CloudFormation macro definition
When you create a macro definition, the macro definition makes the underlying Lambda function available in the specified account so that CloudFormation invokes it to process the templates.
## Event mapping
When CloudFormation invokes a macro's Lambda function, it sends a request in JSON format with the following structure:
```
{
"region" : "us-east-1",
"accountId" : "$ACCOUNT_ID",
"fragment" : { ... },
"transformId" : "$TRANSFORM_ID",
"params" : { ... },
"requestId" : "$REQUEST_ID",
"templateParameterValues" : { ... }
}
```
+ `region`
The Region in which the macro resides.
+ `accountId`
The account ID of the account from which the macro is invoking the Lambda function.
+ `fragment`
The template content available for custom processing, in JSON format.
+ For macros included in the `Transform` template section, this is the entire template except for the `Transform` section.
+ For macros included in an `Fn::Transform` intrinsic function call, this includes all sibling nodes (and their children) based on the location of the intrinsic function within the template except for the `Fn::Transform` function. For more information, see [Macro template scope](#template-macros-scope).
+ `transformId`
The name of the macro invoking this function.
+ `params`
For `Fn::Transform` function calls, any specified parameters for the function. CloudFormation doesn't evaluate these parameters before passing them to the function.
For macros included in the `Transform` template section, this section is empty.
+ `requestId`
The ID of the request invoking this function.
+ `templateParameterValues`
Any parameters specified in the [Parameters](parameters-section-structure.md) section of the template. CloudFormation evaluates these parameters before passing them to the function.
## Response format
CloudFormation expects the Lambda function to return a response in the following JSON format:
```
{
"requestId" : "$REQUEST_ID",
"status" : "$STATUS",
"fragment" : { ... },
"errorMessage": "optional error message for failures"
}
```
+ `requestId`
The ID of the request invoking this function. This must match the request ID provided by CloudFormation when invoking the function.
+ `status`
The status of the request (case-insensitive). Should be set to `success`. CloudFormation treats any other response as a failure.
+ `fragment`
The processed template content for CloudFormation to include in the processed template, including siblings. CloudFormation replaces the template content that is passed to the Lambda function with the template fragment it receives in the Lambda response.
The processed template content must be valid JSON, and its inclusion in the processed template must result in a valid template.
If your function doesn't actually change the template content that CloudFormation passes to it, but you still need to include that content in the processed template, your function needs to return that template content to CloudFormation in its response.
+ `errorMessage`
The error message that explains why the transform failed. CloudFormation displays this error message in the **Events** pane of the **Stack details** page for your stack.
For example:
```
Error creating change set: Transform
AWS account account
number::macro name failed with:
error message string.
```
## Create a macro definition
**To create a CloudFormation macro definition**
1. [Build a Lambda function](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html) that will handle the processing of template contents. It can process any part of a template, up to the entire template.
1. Create a CloudFormation template containing an `AWS::CloudFormation::Macro` resource type and specify the `Name` and `FunctionName` properties. The `FunctionName` property must contain the ARN of the Lambda function to invoke when CloudFormation runs the macro.
1. (Optional) To aid in debugging, you can also specify the `LogGroupName` and `LogRoleArn` properties when creating the `AWS::CloudFormation::Macro` resource type for your macro. These properties enable you to specify the CloudWatch Logs log group to which CloudFormation sends error logging information when invoking the macro's underlying Lambda function, and the role CloudFormation should assume when sending log entries to those logs.
1. [Create a stack](cfn-console-create-stack.md) using the template with the macro in the account you want to use it in. Or, [create a stack set with self-managed permissions](stacksets-getting-started-create-self-managed.md) using the template with the macro in the administrator account, and then create stack instances in the target accounts.
1. After CloudFormation has successfully created the stacks that contain the macro definition, the macro is available for use within those accounts. You use a macro by referencing it in a template, at the appropriate location relevant to the template contents you want to process.
## Macro template scope
Macros referenced in the `Transform` section of a template can process the entire contents of that template.
Macros referenced in an `Fn::Transform` function can process the contents of any of the sibling elements (including children) of that `Fn::Transform` function in the template.
For example, in the template sample below, `AWS::Include` can process the `MyBucket` properties, based on the location of the `Fn::Transform` function that contains it. `MyMacro` can process the contents of the entire template because of its inclusion in the `Transform` section.
```
# Start of processable content for MyMacro
AWSTemplateFormatVersion: 2010-09-09
Transform: [MyMacro]
Resources:
WaitCondition:
Type: AWS::CloudFormation::WaitCondition
MyBucket:
Type: AWS::S3::Bucket
# Start of processable content for AWS::Include
Properties:
BucketName: amzn-s3-demo-bucket1
Tags: [{"key":"value"}]
'Fn::Transform':
- Name: 'AWS::Include'
Parameters:
Location: s3://amzn-s3-demo-bucket2/MyFileName.yaml
CorsConfiguration: []
# End of processable content for AWS::Include
MyEc2Instance:
Type: AWS::EC2::Instance
Properties:
ImageID: ami-1234567890abcdef0
# End of processable content for MyMacro
```
## Macro evaluation order
You can reference multiple macros in a given template, including transforms hosted by CloudFormation, such as [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/transform-aws-include.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/transform-aws-include.html) and [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/transform-aws-serverless.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/transform-aws-serverless.html).
Macros are evaluated in order, based on their location in the template, from the most deeply nested outward to the most general. Macros at the same location in the template are evaluated serially based on the order in which they're listed.
Transforms such as `AWS::Include` and `AWS::Transform` are treated the same as any other macros in terms of action order and scope.
For example, in the template sample below, CloudFormation evaluates the `PolicyAdder` macro first, because it's the most deeply-nested macro in the template. CloudFormation then evaluates `MyMacro` before evaluating `AWS::Serverless` because it's listed before `AWS::Serverless` in the `Transform` section.
```
AWSTemplateFormatVersion: 2010-09-09
Transform: [MyMacro, AWS::Serverless]
Resources:
WaitCondition:
Type: AWS::CloudFormation::WaitCondition
MyBucket:
Type: AWS::S3::Bucket
Properties:
BucketName: amzn-s3-demo-bucket
Tags: [{"key":"value"}]
'Fn::Transform':
- Name: PolicyAdder
CorsConfiguration: []
MyEc2Instance:
Type: AWS::EC2::Instance
Properties:
ImageID: ami-1234567890abcdef0
```
# Example simple string replacement macro
The following example walks you through the process of using macros, from defining the macro in a template, to creating a Lambda function for the macro, and then to using the macro in a template.
In this example, we create a simple macro that inserts the specified string in place of the specified target content in the processed template. And then we'll use it to insert a blank `WaitHandleCondition` in the specified location in the processed template.
## Creating a macro
Before using a macro, we first have to complete two things: create the Lambda function that performs the desired template processing, and then make that Lambda function available to CloudFormation by creating a macro definition.
The following sample template contains the definition for our example macro. To make the macro available in a specific AWS account, create a stack from the template. The macro definition specifies the macro name, a brief description, and references the ARN of the Lambda function that CloudFormation invokes when this macro is used in a template. (We haven't included a `LogGroupName` or `LogRoleARN` property for error logging.)
In this example, assume that the stack created from this template is named `JavaMacroFunc`. Because the macro `Name` property is set to the stack name, the resulting macro is named `JavaMacroFunc` as well.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Macro:
Type: AWS::CloudFormation::Macro
Properties:
Name: !Sub '${AWS::StackName}'
Description: Adds a blank WaitConditionHandle named WaitHandle
FunctionName: 'arn:aws:lambda:us-east-1:012345678910:function:JavaMacroFunc'
```
## Using the macro
To use our macro, we include it in a template using the `Fn::Transform` intrinsic function.
When we create a stack using the template below, CloudFormation calls our example macro. The underlying Lambda function replaces one specified string with another specified string. In this case, the result is a blank `AWS::CloudFormation::WaitConditionHandle` is inserted into the processed template.
```
Parameters:
ExampleParameter:
Type: String
Default: 'SampleMacro'
Resources:
2a:
Fn::Transform:
Name: "JavaMacroFunc"
Parameters:
replacement: 'AWS::CloudFormation::WaitConditionHandle'
target: '$$REPLACEMENT$$'
Type: '$$REPLACEMENT$$'
```
+ The macro to invoke is specified as `JavaMacroFunc`, which is from the previous macro definition example.
+ The macro is passed two parameters, `target` and `replacement`, which represent the target string and its desired replacement value.
+ The macro can operate on the contents of the `Type` node because `Type` is a sibling of the `Fn::Transform` function referencing the macro.
+ The resulting `AWS::CloudFormation::WaitConditionHandle` is named `2a`.
+ The template also contains a template parameter, `ExampleParameter`, which the macro also has access to (but doesn't use in this case).
## Lambda input data
When CloudFormation processes our example template during stack creation, it passes the following event mapping to the Lambda function referenced in the `JavaMacroFunc` macro definition.
+ `region` : `us-east-1`
+ `accountId` : `012345678910`
+ `fragment` :
```
{
"Type": "$$REPLACEMENT$$"
}
```
+ `transformId` : `012345678910::JavaMacroFunc`
+ `params` :
```
{
"replacement": "AWS::CloudFormation::WaitConditionHandle",
"target": "$$REPLACEMENT$$"
}
```
+ `requestId` : `5dba79b5-f117-4de0-9ce4-d40363bfb6ab`
+ `templateParameterValues` :
```
{
"ExampleParameter": "SampleMacro"
}
```
`fragment` contains JSON representing the template fragment that the macro can process. This fragment consists of the siblings of the `Fn::Transform` function call, but not the function call itself. Also, `params` contains JSON representing the macro parameters. In this case, replacement and target. Similarly, `templateParameterValues` contains JSON representing the parameters specified for the template as a whole.
## Lambda function code
Following is the actual code for the Lambda function underlying the `JavaMacroFunc` example macro. It iterates over the template fragment included in the response (be it in string, list, or map format), looking for the specified target string. If it finds the specified target string, the Lambda function replaces the target string with the specified replacement string. If not, the function leaves the template fragment unchanged. Then, the function returns a map of the expected properties, discussed in detail below, to CloudFormation.
```
package com.macroexample.lambda.demo;
import java.util.List;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.Map;
import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.RequestHandler;
public class LambdaFunctionHandler implements RequestHandler, Map> {
private static final String REPLACEMENT = "replacement";
private static final String TARGET = "target";
private static final String PARAMS = "params";
private static final String FRAGMENT = "fragment";
private static final String REQUESTID = "requestId";
private static final String STATUS = "status";
private static final String SUCCESS = "SUCCESS";
private static final String FAILURE = "FAILURE";
@Override
public Map handleRequest(Map event, Context context) {
// TODO: implement your handler
final Map responseMap = new HashMap();
responseMap.put(REQUESTID, event.get(REQUESTID));
responseMap.put(STATUS, FAILURE);
try {
if (!event.containsKey(PARAMS)) {
throw new RuntimeException("Params are required");
}
final Map params = (Map) event.get(PARAMS);
if (!params.containsKey(REPLACEMENT) || !params.containsKey(TARGET)) {
throw new RuntimeException("replacement or target under Params are required");
}
final String replacement = (String) params.get(REPLACEMENT);
final String target = (String) params.get(TARGET);
final Object fragment = event.getOrDefault(FRAGMENT, new HashMap());
final Object retFragment;
if (fragment instanceof String) {
retFragment = iterateAndReplace(replacement, target, (String) fragment);
} else if (fragment instanceof List) {
retFragment = iterateAndReplace(replacement, target, (List