Syntax Properties Return Values Examples

AWS::Serverless::Function

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 Lambda functions with custom runtimes in AWS SAM.

Note

When you deploy to AWS CloudFormation, AWS SAM transforms your AWS SAM resources into CloudFormation resources. For more information, see Generated CloudFormation resources for AWS SAM.

Syntax

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

YAML


Type: AWS::Serverless::Function
Properties:
  Architectures: List
  AssumeRolePolicyDocument: JSON
  AutoPublishAlias: String
  AutoPublishAliasAllProperties: Boolean
  AutoPublishCodeSha256: String
  CapacityProviderConfig: CapacityProviderConfig
  CodeSigningConfigArn: String
  CodeUri: String | FunctionCode
  DeadLetterQueue: Map | DeadLetterQueue
  DeploymentPreference: DeploymentPreference
  Description: String
  DurableConfig: DurableConfig
  Environment: Environment
  EphemeralStorage: EphemeralStorage
  EventInvokeConfig: EventInvokeConfiguration
  Events: EventSource
  FileSystemConfigs: List
  FunctionName: String
  FunctionScalingConfig: FunctionScalingConfig
  FunctionUrlConfig: FunctionUrlConfig
  Handler: String
  ImageConfig: ImageConfig
  ImageUri: String
  InlineCode: String
  KmsKeyArn: String
  Layers: List
  LoggingConfig: LoggingConfig
  MemorySize: Integer
  PackageType: String
  PermissionsBoundary: String
  Policies: String | List | Map
  PublishToLatestPublished: Boolean
  PropagateTags: Boolean
  ProvisionedConcurrencyConfig: ProvisionedConcurrencyConfig
  RecursiveLoop: String
  ReservedConcurrentExecutions: Integer
  Role: String
  RolePath: String
  Runtime: String
  RuntimeManagementConfig: RuntimeManagementConfig
  SnapStart: SnapStart
  SourceKMSKeyArn: String
  Tags: Map
  TenancyConfig: TenancyConfig
  Timeout: Integer
  Tracing: String
  VersionDescription: String
  VersionDeletionPolicy: String
  VpcConfig: VpcConfig

Properties

Architectures

The instruction set architecture for the function.

For more information about this property, see Lambda instruction set architectures in the AWS Lambda Developer Guide.

Valid values: One of x86_64 or arm64

Type: List

Required: No

Default: x86_64

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

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

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'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 with AWS SAM.

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 CloudFormation resources, see Generated CloudFormation resources for AWS SAM.

Type: String

Required: No

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

AutoPublishAliasAllProperties

Specifies when a new AWS::Lambda::Version is created. When true, a new Lambda version is created when any property in the Lambda function is modified. When false, a new Lambda version is created only when any of the following properties are modified:

Environment, MemorySize, or SnapStart.
Any change that results in an update to the Code property, such as CodeDict, ImageUri, or InlineCode.

This property requires AutoPublishAlias to be defined.

If AutoPublishCodeSha256 is also specified, its behavior takes precedence over AutoPublishAliasAllProperties: true.

Type: Boolean

Required: No

Default value: false

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

AutoPublishCodeSha256

When used, this string works with the CodeUri value to determine if a new Lambda version needs to be published. This property is often used to resolve the following deployment issue: A deployment package is stored in an Amazon S3 location and is replaced by a new deployment package with 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).

This problem is marked by an AWS SAM template having the following characteristics:

The DeploymentPreference object is configured for gradual deployments (as described in Deploying serverless applications gradually with AWS SAM)
The AutoPublishAlias property is set and doesn't change between deployments
The CodeUri property is set and doesn't change between deployments.

In this scenario, updating AutoPublishCodeSha256 results in a new Lambda version being created successfully. However, new function code deployed to Amazon S3 will not be recognized. To recognize new function code, consider using versioning in your Amazon S3 bucket. Specify the Version property for your Lambda function and configure your bucket to always use the latest deployment package.

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

Type: String

Required: No

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

CapacityProviderConfig

