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 AWS CloudFormation resources. For more information, see Generated AWS 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
CodeSigningConfigArn:String
CodeUri:String | FunctionCode
DeadLetterQueue:Map | DeadLetterQueue
DeploymentPreference:DeploymentPreference
Description:String
Environment:Environment
EphemeralStorage:EphemeralStorage
EventInvokeConfig:EventInvokeConfiguration
Events:EventSource
FileSystemConfigs:List
FunctionName:String
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
PropagateTags:Boolean
ProvisionedConcurrencyConfig:ProvisionedConcurrencyConfig
RecursiveLoop:String
ReservedConcurrentExecutions:Integer
Role:String
RolePath:String
Runtime:String
RuntimeManagementConfig:RuntimeManagementConfig
SnapStart:SnapStart
SourceKMSKeyArn:String
Tags:Map
Timeout:Integer
Tracing:String
VersionDescription: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
orarm64
Type: List
Required: No
Default:
x86_64
AWS CloudFormation compatibility: This property is passed directly to the
Architectures
property of anAWS::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
AWS CloudFormation compatibility: This property is similar to the
AssumeRolePolicyDocument
property of anAWS::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 AWS CloudFormation resources, see Generated AWS CloudFormation resources for AWS SAM.
Type: String
Required: No
AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.
-
AutoPublishAliasAllProperties
-
Specifies when a new
AWS::Lambda::Version
is created. Whentrue
, a new Lambda version is created when any property in the Lambda function is modified. Whenfalse
, a new Lambda version is created only when any of the following properties are modified:-
Environment
,MemorySize
, orSnapStart
. -
Any change that results in an update to the
Code
property, such asCodeDict
,ImageUri
, orInlineCode
.
This property requires
AutoPublishAlias
to be defined.If
AutoPublishSha256
is also specified, its behavior takes precedence overAutoPublishAliasAllProperties: true
.Type: Boolean
Required: No
Default value:
false
AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS 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 theCodeUri
property remains unchanged (as opposed to the new deployment package being uploaded to a new Amazon S3 location and theCodeUri
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 deploymentsThe
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 theVersion
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
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 Set up code signing for your AWS SAM application.
Type: String
Required: No
AWS CloudFormation compatibility: This property is passed directly to the
CodeSigningConfigArn
property of anAWS::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 toZip
, one ofCodeUri
orInlineCode
is required.AWS CloudFormation compatibility: This property is similar to the
Code
property of anAWS::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
AWS CloudFormation compatibility: This property is similar to the
DeadLetterConfig
property of anAWS::Lambda::Function
resource. In AWS CloudFormation the type is derived from theTargetArn
, whereas in AWS SAM you must pass the type along with theTargetArn
. -
DeploymentPreference
-
The settings to enable gradual Lambda deployments.
If a
DeploymentPreference
object is specified, AWS SAM creates an AWS::CodeDeploy::Application calledServerlessDeploymentApplication
(one per stack), an AWS::CodeDeploy::DeploymentGroup called
, and an AWS::IAM::Role called<function-logical-id>
DeploymentGroupCodeDeployServiceRole
.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 with AWS SAM.
-
Description
-
A description of the function.
Type: String
Required: No
AWS CloudFormation compatibility: This property is passed directly to the
Description
property of anAWS::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 anAWS::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
AWS CloudFormation compatibility: This property is passed directly to the
EphemeralStorage
property of anAWS::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
property of anAWS::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 anAWS::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
AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS 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 toZip
.Type: String
Required: Conditional
AWS CloudFormation compatibility: This property is passed directly to the
Handler
property of anAWS::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
property of anAWS::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 toImage
, 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 toImage
, then eitherImageUri
is required, or you must build your application with necessaryMetadata
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 overImageUri
, so if you specify both thenImageUri
is ignored.Type: String
Required: No
AWS CloudFormation compatibility: This property is passed directly to the
ImageUri
property of theAWS::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 toZip
, otherwise it is ignored.Note
If the
PackageType
property is set toZip
(default), then one ofCodeUri
orInlineCode
is required.Type: String
Required: Conditional
AWS CloudFormation compatibility: This property is passed directly to the
ZipFile
property of theAWS::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
property of anAWS::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
property of anAWS::Lambda::Function
resource. -
LoggingConfig
-
The function's Amazon CloudWatch Logs configuration settings.
Type: LoggingConfig
Required: No
AWS CloudFormation compatibility: This property is passed directly to the
LoggingConfig
property of anAWS::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
property of anAWS::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 eitherCodeUri
orInlineCode
applies, andImageUri
is ignored.2. If this property is set to
Image
, then onlyImageUri
applies, and bothCodeUri
andInlineCode
are ignored. The Amazon ECR repository required to store the function's container image can be auto created by the AWS SAM CLI. For more information, see sam deploy.Valid values:
Zip
orImage
Type: String
Required: No
Default:
Zip
AWS CloudFormation compatibility: This property is passed directly to the
PackageType
property of anAWS::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
property of anAWS::IAM::Role
resource. -
Policies
-
Permission policies for this function. Policies will be appended to the function's default AWS Identity and Access Management (IAM) execution role.
This property accepts a single value or list of values. Allowed values include:
-
The ARN of an AWS managed policy or customer managed policy.
-
The name of an AWS managed policy from the following list
. -
An inline IAM policy formatted in YAML as a map.
Note
If you set the
Role
property, this property is ignored.Type: String | List | Map
Required: No
AWS CloudFormation compatibility: This property is similar to the
Policies
property of anAWS::IAM::Role
resource. -
Indicate whether or not to pass tags from the
Tags
property to your AWS::Serverless::Function generated resources. SpecifyTrue
to propagate tags in your generated resources.Type: Boolean
Required: No
Default:
False
AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.
-
ProvisionedConcurrencyConfig
-
The provisioned concurrency configuration of a function's alias.
Note
ProvisionedConcurrencyConfig
can be specified only if theAutoPublishAlias
is set. Otherwise, an error results.Type: ProvisionedConcurrencyConfig
Required: No
AWS CloudFormation compatibility: This property is passed directly to the
ProvisionedConcurrencyConfig
property of anAWS::Lambda::Alias
resource. -
ProvisionedConcurrencyConfig
-
The provisioned concurrency configuration of a function's alias.
Note
ProvisionedConcurrencyConfig
can be specified only if theAutoPublishAlias
is set. Otherwise, an error results.Type: ProvisionedConcurrencyConfig
Required: No
AWS CloudFormation compatibility: This property is passed directly to the
ProvisionedConcurrencyConfig
property of anAWS::Lambda::Alias
resource. -
RecursiveLoop
-
The status of your function's recursive loop detection configuration.
When this value is set to
Allow
and Lambda detects your function being invoked as part of a recursive loop, it doesn't take any action.When this value is set to
Terminate
and Lambda detects your function being invoked as part of a recursive loop, it stops your function being invoked and notifies you.Type: String
Required: No
AWS CloudFormation compatibility: This property is passed directly to the
RecursiveLoop
property of theAWS::Lambda::Function
resource. -
ReservedConcurrentExecutions
-
The maximum number of concurrent executions that you want to reserve for the function.
For more information about this property, see 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 anAWS::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 anAWS::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 -
RolePath
-
The path to the function's IAM execution role.
Use this property when the role is generated for you. Do not use when the role is specified with the
Role
property.Type: String
Required: Conditional
AWS CloudFormation compatibility: This property is passed directly to the
Path
property of anAWS::IAM::Role
resource. -
Runtime
-
The identifier of the function's runtime. This property is only required if the
PackageType
property is set toZip
.Note
If you specify the
provided
identifier for this property, you can use theMetadata
resource attribute to instruct AWS SAM to build the custom runtime that this function requires. For more information about building custom runtimes, see Building Lambda functions with custom runtimes in AWS SAM.Type: String
Required: Conditional
AWS CloudFormation compatibility: This property is passed directly to the
Runtime
property of anAWS::Lambda::Function
resource. -
RuntimeManagementConfig
-
Configure runtime management options for your Lambda functions such as runtime environment updates, rollback behavior, and selecting a specific runtime version. To learn more, see Lambda runtime updates in the AWS Lambda Developer Guide.
Type: RuntimeManagementConfig
Required: No
AWS CloudFormation compatibility: This property is passed directly to the
RuntimeManagementConfig
property of anAWS::Lambda::Function
resource. -
SnapStart
-
Create a snapshot of any new Lambda function version. A snapshot is a cached state of your initialized function, including all of its dependencies. The function is initialized just once and the cached state is reused for all future invocations, improving application performance by reducing the number of times your function must be initialized. To learn more, see Improving startup performance with Lambda SnapStart in the AWS Lambda Developer Guide.
Type: SnapStart
Required: No
AWS CloudFormation compatibility: This property is passed directly to the
SnapStart
property of anAWS::Lambda::Function
resource. -
SourceKmsKeyArn
-
Represents a KMS key ARN that is used to encrypt the customer's ZIP function code.
Type: String
Required: No
AWS CloudFormation compatibility: This property is passed directly to the
SourceKmsKeyArn
property of anAWS::Lambda::Function
Code
data type. -
A map (string to string) that specifies the tags added to this function. For details about valid keys and values for tags, see Tag Key and Value Requirements in the AWS Lambda Developer Guide.
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
property of anAWS::Lambda::Function
resource. TheTags
property in AWS SAM consists of key-value pairs (whereas in AWS CloudFormation this property consists of a list ofTag
objects). Also, AWS SAM automatically adds alambda: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
property of anAWS::Lambda::Function
resource. -
Tracing
-
The string that specifies the function's X-Ray tracing mode.
-
Active
– Activates X-Ray tracing for the function. -
Disabled
– Deactivates X-Ray for the function. -
PassThrough
– Activates X-Ray tracing for the function. Sampling decision is delegated to the downstream services.
If specified as
Active
orPassThrough
and theRole
property is not set, AWS SAM adds thearn:aws:iam::aws:policy/AWSXrayWriteOnlyAccess
policy to the Lambda execution role that it creates for you.For more information about X-Ray, see Using AWS Lambda with AWS X-Ray in the AWS Lambda Developer Guide.
Valid values: [
Active
|Disabled
|PassThrough
]Type: String
Required: No
AWS CloudFormation compatibility: This property is similar to the
TracingConfig
property of anAWS::Lambda::Function
resource. -
-
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 anAWS::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
property of anAWS::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 ARN of the underlying Lambda function.
Examples
Simple 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.
YAML
Type: AWS::Serverless::Function Properties: Handler: index.handler Runtime: python3.9 CodeUri: s3://
bucket-name
/key-name
Function properties example
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.
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.9 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:::
amzn-s3-demo-bucket
/*' Events: ApiEvent: Type: Api Properties: Path: /path Method: get
ImageConfig example
The following is an example of an ImageConfig
for a Lambda function of
package type Image
.
YAML
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
"
RuntimeManagementConfig examples
A Lambda function configured to update its runtime environment according to current behavior:
TestFunction Type: AWS::Serverless::Function Properties: ... Runtime: python3.9 RuntimeManagementConfig: UpdateRuntimeOn: Auto
A Lambda function configured to update its runtime environment when the function is updated:
TestFunction Type: AWS::Serverless::Function Properties: ... Runtime: python3.9 RuntimeManagementConfig: UpdateRuntimeOn: FunctionUpdate
A Lambda function configured to update its runtime environment manually:
TestFunction Type: AWS::Serverless::Function Properties: ... Runtime: python3.9 RuntimeManagementConfig: RuntimeVersionArn: arn:aws:lambda:us-east-1::runtime:4c459dd0104ee29ec65dcad056c0b3ddbe20d6db76b265ade7eda9a066859b1e UpdateRuntimeOn: Manual
SnapStart examples
Example of a Lambda function with SnapStart turned on for future versions:
TestFunc Type: AWS::Serverless::Function Properties: ... SnapStart: ApplyOn: PublishedVersions