AWS::Serverless transform takes an entire template written in the AWS Serverless Application Model (AWS SAM) syntax and transforms and expands it into a compliant AWS CloudFormation template. (For more information about serverless applications and AWS SAM, see Deploying Lambda-based applications in the AWS Lambda Developer Guide.)
An AWS 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 AWS::CloudFormation::Macro, which enables users to call the Lambda function from within AWS 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 an AWS::CloudFormation::Macro resource, and then create either a stack or stack set with self-managed permissions from the template. AWS CloudFormation StackSets doesn't currently support creating or updating stack sets with service-managed permissions from templates that reference macros.
To process a section, or snippet, 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.
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.) AWS 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, AWS CloudFormation generates a change set that includes the processed template content. After you review the change set, execute it to apply the changes.
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. To create or update the stack set directly, you must use the CreateStackSet or UpdateStackSet action and specify the CAPABILITY_AUTO_EXPAND capability. 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.
If you are comfortable creating or updating a stack directly from a processed template, without first reviewing the proposed changes in a change set, you can do so by specifying the CAPABILITY_AUTO_EXPAND capability during a CreateStack or UpdateStack request. You should only create stacks directly from a template that references macros if you know what processing the macros performs.
For macros, AWS CloudFormation invokes the underlying Lambda functions with the following event mapping. AWS CloudFormation sends its request in JSON format, and it expects the function response to be formatted as JSON too.
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 AWS CloudFormation macro scope.
The processed template content for AWS CloudFormation to include in the processed template, including siblings. AWS CloudFormation replaces the template content that is passed to the Lambda function with the template fragment it receives in the Lambda response.
If your function doesn't actually change the template content that AWS 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 AWS CloudFormation in its response.
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.
In order for AWS 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, AWS CloudFormation impersonates the user while running the macro. For more information, see Lambda permissions model in the AWS Lambda Developer Guide and Actions and condition context keys for AWS Lambda in the IAM User Guide.
The AWS::Serverless transform and AWS::Include transform transforms are macros hosted by AWS CloudFormation. No special permissions are necessary to use them, and they're available from within any account in AWS CloudFormation.
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 log group to which AWS CloudFormation sends error logging information when invoking the macro's underlying AWS Lambda function, and the role AWS CloudFormation should assume when sending log entries to those logs.
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 about modules, see Developing modules in the CloudFormation CLI User Guide.
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.
If your stack set template references one or more macros, you must create or update the stack set directly from the processed template, without first reviewing the resulting changes in a change set. To create or update the stack set directly, use the CreateStackSet or UpdateStackSet action and specify the CAPABILITY_AUTO_EXPAND capability. 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.
Change sets don't currently support nested stacks. If you want to create or update a stack using a template that references macros and contains nested stacks, you must create or update the stack directly. To perform this, use the CreateStack or UpdateStack action and specify the CAPABILITY_AUTO_EXPAND capability.
The Lambda function you build performs the processing of the template contents. Your function can process any part of a template, up to the entire template. For information about the event mapping to which your function must adhere, see AWS CloudFormation macro function interface. For information about additional considerations when creating macros, see Considerations when creating AWS CloudFormation macro definitions.
Create a stack from the template containing the macro in the desired account, or create a stack set with self-managed permissions from the template referencing the macro in the administrator account, then create stack instances in the desired target accounts.
After AWS 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.
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.
For example, in the template sample below, AWS CloudFormation evaluates the PolicyAdder macro first, because it's the most deeply-nested macro in the template. AWS CloudFormation then evaluates MyMacro before evaluating AWS::Serverless because it's listed before AWS::Serverless in the Transform section.
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.
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, AWS CloudFormation requires you to acknowledge their capabilities. Because AWS 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, AWS CloudFormation has the necessary capabilities to create IAM resources.
7fc3f7cf58