Creates an AWS Lambda function, an AWS Identity and Access Management (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 that your application requires. For more information about building custom runtimes, see Building custom runtimes.
To declare this entity in your AWS Serverless Application Model (AWS SAM) template, use the following syntax.
Type: AWS::Serverless::Function
Properties:
[AssumeRolePolicyDocument](#sam-function-assumerolepolicydocument): JSON
[AutoPublishAlias](#sam-function-autopublishalias): String
[AutoPublishCodeSha256](#sam-function-autopublishcodesha256): String
[CodeSigningConfigArn](#sam-function-codesigningconfigarn): String
[CodeUri](#sam-function-codeuri): String | FunctionCode
[DeadLetterQueue](#sam-function-deadletterqueue): Map | DeadLetterQueue
[DeploymentPreference](#sam-function-deploymentpreference): DeploymentPreference
[Description](#sam-function-description): String
[Environment](#sam-function-environment): [Environment](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-environment.html)
[EventInvokeConfig](#sam-function-eventinvokeconfig): EventInvokeConfiguration
[Events](#sam-function-events): EventSource
[FileSystemConfigs](#sam-function-filesystemconfigs): List
[FunctionName](#sam-function-functionname): String
[Handler](#sam-function-handler): String
[ImageConfig](#sam-function-imageconfig): [ImageConfig](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-imageconfig)
[ImageUri](#sam-function-imageuri): String
[InlineCode](#sam-function-inlinecode): String
[KmsKeyArn](#sam-function-kmskeyarn): String
[Layers](#sam-function-layers): List
[MemorySize](#sam-function-memorysize): Integer
[PackageType](#sam-function-packagetype): String
[PermissionsBoundary](#sam-function-permissionsboundary): String
[Policies](#sam-function-policies): String | List | Map
[ProvisionedConcurrencyConfig](#sam-function-provisionedconcurrencyconfig): [ProvisionedConcurrencyConfig](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-alias.html#cfn-lambda-alias-provisionedconcurrencyconfig)
[ReservedConcurrentExecutions](#sam-function-reservedconcurrentexecutions): Integer
[Role](#sam-function-role): String
[Runtime](#sam-function-runtime): String
[Tags](#sam-function-tags): Map
[Timeout](#sam-function-timeout): Integer
[Tracing](#sam-function-tracing): String
[VersionDescription](#sam-function-versiondescription): String
[VpcConfig](#sam-function-vpcconfig): [VpcConfig](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-vpcconfig.html)
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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html#cfn-iam-role-assumerolepolicydocument)
property of an AWS::IAM::Role
resource. AWS SAM adds this property to the generated IAM role for this function. If a role's Amazon Resource Name (ARN) is provided for this function, this property does nothing.
AutoPublishAlias
The name of the Lambda alias. For more information about Lambda aliases, see Lambda function aliases in the AWS Lambda Developer Guide. 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 whether 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 can occur when the deployment package stored in an Amazon Simple Storage Service (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, to trigger the gradual deployment successfully, you must provide a unique value for AutoPublishCodeSha256
.
Type: String
Required: No
AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.
CodeSigningConfigArn
The ARN of the AWS::Lambda::CodeSigningConfig resource, used to enable code signing for this function. For more information about code signing, see Configuring code signing for AWS SAM applications.
Type: String
Required: No
AWS CloudFormation compatibility: This property is passed directly to the [CodeSigningConfigArn](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-codesigningconfigarn)
property of an AWS::Lambda::Function
resource.
CodeUri
The function code's Amazon S3 URI, path to local folder, or FunctionCode object. This property only applies if the PackageType
property is set to Zip
, otherwise it is ignored.
Notes:
1. If the PackageType
property is set to Zip
(default), then one of CodeUri
or InlineCode
is required.
2. If an Amazon S3 URI or FunctionCode object is provided, the Amazon S3 object referenced must be a valid Lambda deployment package.
3. If the path to a local folder is provided, for the code to be transformed properly the template must go through the workflow that includes sam build followed by either sam deploy or sam package. By default, relative paths are resolved with respect to the AWS SAM template's location.
Type: String | FunctionCode
Required: Conditional
AWS CloudFormation compatibility: This property is similar to the [Code](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-code)
property of an AWS::Lambda::Function
resource. The nested Amazon S3 properties are named differently.
DeadLetterQueue
Configures an Amazon Simple Notification Service (Amazon SNS) topic or Amazon Simple Queue Service (Amazon 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 in the AWS Lambda Developer Guide.
Type: Map | DeadLetterQueue
Required: No
AWS CloudFormation compatibility: This property is similar to the [DeadLetterConfig](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-deadletterconfig.html)
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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-environment.html)
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 Elastic File System (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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-functionname)
property of an AWS::Lambda::Function
resource.
Handler
The function within your code that is called to begin execution. This property is only required if the PackageType
property is set to Zip
.
Type: String
Required: Conditional
AWS CloudFormation compatibility: This property is passed directly to the [Handler](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-handler)
property of an AWS::Lambda::Function
resource.
ImageConfig
The object used to configure Lambda container image settings. For more information, see Using container images with Lambda in the AWS Lambda Developer Guide.
Type: ImageConfig
Required: No
AWS CloudFormation compatibility: This property is passed directly to the [ImageConfig](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-imageconfig)
property of an AWS::Lambda::Function
resource.
ImageUri
The URI of the Amazon Elastic Container Registry (Amazon ECR) repository for the Lambda function's container image. This property only applies if the PackageType
property is set to Image
, otherwise it is ignored. For more information, see Using container images with Lambda in the AWS Lambda Developer Guide.
Note: If the PackageType
property is set to Image
, then either ImageUri
is required, or you must build your application with necessary Metadata
entries in the AWS SAM template file. For more information, see Building applications.
Type: String
Required: No
AWS CloudFormation compatibility: This property is passed directly to the [ImageUri](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-code.html#cfn-lambda-function-code-imageuri)
property of the AWS::Lambda::Function
Code
data type.
InlineCode
The Lambda function code that is written directly in the template. This property only applies if the PackageType
property is set to Zip
, otherwise it is ignored.
Note: If the PackageType
property is set to Zip
(default), then one of CodeUri
or InlineCode
is required.
Type: String
Required: Conditional
AWS CloudFormation compatibility: This property is passed directly to the [ZipFile](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-code.html#cfn-lambda-function-code-zipfile)
property of the AWS::Lambda::Function
Code
data type.
KmsKeyArn
The 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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-kmskeyarn)
property of an AWS::Lambda::Function
resource.
Layers
The list of LayerVersion
ARNs that this function should use. The order specified here is the order in which they will be imported when running the Lambda function.
Type: List
Required: No
AWS CloudFormation compatibility: This property is passed directly to the [Layers](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-layers)
property of an AWS::Lambda::Function
resource.
MemorySize
The size of the memory in MB allocated per invocation of the function.
Type: Integer
Required: No
AWS CloudFormation compatibility: This property is passed directly to the [MemorySize](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-memorysize)
property of an AWS::Lambda::Function
resource.
PackageType
The deployment package type of the Lambda function. For more information, see Lambda deployment packages in the AWS Lambda Developer Guide.
Notes:
1. If this property is set to Zip
(default), then either CodeUri
or InlineCode
applies, and ImageUri
is ignored.
2. If this property is set to Image
, then only ImageUri
applies, and both CodeUri
and InlineCode
are ignored.
Valid values: Zip
or Image
Type: String
Required: No
Default: Zip
AWS CloudFormation compatibility: This property is passed directly to the [PackageType](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-packagetype)
property of an AWS::Lambda::Function
resource.
PermissionsBoundary
The ARN of a permissions boundary to use for this function's execution role. This property works only if the role is generated for you.
Type: String
Required: No
AWS CloudFormation compatibility: This property is passed directly to the [PermissionsBoundary](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html#cfn-iam-role-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, and can be the name of AWS managed policies or AWS SAM policy templates, or inline IAM policy documents formatted in YAML.
For more information about AWS managed policies, see AWS managed policies in the IAM User Guide. For more information about AWS SAM policy templates, see AWS SAM policy templates in the AWS Serverless Application Model Developer Guide. For more information about inline policies, see Inline policies in the IAM User Guide.
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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html#cfn-iam-role-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 accepts only JSON policy documents.
ProvisionedConcurrencyConfig
The provisioned concurrency configuration of a function's alias.
Note: ProvisionedConcurrencyConfig
can be specified only if the AutoPublishAlias
is set. Otherwise, an error results.
Type: ProvisionedConcurrencyConfig
Required: No
AWS CloudFormation compatibility: This property is passed directly to the [ProvisionedConcurrencyConfig](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-alias.html#cfn-lambda-alias-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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-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. This property is only required if the PackageType
property is set to Zip
.
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 that this function requires. For more information about building custom runtimes, see Building custom runtimes.
Type: String
Required: Conditional
AWS CloudFormation compatibility: This property is passed directly to the [Runtime](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-runtime)
property of an AWS::Lambda::Function
resource.
Tags
A map (string to string) that specifies the tags added to this function. 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.
When the stack is created, AWS SAM automatically adds a lambda:createdBy:SAM
tag to this Lambda function, and to the default roles that are generated for this function.
Type: Map
Required: No
AWS CloudFormation compatibility: This property is similar to the [Tags](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-tags)
property of an AWS::Lambda::Function
resource. The Tags
property in AWS SAM consists of key-value pairs (whereas in AWS CloudFormation this property consists of a list of Tag
objects). Also, AWS SAM automatically adds a lambda:createdBy:SAM
tag to this Lambda function, and to the default roles that are generated for this function.
Timeout
The maximum time in seconds that the function can run before it is stopped.
Type: Integer
Required: No
Default: 3
AWS CloudFormation compatibility: This property is passed directly to the [Timeout](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-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.
Valid values: Active
or PassThrough
Type: String
Required: No
AWS CloudFormation compatibility: This property is similar to the [TracingConfig](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-tracingconfig)
property of an AWS::Lambda::Function
resource. If the Tracing
property is set to Active
and the Role
property is not specified, then AWS SAM adds the arn:aws:iam::aws:policy/AWSXrayWriteOnlyAccess
policy to the Lambda execution role that it creates for you.
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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-version.html#cfn-lambda-version-description)
property of an AWS::Lambda::Version
resource.
VpcConfig
The configuration that enables this function to access private resources within your virtual private cloud (VPC).
Type: VpcConfig
Required: No
AWS CloudFormation compatibility: This property is passed directly to the [VpcConfig](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-vpcconfig.html)
property of an AWS::Lambda::Function
resource.
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 https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html in the AWS CloudFormation User Guide.
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 https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-getatt.html in the AWS CloudFormation User Guide.
Arn
The ARN of the underlying Lambda function.
The following is a basic example of an AWS::Serverless::Function resource of package type Zip
(default) and function code in an Amazon S3 bucket.
Type: AWS::Serverless::Function
Properties:
Handler: index.handler
Runtime: python3.6
CodeUri: s3://bucket-name/key-name
The following is an example of an AWS::Serverless::Function of package type Zip
(default) that uses InlineCode
, Layers
, Tracing
, Policies
, Amazon EFS
, and an Api
event source.
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
The following is an example of an ImageConfig
for a Lambda function of package type Image
.
HelloWorldFunction:
Type: AWS::Serverless::Function
Properties:
PackageType: Image
ImageUri: account-id.dkr.ecr.region.amazonaws.com/ecr-repo-name:image-name
ImageConfig:
Command:
- "app.lambda_handler"
EntryPoint:
- "entrypoint1"
WorkingDirectory: "workDir"