AWS::Serverless::Function - AWS Serverless Application Model
SyntaxPropertiesReturn ValuesExamples

AWS::Serverless::Function

Creates a Lambda function, IAM execution role, and event source mappings that trigger the function.

The AWS::Serverless::Function resource also supports the Metadata resource attribute, so you can instruct AWS SAM to build custom runtimes required by your application. For more information about building custom runtimes, see Building custom runtimes.

Syntax

To declare this entity in your AWS Serverless Application Model (AWS SAM) template, use the following syntax.

Properties

AssumeRolePolicyDocument

Adds an AssumeRolePolicyDocument for the default created Role for this function. If this property isn't specified, AWS SAM adds a default assume role for this function.

Type: JSON

Required: No

AWS CloudFormation compatibility: This property is similar to the AssumeRolePolicyDocument property of an AWS::IAM::Role resource. AWS SAM adds this property to the generated IAM role for this function. If a role ARN is provided for this function, this property does nothing.

AutoPublishAlias

Name of the Lambda alias. For more information about Lambda aliases, see AWS Lambda Function Aliases. For examples that use this property, see Deploying serverless applications gradually.

AWS SAM generates AWS::Lambda::Version and AWS::Lambda::Alias resources when this property is set. For information about this scenario, see AutoPublishAlias property is specified. For general information about generated AWS CloudFormation resources, see Generated AWS CloudFormation resources.

Type: String

Required: No

AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.

AutoPublishCodeSha256

The string value that is used (along with the value in CodeUri) to determine if a new Lambda version should be published.

This property addresses a problem that occurs when an AWS SAM template has the following characteristics: the DeploymentPreference object is configured for gradual deployments (as described in Deploying Serverless Applications Gradually), the AutoPublishAlias property is set and doesn't change between deployments, and the CodeUri property is set and doesn't change between deployments.

This scenario might occur when the deployment package stored in an Amazon S3 location is replaced by a new deployment package that contains updated Lambda function code, but the CodeUri property remains unchanged (as opposed to the new deployment package being uploaded to a new Amazon S3 location and the CodeUri being changed to the new location).

In this scenario, you must provide a unique value for AutoPublishCodeSha256 to trigger the gradual deployment successfully.

Type: String

Required: No

AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.

CodeUri

The Amazon S3 URI, local file path, or FunctionCode object of the function code.

If an Amazon S3 URI or FunctionCode object is provided, the Amazon S3 object referenced must be a valid Lambda deployment package.

If a local file path is provided, the template must go through the workflow that includes the sam deploy or sam package command, in order for the code to be transformed properly.

Note: Either CodeUri or InlineCode is required.

Type: String | FunctionCode

Required: Conditional

AWS CloudFormation compatibility: This property is similar to the Code property of an AWS::Lambda::Function resource. The nested Amazon S3 properties are named differently.

DeadLetterQueue

Configures SNS topic or SQS queue where Lambda sends events that it can't process. For more information about dead-letter queue functionality, see AWS Lambda Function Dead Letter Queues.

Type: Map | DeadLetterQueue

Required: No

AWS CloudFormation compatibility: This property is similar to the DeadLetterConfig property of an AWS::Lambda::Function resource. In AWS CloudFormation the type is derived from the TargetArn, whereas in AWS SAM you must pass the type along with the TargetArn.

DeploymentPreference

The settings to enable gradual Lambda deployments.

If a DeploymentPreference object is specified, AWS SAM creates an AWS::CodeDeploy::Application called ServerlessDeploymentApplication (one per stack), an AWS::CodeDeploy::DeploymentGroup called <function-logical-id>DeploymentGroup, and an AWS::IAM::Role called CodeDeployServiceRole.

Type: DeploymentPreference

Required: No

AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.

See also: For more information about this property, see Deploying serverless applications gradually.

Description

A description of the function.

Type: String

Required: No

AWS CloudFormation compatibility: This property is passed directly to the Description property of an AWS::Lambda::Function resource.

Environment

The configuration for the runtime environment.

Type: Environment

Required: No

AWS CloudFormation compatibility: This property is passed directly to the Environment property of an AWS::Lambda::Function resource.

