Skip to content

Latest commit

 

History

History
601 lines (466 loc) · 18 KB

generated_resources.rst

File metadata and controls

601 lines (466 loc) · 18 KB
Raw

CloudFormation Resources Generated By SAM

When you create a Serverless Function or a Serverless API, SAM will create additional AWS resources to wire everything up. For example, when you create a AWS::Serverless::Function, SAM will create a Lambda Function resource along with an IAM Role resource to give appropriate permissions for your function. This document describes all such generated resources, how they are named, and how to refer to them in your SAM template.

AWS::Serverless::Function

Given a Function defined as follows:

MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    ...

Following resources will be generated:

CloudFormation Resource Type Logical ID
AWS::Lambda::Function MyFunction
AWS::IAM::Role MyFunctionRole

With AutoPublishAlias Property

Example:

MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    ...
    AutoPublishAlias: live
    ...

Additional generated resources:

CloudFormation Resource Type Logical ID
AWS::Lambda::Version MyFunctionVersionSHA (10 digits of SHA256 of CodeUri)
AWS::Lambda::Alias MyFunctionAliaslive

With DeploymentPreference Property

Example:

MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    ...
    AutoPublishAlias: live
    DeploymentPreference:
      Type: Linear10PercentEvery10Minutes
      Role: "arn"
    ...

Additional generated resources:

CloudFormation Resource Type Logical ID
AWS::CodeDeploy::Application ServerlessDeploymentApplication (only one per stack)
AWS::CodeDeploy::DeploymentGroup MyFunctionDeploymentGroup
AWS::IAM::Role CodeDeployServiceRole
NOTE: AWS::IAM::Role resources are only generated if no Role parameter is supplied for DeploymentPreference

With Events

A common theme with all Events is SAM will generate a AWS::Lambda::Permission resource to give event source permission to invoke the function. Other generated resources depend on the specific event type.

API

This is called an "Implicit API". There can be many functions in the template that define these APIs. Behind the scenes, SAM will collect all implicit APIs from all Functions in the template, generate a Swagger, and create an implicit AWS::Serverless::Api using this Swagger. This API defaults to a StageName called "Prod" that cannot be configured.

MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    ...
    Events:
      ThumbnailApi:
        Type: Api
        Properties:
          Path: /thumbnail
          Method: GET
    ...

Additional generated resources:

CloudFormation Resource Type Logical ID
AWS::ApiGateway::RestApi ServerlessRestApi
AWS::ApiGateway::Stage ServerlessRestApiProdStage
AWS::ApiGateway::Deployment ServerlessRestApiDeploymentSHA (10 Digits of SHA256 of Swagger)
AWS::Lambda::Permission MyFunctionThumbnailApiPermissionProd (Prod is the default Stage Name for implicit APIs)
NOTE: ServerlessRestApi* resources are generated one per stack.

HTTP API

This is called an "Implicit HTTP API". There can be many functions in the template that define these APIs. Behind the scenes, SAM will collect all implicit HTTP APIs from all Functions in the template, generate an OpenApi doc, and create an implicit AWS::Serverless::HttpApi using this OpenApi. This API defaults to a StageName called "$default" that cannot be configured.

MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    ...
    Events:
      ThumbnailApi:
        Type: HttpApi
        Properties:
          Path: /thumbnail
          Method: GET
    ...

Additional generated resources:

CloudFormation Resource Type Logical ID
AWS::ApiGatewayV2::Api ServerlessHttpApi
AWS::ApiGatewayV2::Stage ServerlessHttpApiApiGatewayDefaultStage
AWS::Lambda::Permission MyFunctionThumbnailApiPermission
NOTE: ServerlessHttpApi* resources are generated one per stack.

Cognito

Example:

MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    ...
    Events:
      CognitoTrigger:
        Type: Cognito
        Properties:
          UserPool: !Ref MyUserPool
          Trigger: PreSignUp
    ...

MyUserPool:
  Type: AWS::Cognito::UserPool

Additional generated resources:

CloudFormation Resource Type Logical ID
AWS::Lambda::Permissions MyFunctionCognitoPermission
AWS::Cognito::UserPool Existing MyUserPool resource is modified to append LambdaConfig property where the Lambda function trigger is defined

