The ultimate guide to AWS Lambda Alias

Published on: Mon May 09 2022




AWS Lambda Alias is a feature that makes it easier to manage your Lambda function versions.

It works by creating a “container” which points to a published version of your Lambda function.

There are several benefits to this.


  • You can have safer deployments in your Software Development Lifecycle (SDLC)
  • You can have dynamic references Lambda function versions

In this guide, we will talk about the existing versioning strategies used by AWS Lambda then look at why Lambda alias is a better choice.

Let’s dive right in.

Existing versioning

Immutable versions

By default, when you publish changes on your Lambda function, it creates a new version.

This new version is considered to be immutable, meaning that you cannot change it’s identifier (ARN) or the function code once it is published.

Understanding $LATEST

In addition to the immutability of the versions, AWS Lambda automatically promotes the latest version to a default alias $LATEST .

This is important to understand the later sections when we start to discuss the AWS resource identifier (ARN) used when referencing a lambda resource.

Understanding the Lambda ARN

Within AWS, each resource can be identified with an unique resource identifier (ARN).

With Lambda, it is the same but it does has some subtle differences.

Lambda separates the AWS resource identifier (ARN) into two types:

  • Qualified ARN - versioned
  • Unqualified ARN (Default) - does not include version (points to $LATEST alias)

It is important to distinguish between the two because it will determine which lambda function version they will reference.

When you use a ”qualified ARN”, you are referencing a specific version of lambda.

While, the ”unqualified ARN” is a reference to the latest version of lambda function (this is done via the $LATEST alias).

The difference is quite subtle but it is important to make the distinction because you may reference a lambda ARN and then have it change when someone else makes a new code change.

Each of these have their respective pros and cons which we will discuss in the next section.

Example (qualified ARN):


Example (unqualified ARN):

⚠️ An Unqualified Lambda ARN will always point to the latest published version via the $LATEST alias

Pros and Cons

Static versioning (qualified ARN)

lambda qualified alias

The biggest pro of static versioning is also it’s biggest con.

With static versioning, you do have more control over which version of the lambda function you will be pointing to.

This allows for safer deployments because you decide which versions are promoted in your infrastructure.

However, this also locks you in, and requires you make subsequent updates to any resources referencing it (ie api gateway, event source integrations).


  • Safe deployments


  • Subsequent updates required for resources

Dynamic versioning - $LATEST (unqualified ARN)

lambda unqualified alias

This is the opposite of static versioning where you have a lot of flexibility in terms of referencing the lambda function versions because it always gets updated via $LATEST .

However, this workflow may be risky because you are automatically promoting any new version of your lambda function into a live environment without any testing.


  • Subsequent updates are not required for resources


  • Risky deployments (latest versions are always used)

In a typical Software development lifecycle (SDLC), ideally, you will go through the build and then do some testing then go live once you are ready.

So, is there a better choice ?

Yes, of course! This is where AWS Lambda alias comes in.

What makes AWS Lambda Alias different ?

lambda alias dev

AWS lambda alias is a custom named “container” that points to a specific version of your lambda function.

The version referenced in an alias can be updated at anytime.

This gives you the flexibility as well as the safety because you can promote a version whenever it is considered ready to go live.

In addition, any references to the alias will always point to a target version.

So, with this setup, there is no need to make updates to any other resource referencing the ARN!


  • Subsequent updates are not required for other resources
  • Safe deployments (you are in control of the reference)

With the AWS Lambda alias, you get the best of both worlds!

AWS Lambda Alias example

Here is an example of using the AWS lambda alias.

In your workflow, you can have separate stages (or alias) which can be:

  • dev - for development and testing purposes
  • prod - for live environment
lambda alias example

Then as you run your CI/CD, you can update each of the alias accordingly.

The workflows will depend on the CI tool.

Using the AWS CLI, you can achieve this by running:

aws lambda update-alias \
    --function-name "myFunction" \
    --name "prod" \
    --function-version "2"

AWS Lambda Alias IAM Gotcha

There is a small gotcha with with AWS Lambda Alias, and it is related what you need to reference in your IAM permissions and policies.

  • Event source (API gateway, event triggers etc) - should reference the ARN of the lambda alias to provide invoke permissions
  • Run time permissions (Access to S3, DB etc) - should reference the ARN of the lambda function
Lambda ARN reference difference when using an alias
Just keep this in mind when using AWS Lambda Alias ❗️

Advanced deployments

Traffic shifting configuration

lambda alias traffic shifting

There are also other benefits with using AWS Lambda alias, these include advanced deployment patterns which AWS offers natively.

By default, the AWS CLI for lambda supports traffic shifting (or weighted deployment) where you can split the traffic between two versions using a percentage (%).

Using the AWS CLI, you can achieve this by running:

aws lambda update-alias \
    --function-name "myFunction" \
    --name "prod" \
    --function-version "2" \
    --routing-config AdditionalVersionWeights={"2"=0.1}

This means 10% traffic will be shifted to version 2 while rest of the 90% will stay on version 1.

AWS Codedeploy

AWS Codedeploy also supports lambda releases with canary deployments where you can delegate deployment to codedeploy.

It will still make use the traffic shifting, however, the eventual goal is to shift 100% over to the target resource.

AWS Codedeploy also supports automatic rollback based on cloudwatch metrics during the canary rollout phase.


To recap, AWS Lambda alias bridges the gap between the existing solutions using static and dynamic versioning.

This allows for flexibility the version promotion hence the safety in the deployments.

Finally, any references to the lambda ARN do not need to be updated when using an alias!

This makes it a much better choice in general, you get the best of both worlds!

Here is a quick summary of the versioning strategies:

Lambda Alias versioning comparison

That’s all, I hope that was helpful!

Enjoy the content ?

Then consider signing up to get notified when new content arrives!

Jerry Chang 2023. All rights reserved.