AWS::Serverless transform

This topic describes how to use the AWS::Serverless transform to process a template written in the Amazon Serverless Application Model (Amazon SAM) syntax and transform it into a compliant CloudFormation template.

For more information about using the AWS::Serverless transform, see Amazon SAM transform on GitHub.

Usage

To use the AWS::Serverless transform, you must declare it at the top level of your CloudFormation template. You can't use AWS::Serverless as a transform embedded in any other template section.

The declaration must use the literal string AWS::Serverless-2016-10-31 as its value. You can't use a parameter or function to specify a transform value.

Syntax

To declare this transform in your CloudFormation template, use the following syntax:

{
  "Transform":"AWS::Serverless-2016-10-31",
  "Resources":{
    ...
  }
}

Transform: AWS::Serverless-2016-10-31
Resources:
  ...

The AWS::Serverless transform is a standalone declaration with no additional parameters.

Examples

The following examples show how to use the AWS::Serverless transform and Amazon SAM syntax to simplify the declaration of a Lambda function and its execution role.

{
  "Transform":"AWS::Serverless-2016-10-31",
  "Resources":{
    "MyFunction":{
      "Type":"AWS::Serverless::Function",
      "Properties":{
        "Handler":"index.handler",
        "Runtime":"nodejs20.x",
        "CodeUri":"s3://amzn-s3-demo-bucket/MySourceCode.zip"
      }
    }
  }
}

Transform: AWS::Serverless-2016-10-31
Resources:
  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs20.x
      CodeUri: 's3://amzn-s3-demo-bucket/MySourceCode.zip'

When creating a change set from the template, CloudFormation expands the Amazon SAM syntax, as defined by the transform. The processed template expands the AWS::Serverless::Function resource, declaring a Lambda function and an execution role.

{
  "Resources": {
    "MyFunction": {
      "Type": "AWS::Lambda::Function",
      "Properties": {
        "Handler": "index.handler",
        "Code": {
          "S3Bucket": "amzn-s3-demo-bucket",
          "S3Key": "MySourceCode.zip"
        },
        "Role": {
          "Fn::GetAtt": ["MyFunctionRole", "Arn"]
        },
        "Runtime": "nodejs20.x"
      }
    },
    "MyFunctionRole": {
      "Type": "AWS::IAM::Role",
      "Properties": {
        "ManagedPolicyArns": ["arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"],
        "AssumeRolePolicyDocument": {
          "Version": "2012-10-17",
          "Statement": [{
            "Action": ["sts:AssumeRole"],
            "Effect": "Allow",
            "Principal": {
              "Service": ["lambda.amazonaws.com"]
            }
          }]
        }
      }
    }
  }
}

Using AWS::Serverless with AWS::LanguageExtensions

When using both AWS::Serverless and AWS::LanguageExtensions transforms, referencing resources like AWS::ApiGateway::Stage requires special syntax when the stage name is passed as a non-NoEcho parameter value.

Instead of using the Amazon SAM syntax for the reference (MyApi.Stage), use Fn::Sub to generate the logical ID reference. For example, "Ref": {"Fn::Sub": "${MyApi}${StageName}Stage"}. This builds the correct logical ID at runtime.

The reason for this special format is because these two transforms handle values differently:

Related resources

For more information about serverless applications and the Amazon Serverless Application Model (Amazon SAM), see Amazon Serverless Application Model Developer Guide.

For the resource and property types that are specific to Amazon SAM, see Amazon SAM resources and properties in the Amazon Serverless Application Model Developer Guide.

For general information about using macros, see Perform custom processing on CloudFormation templates with template macros in the Amazon CloudFormation User Guide.