NOTE: You must refer to a Cognito UserPool defined in the same template. This is for two reasons:

1. SAM needs to add a LambdaConfig property to the UserPool resource by reading and modifying the resource definition

2. Lambda triggers are specified as a property on the UserPool resource. Since CloudFormation cannot modify a resource created outside of the stack, this bucket needs to be defined within the template.

S3

Example:

MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    ...
    Events:
      S3Trigger:
        Type: S3
        Properties:
          Bucket: !Ref MyBucket
          Events: s3:ObjectCreated:*
    ...

MyBucket:
  Type: AWS::S3::Bucket

Additional generated resources:

CloudFormation Resource Type Logical ID
AWS::Lambda::Permission MyFunctionS3TriggerPermission
AWS::S3::Bucket Existing MyBucket resource is modified to append NotificationConfiguration property where the Lambda function trigger is defined

NOTE: You must refer to an S3 Bucket defined in the same template. This is for two reasons:

1. SAM needs to add a NotificationConfiguration property to the bucket resource by reading and modifying the resource definition

2. Lambda triggers are specified as a property on the bucket resource. Since CloudFormation cannot modify a resource created outside of the stack, this bucket needs to be defined within the template.

SNS

Example:

MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    ...
    Events:
      MyTrigger:
        Type: SNS
        Properties:
          Topic: arn:aws:sns:us-east-1:123456789012:my_topic
          SqsSubscription:
            QueuePolicyLogicalId: CustomQueuePolicyLogicalId
            QueueArn: !GetAtt MyCustomQueue.Arn
            QueueUrl: !Ref MyCustomQueue
            BatchSize: 5
            Enabled: true
    ...

Additional generated resources:

CloudFormation Resource Type Logical ID
AWS::Lambda::Permission MyFunctionMyTriggerPermission
AWS::Lambda::EventSourceMapping MyFunctionMyTriggerEventSourceMapping
AWS::SNS::Subscription MyFunctionMyTrigger
AWS::SQS::Queue MyFunctionMyTriggerQueue
AWS::SQS::QueuePolicy MyFunctionMyTriggerQueuePolicy

NOTE: AWS::Lambda::Permission resources are only generated if SqsSubscription is false. AWS::Lambda::EventSourceMapping, AWS::SQS::Queue, AWS::SQS::QueuePolicy resources are only generated if SqsSubscription is true.

AWS::SQS::Queue resources are only generated if SqsSubscription is true.

Example:

MyFunction:
Type: AWS::Serverless::Function
Properties:
  ...
  Events:
    MyTrigger:
      Type: SNS
      Properties:
        Topic: arn:aws:sns:us-east-1:123456789012:my_topic
        SqsSubscription: true
  ...

Kinesis

Example:

MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    ...
    Events:
      MyTrigger:
        Type: Kinesis
        Properties:
          Stream: arn:aws:kinesis:us-east-1:123456789012:stream/my-stream
          StartingPosition: TRIM_HORIZON
    ...

Additional generated resources:

CloudFormation Resource Type Logical ID
AWS::Lambda::Permission MyFunctionMyTriggerPermission
AWS::Lambda::EventSourceMapping MyFunctionMyTrigger

MQ

Example:

MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    ...
    Events:
      MyTrigger:
        Type: MQ
        Properties:
          Broker: arn:aws:mq:us-east-2:123456789012:broker:MyBroker:b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9
          SourceAccessConfigurations:
            Type: BASIC_AUTH
            URI: arn:aws:secretsmanager:us-west-2:123456789012:secret:my-path/my-secret-name-1a2b3c
    ...

Additional generated resources:

CloudFormation Resource Type Logical ID
AWS::Lambda::Permission MyFunctionMyTriggerPermission
AWS::Lambda::EventSourceMapping MyFunctionMyTrigger

MSK

Example:

MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    ...
    Events:
      MyTrigger:
        Type: MSK
        Properties:
          Stream: arn:aws:kafka:us-east-1:123456789012:cluster/mycluster/6cc0432b-8618-4f44-bccc-e1fbd8fb7c4d-2
          StartingPosition: TRIM_HORIZON
    ...

Additional generated resources:

