Macros are actually a very simple concept—take the contents of a template, pass them to a lambda function as a string, and do string manipulation on the contents in order to replace or add elements. Then, the Lambda function passes the altered contents back to CloudFormation, and the stack is executed as if it had been originally written with the new content.

You created a global resource in your account by using the AWS::CloudFormation::Macro resource, which you linked to a custom lambda function. You then created a stack that makes use of that macro in order to expand a very short and simple template into a much more complex set of resources.

In this recipe, what we have done is to replace this code:

AWSTemplateFormatVersion: "2010-09-09"
Transform: CloudTrailBucket
Description: "This template will be transformed by the macro"
Resources:
  MyCloudTrailBucket:
  Type: CloudTrailBucket

We replaced it with this:

AWSTemplateFormatVersion: '2010-09-09'
Resources:
  MyCloudTrailBucket:
    Type: AWS::S3::Bucket
    DeletionPolicy: Retain
  MyCloudTrailBucketBucketPolicy:
    Type: AWS::S3::BucketPolicy
    Properties:
      Bucket:
        Ref: MyCloudTrailBucket
      PolicyDocument:
        Version: '2012-10-17'
        Statement:
        - Sid: AWSCloudTrailAclCheck
          Effect: Allow
          Principal:
            Service: cloudtrail.amazonaws.com
          Action: s3:GetBucketAcl
          Resource:
            Fn::Join:
            - ''
            - - 'arn:aws:s3:::'
              - Ref: MyCloudTrailBucket
        - Sid: AWSCloudTrailWrite
          Effect: Allow
          Principal:
            Service: cloudtrail.amazonaws.com
          Action: s3:PutObject
          Resource:
            Fn::Join:
            - ''
            - - 'arn:aws:s3:::'
              - Ref: MyCloudTrailBucket
              - "/AWSLogs/"
              - Ref: AWS::AccountId
              - "/*"
          Condition:
            StringEquals:
              s3:x-amz-acl: bucket-owner-full-control
  MyCloudTrailBucketTrail:
    DependsOn:
    - MyCloudTrailBucketBucketPolicy
    Type: AWS::CloudTrail::Trail
    Properties:
      S3BucketName:
        Ref: MyCloudTrailBucket
      IsLogging: true