SAMConfig

CloudFormation Resources Generated By SAM
=========================================

.. contents::
  :local:
  :backlinks: none

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:

.. code:: yaml

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

Following resources will be generated:

================================== ================================
CloudFormation Resource Type       Logical ID 
================================== ================================
AWS::Lambda::Function              MyFunction
AWS::IAM::Role                     MyFunction\ **Role**
================================== ================================

With AutoPublishAlias Property
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Example:

.. code:: yaml

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


Additional generated resources:

================================== ================================
CloudFormation Resource Type       Logical ID 
================================== ================================
AWS::Lambda::Version               MyFunction\ **Version**\ *SHA* (10 digits of SHA256 of CodeUri)
AWS::Lambda::Alias                 MyFunction\ **Alias**\ *live*
================================== ================================


With DeploymentPreference Property
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Example:

.. code:: yaml

  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   MyFunction\ **DeploymentGroup** 
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.

.. code:: yaml

  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             *ServerlessRestApi*\ **Prod**\ Stage 
AWS::ApiGateway::Deployment        *ServerlessRestApi*\ Deployment\ *SHA* (10 Digits of SHA256 of Swagger)
AWS::Lambda::Permission            MyFunction\ **ThumbnailApi**\ Permission\ **Prod** 
                                   (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.

.. code:: yaml

  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            MyFunction\ **ThumbnailApi**\ Permission
================================== ================================


  NOTE: ``ServerlessHttpApi*`` resources are generated one per stack.

Cognito
^^^^^^^

Example:

.. code:: yaml

  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           *MyFunction*\ CognitoPermission
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:

.. code:: yaml

  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            MyFunction\ **S3Trigger**\ Permission
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:

.. code:: yaml

  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            MyFunction\ **MyTrigger**\ Permission
AWS::Lambda::EventSourceMapping    MyFunction\ **MyTrigger**\ EventSourceMapping
AWS::SNS::Subscription             MyFunction\ **MyTrigger**
AWS::SQS::Queue                    MyFunction\ **MyTrigger**\ Queue
AWS::SQS::QueuePolicy              MyFunction\ **MyTrigger**\ QueuePolicy
================================== ================================