CloudFormation Resource Type Logical ID
AWS::Lambda::Permission MyFunctionMyTriggerPermission
AWS::Lambda::EventSourceMapping MyFunctionMyTrigger

SQS

Example:

MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    ...
    Events:
      MyTrigger:
        Type: SQS
        Properties:
          Queue: arn:aws:sqs:us-east-1:123456789012:my-queue
    ...

Additional generated resources:

CloudFormation Resource Type Logical ID
AWS::Lambda::Permission MyFunctionMyTriggerPermission
AWS::Lambda::EventSourceMapping MyFunctionMyTrigger

DynamoDb

Example:

MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    ...
    Events:
      MyTrigger:
        Type: DynamoDb
        Properties:
          Stream: arn:aws:dynamodb:us-east-1:123456789012:table/TestTable/stream/2016-08-11T21:21:33.291
          StartingPosition: TRIM_HORIZON
    ...

Additional generated resources:

CloudFormation Resource Type Logical ID
AWS::Lambda::Permission MyFunctionMyTriggerPermission
AWS::Lambda::EventSourceMapping MyFunctionMyTrigger

Schedule

Example:

MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    ...
    Events:
      MyTimer:
        Type: Schedule
        Properties:
          Input: rate(5 minutes)
          DeadLetterConfig:
            Type: SQS
    ...

Additional generated resources:

CloudFormation Resource Type Logical ID
AWS::Lambda::Permission MyFunctionMyTimerPermission
AWS::Events::Rule MyFunctionMyTimer
AWS::SQS::Queue MyFunctionMyTimerQueue
AWS::SQS::QueuePolicy MyFunctionMyTimerQueuePolicy

CloudWatchEvent (superseded by EventBridgeRule, see below)

Example:

MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    ...
    Events:
      OnTerminate:
        Type: CloudWatchEvent
        Properties:
          Pattern:
            source:
              - aws.ec2
            detail-type:
              - EC2 Instance State-change Notification
            detail:
              state:
                - terminated
    ...

Additional generated resources:

CloudFormation Resource Type Logical ID
AWS::Lambda::Permission MyFunctionOnTerminatePermission
AWS::Events::Rule MyFunctionOnTerminate

EventBridgeRule

Example:

MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    ...
    Events:
      OnTerminate:
        Type: EventBridgeRule
        Properties:
          Pattern:
            source:
              - aws.ec2
            detail-type:
              - EC2 Instance State-change Notification
            detail:
              state:
                - terminated
            DeadLetterConfig:
              Type: SQS
            RetryPolicy:
              MaximumEventAgeInSeconds: 600
              MaximumRetryAttempts:3
    ...

Additional generated resources:

CloudFormation Resource Type Logical ID
AWS::Lambda::Permission MyFunctionOnTerminatePermission
AWS::Events::Rule MyFunctionOnTerminate
AWS::SQS::Queue MyFunctionOnTerminateQueue
AWS::SQS::QueuePolicy MyFunctionOnTerminateQueuePolicy

AWS::Serverless::Api

In contrast to Implict APIs, you can explicitly define your API resource by providing an entire Swagger definition of your API.

Example:

MyApi:
  Type: AWS::Serverless::Api
  Properties:
    ...
    DefinitionUri: s3://bucket/swagger.json
    StageName: dev
    ...

Generated resources:

CloudFormation Resource Type Logical ID
AWS::ApiGateway::RestApi MyApi
AWS::ApiGateway::Stage MyApidevStage
AWS::ApiGateway::Deployment MyApiDeploymentSHA (10 Digits of SHA256 of DefinitionUri or DefinitionBody value)

NOTE: By just specifying AWS::Serverless::Api resource, SAM will not add permission for API Gateway to invoke the the Lambda Function backing the APIs. You should explicitly re-define all APIs under Events section of the AWS::Serverless::Function resource but include a RestApiId property that references the AWS::Serverless::Api resource. SAM will add permission for these APIs to invoke the function.

Example:

MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    ...
    Events:
      GetApi:
        Type: Api
        Properties:
          Path: /
          Method: GET

          # This is the property that instructs SAM to just add permissions for an explicitly defined API
          RestApiId: !Ref MyApi