Create a routing configuration for a Lambda alias
Use a routing configuration on an alias to send a portion of traffic to a second function version. For example,
you can reduce the risk of deploying a new version by configuring the alias to send most of the traffic to the
existing version, and only a small percentage of traffic to the new version.
Lambda uses a simple probabilistic model to distribute the traffic between the two function versions.
At low traffic levels, you might see a high variance between the configured and actual percentage of traffic on
each version. If your function uses provisioned concurrency, you can avoid spillover invocations by configuring a higher number of
provisioned concurrency instances during the time that alias routing is active.
You can point an alias to a maximum of two Lambda function versions. The versions must meet the following
criteria:
-
Both versions must have the same execution role.
-
Both versions must have the same dead-letter queue
configuration, or no dead-letter queue configuration.
-
Both versions must be published. The alias cannot point to $LATEST
.
- Console
-
To configure routing on an alias using the console
Open the Functions page of the Lambda console.
-
Choose a function.
-
Choose Aliases and then choose Create alias.
-
On the Create alias page, do the following:
-
Enter a Name for the alias.
-
(Optional) Enter a Description for the alias.
-
For Version, choose the first function version that you want the alias to point
to.
-
Expand Weighted alias.
-
For Additional version, choose the second function version that you want the
alias to point to.
-
For Weight (%), enter a weight value for the function.
Weight is the percentage of traffic that is assigned to that version when the alias
is invoked. The first version receives the residual weight. For example, if you specify 10 percent to
Additional version, the first version is assigned 90 percent automatically.
-
Choose Save.
- AWS CLI
-
Use the create-alias and update-alias AWS CLI commands to configure the traffic weights between two function versions. When you create or update the alias, you specify the traffic weight in
the routing-config
parameter.
The following example creates a Lambda function alias named routing-alias
that points to version 1 of the function. Version 2 of the function receives 3 percent of the traffic. The
remaining 97 percent of traffic is routed to version 1.
aws lambda create-alias \
--name routing-alias \
--function-name my-function \
--function-version 1 \
--routing-config AdditionalVersionWeights={"2"=0.03}
Use the update-alias
command to increase the percentage of incoming traffic to version 2. In
the following example, you increase the traffic to 5 percent.
aws lambda update-alias \
--name routing-alias \
--function-name my-function \
--routing-config AdditionalVersionWeights={"2"=0.05}
To route all traffic to version 2, use the update-alias
command to change the
function-version
property to point the alias to version 2. The command also resets the routing
configuration.
aws lambda update-alias \
--name routing-alias \
--function-name my-function \
--function-version 2 \
--routing-config AdditionalVersionWeights={}
The AWS CLI commands in the preceding steps correspond to the following Lambda API operations:
Determining which version was invoked
When you configure traffic weights between two function versions, there are two ways to determine the Lambda
function version that has been invoked:
-
CloudWatch Logs – Lambda automatically emits a START
log entry
that contains the invoked version ID to Amazon CloudWatch Logs for every function invocation. The following is an
example:
19:44:37 START RequestId: request id
Version:
$version
For alias invocations, Lambda uses the Executed Version
dimension to filter the metric data
by the invoked version. For more information, see View metrics for Lambda functions.
-
Response payload (synchronous invocations) – Responses to
synchronous function invocations include an x-amz-executed-version
header to indicate which
function version has been invoked.