Versions and Aliases

When you deployed the example stack, SAM wired the API gateway to use the $LATEST version of your Lambda function. That’s OK for a simple case, but it might be problematic for backwards incompatible deployments in the future. Updating a distributed architecture is not instantaneous. You don’t want the API to somehow get updated first and then send a new version of an event to an older version of the function. Lambda and API Gateway charge for requests, not for the number of environments, so there is no special cost for keeping an old copy around while the new one is being created. With container-based application hosts, the only solution to this problem would be to create a completely different stack and then switch request routing on the load balancer to the new environment at the end of deployment. With Lambda, it’s easy to do that even with a single stack.

Published versions #

You can tell Lambda to keep a configured version by publishing it. Published versions are read-only copies of function configurations and they are not wiped out after a subsequent update. An event source can request that a particular published function version handles its events. That way, old deployments of the API Gateway can ask for the old Lambda code, and new deployments can ask for the new Lambda function. During an update, any events aimed at the previous version will just keep running on old containers. Once no events have requested an old version for a while, Lambda will remove those instances. When an event targets the new version, Lambda will create a new container using the newly published configuration.

Aliases #

To make deployments safe, you need to make sure that events target a particular version, not $LATEST. Each published configuration version has a unique numerical ID, assigned by Lambda incrementally with each deployment. In theory, you could manually keep track of these, ensure that event sources request a particular numerical version, and update the template before each deployment to rewire event sources, but this would be error-prone and laborious. Lambda allows you to declare configuration aliases, meaningful names pointing to a numerical version. For example, you can create an alias called live to represent a published configuration version and set up all event sources to request that alias. After an application update, you do not need to rewire event sources. You just need to point the alias to the new numerical version.