Managing Lambda Versions and Aliases: A Deployment Guide

Previously in this course, we explored Managing Lambda Execution Environments: Memory, Timeouts, and Roles. While we now know how to configure a single function effectively, we've been treating our code as a "live" target. In this lesson, we add the ability to freeze specific states of our code and manage them using Aliases, ensuring our production environment remains stable while we iterate.

Understanding Lambda Versioning and Aliases

In production environments, you never want to overwrite your running code directly. If you push a bug, your entire application goes down instantly.

AWS Lambda solves this with two core concepts:

1. Versions: An immutable snapshot of your code and configuration (memory, timeout, environment variables). Once published, a version cannot be changed.
2. Aliases: A mutable "pointer" that directs traffic to a specific version. Think of an alias as a bookmark like PROD or STAGING that you can move from one version to another.

By using these, you decouple the trigger (like your API Gateway) from the code. You point your API to an alias, and then simply update the alias to point to a new version when you are ready.

How to Publish a Lambda Version

When you deploy a change, you have the option to publish a new version. This creates a numbered copy (starting at 1) of your function.

Worked Example: Publishing via AWS CLI

Assuming you have your project from the previous lessons, you can publish a version using the CLI. If you haven't set up the tools yet, check out our guide on Configuring the AWS CLI.

Bash
# Publish a new version of your function
aws lambda publish-version --function-name my-web-app-backend

The output will include a Version number (e.g., "Version": "2"). This version is now locked. Even if you update the code for my-web-app-backend later, version 2 will remain exactly as it was at the moment of publishing.

Managing Traffic with Aliases

Once you have versions, you need a way to reference them without constantly updating your API Gateway configuration. This is where Aliases shine.

Creating and Updating an Alias

You can create an alias named PROD that points to your stable version.

1. Create the Alias:

   Bash
   aws lambda create-alias \
     --function-name my-web-app-backend \
     --name PROD \
     --function-version 1
   

2. Update the Alias: When you are ready to promote version 2 to production, you update the pointer:

   Bash
   aws lambda update-alias \
     --function-name my-web-app-backend \
     --name PROD \
     --function-version 2
   

By pointing your API Gateway to the ARN (Amazon Resource Name) of your alias—which looks like arn:aws:lambda:region:account:function:my-function:PROD—you can swap the underlying code instantly without modifying the API Gateway settings.

Comparison: Versioning vs. Aliases

Hands-on Exercise

1. Publish a version: Use the AWS Console or CLI to publish a new version of your backend function.
2. Create an alias: Create an alias named STAGING and point it to that version.
3. Verify: Invoke the alias specifically using the CLI: aws lambda invoke --function-name my-function:STAGING response.json
4. Update: Make a small change to your function's environment variables, publish version 3, and update the STAGING alias to point to it.

Common Pitfalls

• Forgetting to update Aliases: If you update your function code but forget to publish a new version and point your alias to it, your production users will still be running the old code.
• Environment Variable Confusion: Remember that environment variables are locked into the version. If you update an environment variable in the "Latest" configuration, it does not affect previously published versions.
• Over-versioning: Don't publish a version for every single save. Use your CI/CD pipeline to publish versions automatically when code is merged to your main branch.

FAQ

Can I delete a version? Yes, but only if no aliases are pointing to it. You must update your aliases to point to a different version before you can delete an old, unused snapshot.

Does this help with Managing Breaking Changes in REST API Design? Yes. By using aliases, you can maintain a v1 and v2 alias for your functions, allowing you to run different versions of your API logic simultaneously while you migrate clients.

Recap

We have successfully moved from treating our code as a single moving target to managing immutable snapshots. By using publish-version and update-alias, we gain the ability to deploy with confidence, knowing we can roll back to a previous version in seconds if something goes wrong.

Up next

In the next lesson, we will leverage these aliases to perform Blue/Green Deployments with Lambda, where we shift traffic gradually between versions to minimize risk.