Lambda Canary Deploys: Route Traffic with Aliases (2026)

Lambda aliases are the secret sauce behind canary deployments, allowing you to gradually shift production traffic from one version of your Lambda function to another.

Let’s see this in action. Imagine you have a Lambda function, my-api-handler, currently pointed to by a production alias named PROD. This alias directs 100% of traffic to version 1 of your function.

{
  "FunctionName": "my-api-handler",
  "AliasName": "PROD",
  "FunctionVersion": "1",
  "Description": "Production alias",
  "RoutingConfig": {
    "AdditionalVersionWeights": {}
  }
}

Now, you deploy a new version of your function, version 2. You want to test this new version with a small percentage of your users before committing to a full rollout. You create a new alias, let’s call it BETA, that points 100% of its traffic to version 2.

{
  "FunctionName": "my-api-handler",
  "AliasName": "BETA",
  "FunctionVersion": "2",
  "Description": "New feature beta",
  "RoutingConfig": {
    "AdditionalVersionWeights": {}
  }
}

This is where the magic of Lambda aliases for canary deployments really shines. You can update your PROD alias to start sending a small percentage of traffic to version 2 in addition to version 1.

Let’s say you want to send 10% of traffic to version 2 and keep 90% on version 1. You’d update the PROD alias like this:

aws lambda update-alias \
    --function-name my-api-handler \
    --name PROD \
    --function-version 1 \
    --routing-config additionalVersionWeights={2=10}

Notice that you specify the primary version (--function-version 1) which will receive the remaining traffic (90% in this case), and then use --routing-config additionalVersionWeights to specify the percentage of traffic directed to other versions. The values in additionalVersionWeights are percentages, and they sum up to 100% along with the primary version.

Your PROD alias now looks like this internally:

{
  "FunctionName": "my-api-handler",
  "AliasName": "PROD",
  "FunctionVersion": "1", // Primary version
  "Description": "Production alias",
  "RoutingConfig": {
    "AdditionalVersionWeights": {
      "2": 10 // 10% of traffic goes to version 2
    }
  }
}

This means that 90% of requests made to arn:aws:lambda:us-east-1:123456789012:alias:my-api-handler:PROD will execute version 1 of your function, and 10% will execute version 2. You can monitor version 2 for errors, performance regressions, or unexpected behavior using CloudWatch metrics and logs.

If version 2 proves stable, you can gradually increase the traffic percentage. For example, to shift to 50% on version 2:

aws lambda update-alias \
    --function-name my-api-handler \
    --name PROD \
    --function-version 1 \
    --routing-config additionalVersionWeights={2=50}

The PROD alias now sends 50% to version 1 and 50% to version 2.

Once you’re confident, you can promote version 2 to be the sole recipient of traffic by setting the primary version and removing additional weights.

aws lambda update-alias \
    --function-name my-api-handler \
    --name PROD \
    --function-version 2 \
    --routing-config additionalVersionWeights={}

The PROD alias now exclusively points to version 2.

The key insight here is that the alias is the stable endpoint that your applications call. You don’t change your application’s configuration to point to different function versions. Instead, you reconfigure the alias that the application is already pointing to. This allows for zero-downtime deployments and a safe way to roll out new code.

The actual traffic routing logic isn’t handled by the Lambda service itself in terms of a load balancer; rather, when a request hits the alias ARN, Lambda’s internal routing mechanism consults the alias configuration and directs the request to the appropriate version based on the defined weights. This allows for fine-grained control over traffic distribution without external infrastructure.

The next step in managing your deployments is often implementing automated rollback strategies when canary metrics indicate a problem.