Menu
AWS Lambda
Developer Guide

Introduction to AWS Lambda Versioning

This section explains how to create a Lambda function and publish a version from it. It also explains how to update function code and configuration information when you have one or more published versions. In addition, this section includes information on how to delete function versions, either specific versions or the entire Lambda function (with all of its versions and associated aliases).

Creating a Lambda Function (the $LATEST version)

When you create a Lambda function, there is only one version. It is the $LATEST version.

You can refer to this function using its Amazon Resource Name (ARN). There are two ARNs associated with this initial version:

  • Qualified ARN – The function ARN with the version suffix.

    Copy
    arn:aws:lambda:aws-region:acct-id:function:helloworld:$LATEST
  • Unqualified ARN – The function ARN without the version suffix.

    You can use this ARN in all relevant operations however you cannot use it to create an alias. For more information, see Introduction to AWS Lambda Aliases.

    The unqualified ARN has its own resource policies.

    Copy
    arn:aws:lambda:aws-region:acct-id:function:helloworld

Note

Unless you choose to publish versions, the $LATEST version is the only Lambda function version you have. You can use either the qualified or unqualified ARN in your event source mapping to invoke this $LATEST version.

The following is an example response of a CreateFunction API call:

Copy
{ "CodeSize": 287, "Description": "test function." "FunctionArn": "arn:aws:lambda:aws-region:acct-id:function:helloworld", "FunctionName": "helloworld", "Handler": "helloworld.handler", "LastModified": "2015-07-16T00:34:31.322+0000", "MemorySize": 128, "Role": "arn:aws:iam::acct-id:role/lambda_basic_execution", "Runtime": "nodejs6.10", "Timeout": 3, "CodeSHA256": "OjRFuuHKizEE8tHFIMsI+iHR6BPAfJ5S0rW31Mh6jKg=", "Version": "$LATEST" }

For more information, see CreateFunction.

In this response, AWS Lambda returns the unqualified ARN of the newly created function as well as its version, $LATEST. The response also shows that the Version is $LATEST. The CodeSha256 is the checksum of the deployment package that you uploaded.

Publishing a Lambda Function Version

When you publish a version, AWS Lambda makes a snapshot copy of the Lambda function code (and configuration) in the $LATEST version. A published version is immutable. That is, you can't change the code or configuration information. The new version has a unique ARN that includes a version number suffix as shown:

You can publish a version using any of the following methods:

  • Publish a version explicitly – Use the PublishVersion API to explicitly publish a version. For more information, see PublishVersion. This action creates a new version using the code and configuration in the $LATEST version.

  • Publish a version at the time you create or update a Lambda function – Use the CreateFunction or UpdateFunctionCode requests to also publish a version by adding the optional publish parameter in the request:

    • Specify the publish parameter in your CreateFunction request to create a new Lambda function (the $LATEST version), and then immediately publish it by creating a snapshot and assigning it to be version 1. For more information about CreateFunction, see CreateFunction.

    • Specify the publish parameter in your UpdateFunctionCode request to update the code in the $LATEST version, and then publish a version from the $LATEST. For more information about UpdateFunctionCode, see UpdateFunctionCode.

    If you specify the publish parameter at the time you create a Lambda function, the function configuration information that AWS Lambda returns in response shows the version number of the newly published version, as shown following (in the example, the version is 1):

    Copy
    { "CodeSize": 287, "Description": "test function." "FunctionArn": "arn:aws:lambda:aws-region:acct-id:function:helloworld", "FunctionName": "helloworld", "Handler": "helloworld.handler", "LastModified": "2015-07-16T00:34:31.322+0000", "MemorySize": 128, "Role": "arn:aws:iam::acct-id:role/lambda_basic_execution", "Runtime": "nodejs6.10", "Timeout": 3, "CodeSHA256": "OjRFuuHKizEE8tHFIMsI+iHR6BPAfJ5S0rW31Mh6jKg=", "Version": "1" }

Note

Lambda will only publish a new version if the code has not yet been published or if the code has changed when compared against the $LATEST version. If there is no change, the $LATEST published version will be returned.

We recommend that you publish a version at the same time that you create your Lambda function or update your Lambda function code, especially when multiple developers contribute to the same Lambda function development. You can use the publish parameter in your request to do this. When you have multiple developers working on a project, it is possible for developer A to create a Lambda function ($LATEST version) and before developer A publishes a version, developer B updates the code (deployment package) associated with the $LATEST version. In this case, you lose the original code that developer A uploaded. When both developers add the publish parameter it prevents the race condition described.

Note

The published versions are immutable. That is, you cannot change code or configuration information associated with a version.

Each version of a Lambda function is a unique resource with a Amazon Resource Name (ARN). The following example shows the ARN of version number 1 of the helloworld Lambda function:

Copy
arn:aws:lambda:aws-region:acct-id:function:helloworld:1

Note

This is a qualified ARN, where the version number is a suffix. Published versions can have only qualified ARN.

You can publish multiple versions. Each time you publish a version, AWS Lambda copies $LATEST version (code and configuration information) to create a new version. When you publish additional versions, AWS Lambda assigns a monotonically increasing sequence number for versioning, even if the function was deleted and re-created. Version numbers are never reused, even for a function that has been deleted and re-created, so that the consumer of that version can depend on the executable of that version to never change (except if it's deleted). If you want to re-use a qualifier, use aliases with your versions. Aliases can be deleted and re-created with the same name.

Updating Lambda Function Code and Configuration

AWS Lambda maintains your latest function code in the $LATEST version. When you update your function code, AWS Lambda replaces the code in the $LATEST version of the Lambda function. For more information, see UpdateFunctionCode.

Published versions are immutable. You cannot update code or configuration information associated with a published version.

You have the following options of publishing a new version as you update your Lambda function code:

  • Publish a version in the same update code request – Use the UpdateFunctionCode API (recommended).

  • First update the code, and then explicitly publish a version – Use the PublishVersion API.

You can update code and configuration information (such as description, memory size, and execution timeout) of the $LATEST version of the Lambda function. However, published versions are immutable. That is, you cannot change code or configuration information.

Deleting a Lambda Function and a Specific Version

With versioning, you have the following choices:

  • Delete a specific version – You can delete a Lambda function version by specifying the version you want to delete in your DeleteFunction request. If there are aliases dependent on this version, the request will fail. AWS Lambda deletes the version only if there are no aliases dependent on this version. For more information about aliases, see Introduction to AWS Lambda Aliases.

  • Delete the entire Lambda function (all of its versions and aliases) – To delete the Lambda function and all of its versions, do not specify any version in your DeleteFunction request. This deletes the entire function including all of its versions and aliases.

Important

You can delete a specific function version, but you cannot delete the $LATEST.

Introduction to AWS Lambda Aliases

Managing Versioning Using the AWS Management Console, the AWS CLI, or Lambda APIs