Configures the capacity provider to which published versions of the function will be attached. This enables the function to run on customer-owned EC2 instances managed by Lambda Managed Instances.

Type: CapacityProviderConfig

Required: No

CloudFormation compatibility: SAM flattens the property passed to the CapacityProviderConfig property of an AWS::Lambda::Function resource and reconstructs the nested structure.

CodeSigningConfigArn

The ARN of the AWS::Lambda::CodeSigningConfig resource, used to enable code signing for this function. For more information about code signing, see Set up code signing for your AWS SAM application.

Type: String

Required: No

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

CodeUri

The code for the function. Accepted values include:

The function's Amazon S3 URI. For example, s3://bucket-123456789/sam-app/1234567890abcdefg.
The local path to the function. For example, hello_world/.
A FunctionCode object.

Note

If you provide a function's Amazon S3 URI or FunctionCode object, you must reference a valid Lambda deployment package.

If you provide a local file path, use the AWS SAM CLI to upload the local file at deployment. To learn more, see How AWS SAM uploads local files at deployment.

If you use intrinsic functions in CodeUri property, AWS SAM will not be able to correctly parse the values. Consider using AWS::LanguageExtensions transform instead.

Type: [ String | FunctionCode ]

Required: Conditional. When PackageType is set to Zip, one of CodeUri or InlineCode is required.

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 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 Dead-letter queues in the AWS Lambda Developer Guide.

Note

If your Lambda function's event source is an Amazon SQS queue, configure a dead-letter queue for the source queue, not for the Lambda function. The dead-letter queue that you configure for a function is used for the function's asynchronous invocation queue, not for event source queues.

Type: Map | DeadLetterQueue

Required: No

CloudFormation compatibility: This property is similar to the DeadLetterConfig property of an AWS::Lambda::Function resource. In 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

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

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

Description

A description of the function.

Type: String

Required: No

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

DurableConfig

Configuration for durable functions. Enables stateful execution with automatic checkpointing and replay capabilities.

Type: DurableConfig

Required: No

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

Environment

The configuration for the runtime environment.

Type: Environment

Required: No

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

EphemeralStorage

An object that specifies the disk space, in MB, available to your Lambda function in /tmp.

For more information about this property, see Lambda execution environment in the AWS Lambda Developer Guide.

Type: EphemeralStorage

Required: No

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

EventInvokeConfig

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

Type: EventInvokeConfiguration

Required: No

CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an 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

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

FileSystemConfigs

List of FileSystemConfig objects that specify the connection settings for an Amazon Elastic File System (Amazon EFS) file system or an Amazon S3 Files file system. You can attach either an Amazon EFS access point or an S3 Files access point, but not both.

Each FileSystemConfig object contains an Arn (the access point ARN) and a LocalMountPath (the path where the file system is mounted in the function). For Amazon EFS, the ARN is an Amazon EFS access point ARN. For S3 Files, the ARN is an AWS::S3Files::AccessPoint ARN.

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. Similarly, if your template contains an AWS::S3Files::MountTarget resource, you must specify a DependsOn attribute for the S3 Files mount target.

Type: List

Required: No

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

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

FunctionScalingConfig

Configures the scaling behavior for Lambda functions running on capacity providers. Defines the minimum and maximum number of execution environments.

Type: FunctionScalingConfig

Required: No

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

FunctionUrlConfig

The object that describes a function URL. A function URL is an HTTPS endpoint that you can use to invoke your function.

For more information, see Function URLs in the AWS Lambda Developer Guide.

Type: FunctionUrlConfig

Required: No

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

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

CloudFormation compatibility: This property is passed directly to the 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

CloudFormation compatibility: This property is passed directly to the 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 Default build with AWS SAM.

Building your application with necessary Metadata entries takes precedence over ImageUri, so if you specify both then ImageUri is ignored.

Type: String

Required: No

CloudFormation compatibility: This property is passed directly to the 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

CloudFormation compatibility: This property is passed directly to the 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

CloudFormation compatibility: This property is passed directly to the 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. The version is either a full ARN including the version or a reference to a LayerVersion resource. For example, a reference to a LayerVersion will be