EventInvokeConfig

The object that describes event invoke configuration on a Lambda function.

Type: EventInvokeConfiguration

Required: No

AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.

Events

Specifies the events that trigger this function. Events consist of a type and a set of properties that depend on the type.

Type: EventSource

Required: No

AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.

FileSystemConfigs

List of FileSystemConfig objects that specify the connection settings for an Amazon EFS file system.

If your template contains an AWS::EFS::MountTarget resource, you must also specify a DependsOn resource attribute to ensure that the mount target is created or updated before the function.

Type: List

Required: No

AWS CloudFormation compatibility: This property is passed directly to the FileSystemConfigs property of an AWS::Lambda::Function resource.

FunctionName

A name for the function. If you don't specify a name, a unique name is generated for you.

Type: String

Required: No

AWS CloudFormation compatibility: This property is passed directly to the FunctionName property of an AWS::Lambda::Function resource.

Handler

The function within your code that is called to begin execution.

Type: String

Required: Yes

AWS CloudFormation compatibility: This property is passed directly to the Handler property of an AWS::Lambda::Function resource.

InlineCode

The Lambda function code that is written directly in the template.

Note: Either CodeUri or InlineCode is required.

Type: String

Required: Conditional

AWS CloudFormation compatibility: This property is passed directly to the ZipFile property of the AWS::Lambda::Function Code data type.

KmsKeyArn

The Amazon Resource Name (ARN) of an AWS Key Management Service (AWS KMS) key that Lambda uses to encrypt and decrypt your function's environment variables.

Type: String

Required: No

AWS CloudFormation compatibility: This property is passed directly to the KmsKeyArn property of an AWS::Lambda::Function resource.

Layers

The list of LayerVersion ARNs that should be used by this function. The order specified here is the order that they will be imported when running the Lambda function.

Type: List

Required: No

AWS CloudFormation compatibility: This property is passed directly to the Layers property of an AWS::Lambda::Function resource.

MemorySize

The size of the memory allocated per invocation of the function in MB.

Type: Integer

Required: No

AWS CloudFormation compatibility: This property is passed directly to the MemorySize property of an AWS::Lambda::Function resource.

PermissionsBoundary

The ARN of a permissions boundary to use for this function's execution role. This property only works if the role is generated for you.

Type: String

Required: No

AWS CloudFormation compatibility: This property is passed directly to the PermissionsBoundary property of an AWS::IAM::Role resource.

Policies

One or more policies that this function needs. They will be appended to the default role for this function.

This property accepts a single string or a list of strings. The property can be the name of AWS managed AWS Identity and Access Management (IAM) policies, AWS SAM policy templates, or one or more inline policy documents formatted as a map.

For more information about AWS managed IAM policies, see AWS Managed Policies. For more information about AWS SAM policy templates, see AWS SAM policy templates. For more information about inline policies, see Inline Policies.

NOTE: If the Role property is set, this property is ignored.

Type: String | List | Map

Required: No

AWS CloudFormation compatibility: This property is similar to the Policies property of an AWS::IAM::Role resource. AWS SAM supports AWS managed policy names and AWS SAM policy templates, in addition to JSON policy documents. AWS CloudFormation only accepts JSON policy documents.

ProvisionedConcurrencyConfig

The provisioned concurrency configuration of a function's alias.

Note: ProvisionedConcurrencyConfig can only be specified if the AutoPublishAlias is set. Otherwise, an error results.

Type: ProvisionedConcurrencyConfig

Required: No

AWS CloudFormation compatibility: This property is passed directly to the ProvisionedConcurrencyConfig property of an AWS::Lambda::Alias resource.

ReservedConcurrentExecutions

The maximum number of concurrent executions that you want to reserve for the function.

For more information about this property, see AWS Lambda Function Scaling in the AWS Lambda Developer Guide.

Type: Integer

Required: No

AWS CloudFormation compatibility: This property is passed directly to the ReservedConcurrentExecutions property of an AWS::Lambda::Function resource.

Role

The ARN of an IAM role to use as this function's execution role.

Type: String

Required: No

