AWS Lambda Alias: An Essential Guide  by@jerrychang

AWS Lambda Alias: An Essential Guide

Jerry HackerNoon profile picture


cloud, aws, javascript, react, dev tips


  • Introduction
  • Existing versioning
    • Immutable Versions
    • Understanding $LATEST
  • Understanding the Lambda ARN
  • Pros and Cons
    • Static versioning qualified ARN
    • Dynamic versioning $LATEST
  • What Makes AWS Lambda Alias different?
  • Mapping out the AWS compute solutions
  • AWS Lambda Alias Example
  • AWS Lambda Alias IAM Gotcha
  • Advanced deployments
    • Traffic shifting
    • AWS Codedeploy
  • Conclusion


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

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

There are a few 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, and then look at why AWS 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 its 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 in 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 a unique resource identifier (ARN).

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

AWS 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 they determine which lambda function version they will reference.

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

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

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

Each of these has its 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)


The biggest pro of static versioning is also its biggest con.

With static versioning, you do have more control over which version of the AWS 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 to make subsequent updates to any resources referencing it (i.e. API gateway, event source integrations).


  • Safe deployments


  • Subsequent updates are required for resources

Dynamic versioning - $LATEST (unqualified ARN)


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 (continuous integration) 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 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 any time.

This gives you flexibility as well as 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 Lambda alias, you get the best of both worlds!

AWS Lambda Alias example

Here is an example of using a 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


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 AWS Lambda Alias, and it is related to 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


Just keep this in mind when using AWS Lambda Alias ❗️

Advanced deployments

Traffic shifting configuration


There are also other benefits to using a 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% of traffic will be shifted to version 2 while the 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 AWS Codedeploy.

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

AWS Codedeploy also supports automatic rollback based on AWS 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 when promoting the versions, hence the safety of the deployments.

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

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

Here is a quick summary of the versioning strategies:



Signup or Login to Join the Discussion


Related Stories