AWS CloudFormation compatibility: This property is similar to the Role property of an AWS::Lambda::Function resource. This is required in AWS CloudFormation but not in AWS SAM. If a role isn't specified, one is created for you with a logical ID of <function-logical-id>Role.

Runtime

The identifier of the function's runtime.

Note: If you specify the provided identifier for this property, you can use the Metadata resource attribute to instruct AWS SAM to build the custom runtime required by this function. For more information about building custom runtimes, see Building custom runtimes.

Type: String

Required: Yes

AWS CloudFormation compatibility: This property is passed directly to the Runtime property of an AWS::Lambda::Function resource.

Tags

A map (string to string) that specifies the tags added to the Lambda function and the corresponding IAM execution role. Keys and values are limited to alphanumeric characters. Keys can be 1 to 127 Unicode characters in length and cannot be prefixed with aws:. Values can be 1 to 255 Unicode characters in length.

Type: Map

Required: No

AWS CloudFormation compatibility: This property is similar to the Tags property of an AWS::Lambda::Function resource. The Tags property in AWS SAM consists of Key:Value pairs. In AWS CloudFormation it consists of a list of Tag objects. When the stack is created, AWS SAM automatically adds a lambda:createdBy:SAM tag to this Lambda function and the corresponding IAM execution role.

Timeout

The maximum time that the function can run before it is killed, in seconds.

Type: Integer

Required: No

Default: 3

AWS CloudFormation compatibility: This property is passed directly to the Timeout property of an AWS::Lambda::Function resource.

Tracing

The string that specifies the function's X-Ray tracing mode. For more information about X-Ray, see Using AWS Lambda with AWS X-Ray in the AWS Lambda Developer Guide.

Supported values: Active and PassThrough.

Type: String

Required: No

AWS CloudFormation compatibility: This property is similar to the TracingConfig property of an AWS::Lambda::Function resource. If Tracing is set to Active, then AWS SAM adds the arn:aws:iam::aws:policy/AWSXrayWriteOnlyAccess policy to the Lambda role.

VersionDescription

Specifies the Description field that is added on the new Lambda version resource.

Type: String

Required: No

AWS CloudFormation compatibility: This property is passed directly to the Description property of an AWS::Lambda::Version resource.

VpcConfig

The configuration that enables this function to access private resources within your VPC.

Type: VpcConfig

Required: No

AWS CloudFormation compatibility: This property is passed directly to the VpcConfig property of an AWS::Lambda::Function resource.

Return Values

Ref

When the logical ID of this resource is provided to the Ref intrinsic function, it returns the resource name of the underlying Lambda function.

For more information about using the Ref function, see Ref in the AWS CloudFormation User Guide.

Fn::GetAtt

Fn::GetAtt returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

For more information about using Fn::GetAtt, see Fn::GetAtt in the AWS CloudFormation User Guide.

Arn

The Amazon Resource Name (ARN) of the underlying Lambda function.

Examples

Simple Function

The following is a base case example of an AWS::Serverless::Function resource.

YAML

Type: AWS::Serverless::Function
Properties:
  Handler: index.handler
  Runtime: python3.6
  CodeUri: s3://bucket/key

Function Properties Example

The following is an example of an AWS::Serverless::Function that uses InlineCode, Tracing, Policies, Layers, EFS, and an Api event source.

YAML

Type: AWS::Serverless::Function
DependsOn: MyMountTarget        # This is needed if an AWS::EFS::MountTarget resource is declared for EFS
Properties:
  Handler: index.handler
  Runtime: python3.6
  InlineCode: |
    def handler(event, context):
      print("Hello, world!")
  ReservedConcurrentExecutions: 30
  Layers:
    - Ref: MyLayer
  Tracing: Active
  Timeout: 120
  FileSystemConfigs:
    - Arn: !Ref MyEfsFileSystem
      LocalMountPath: /mnt/EFS
  Policies:
    - AWSLambdaExecute
    - Version: '2012-10-17' 
      Statement:
        - Effect: Allow
          Action:
            - s3:GetObject
            - s3:GetObjectACL
          Resource: 'arn:aws:s3:::my-bucket/*'
  Events:
    ApiEvent:
      Type: Api
      Properties:
        Path: /path
        Method: get