Manage AWS Lambda Aliases

The aws:lambda/alias:Alias resource, part of the Pulumi AWS provider, creates a named pointer to a specific Lambda function version, enabling stable references and traffic management. This guide focuses on three capabilities: version pinning for stable references, traffic splitting between versions, and development aliases tracking latest code.

Aliases reference Lambda functions and their published versions, which must exist before creating the alias. The examples are intentionally small. Combine them with your own function versioning strategy and deployment pipelines.

Point an alias to a specific function version

Most deployments use aliases to create stable references that can be updated without changing client code or API Gateway integrations.

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const example = new aws.lambda.Alias("example", {
    name: "production",
    description: "Production environment alias",
    functionName: exampleAwsLambdaFunction.arn,
    functionVersion: "1",
});

import pulumi
import pulumi_aws as aws

example = aws.lambda_.Alias("example",
    name="production",
    description="Production environment alias",
    function_name=example_aws_lambda_function["arn"],
    function_version="1")

package main

import (
	"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/lambda"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := lambda.NewAlias(ctx, "example", &lambda.AliasArgs{
			Name:            pulumi.String("production"),
			Description:     pulumi.String("Production environment alias"),
			FunctionName:    pulumi.Any(exampleAwsLambdaFunction.Arn),
			FunctionVersion: pulumi.String("1"),
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;

return await Deployment.RunAsync(() => 
{
    var example = new Aws.Lambda.Alias("example", new()
    {
        Name = "production",
        Description = "Production environment alias",
        FunctionName = exampleAwsLambdaFunction.Arn,
        FunctionVersion = "1",
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.lambda.Alias;
import com.pulumi.aws.lambda.AliasArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var example = new Alias("example", AliasArgs.builder()
            .name("production")
            .description("Production environment alias")
            .functionName(exampleAwsLambdaFunction.arn())
            .functionVersion("1")
            .build());

    }
}

resources:
  example:
    type: aws:lambda:Alias
    properties:
      name: production
      description: Production environment alias
      functionName: ${exampleAwsLambdaFunction.arn}
      functionVersion: '1'

The alias acts as a pointer: clients invoke the alias name, and Lambda routes requests to the specified functionVersion. When you publish a new version, update the alias to point to it. The name property creates the stable reference (e.g., “production”), while functionVersion controls which code actually runs.

Split traffic between two function versions

When testing new code in production, teams gradually shift traffic from a stable version to a new version.

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const example = new aws.lambda.Alias("example", {
    name: "staging",
    description: "Staging environment with traffic splitting",
    functionName: exampleAwsLambdaFunction.functionName,
    functionVersion: "2",
    routingConfig: {
        additionalVersionWeights: {
            "1": 0.1,
        },
    },
});

import pulumi
import pulumi_aws as aws

example = aws.lambda_.Alias("example",
    name="staging",
    description="Staging environment with traffic splitting",
    function_name=example_aws_lambda_function["functionName"],
    function_version="2",
    routing_config={
        "additional_version_weights": {
            "1": 0.1,
        },
    })

package main

import (
	"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/lambda"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := lambda.NewAlias(ctx, "example", &lambda.AliasArgs{
			Name:            pulumi.String("staging"),
			Description:     pulumi.String("Staging environment with traffic splitting"),
			FunctionName:    pulumi.Any(exampleAwsLambdaFunction.FunctionName),
			FunctionVersion: pulumi.String("2"),
			RoutingConfig: &lambda.AliasRoutingConfigArgs{
				AdditionalVersionWeights: pulumi.Float64Map{
					"1": pulumi.Float64(0.1),
				},
			},
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;

return await Deployment.RunAsync(() => 
{
    var example = new Aws.Lambda.Alias("example", new()
    {
        Name = "staging",
        Description = "Staging environment with traffic splitting",
        FunctionName = exampleAwsLambdaFunction.FunctionName,
        FunctionVersion = "2",
        RoutingConfig = new Aws.Lambda.Inputs.AliasRoutingConfigArgs
        {
            AdditionalVersionWeights = 
            {
                { "1", 0.1 },
            },
        },
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.lambda.Alias;
import com.pulumi.aws.lambda.AliasArgs;
import com.pulumi.aws.lambda.inputs.AliasRoutingConfigArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var example = new Alias("example", AliasArgs.builder()
            .name("staging")
            .description("Staging environment with traffic splitting")
            .functionName(exampleAwsLambdaFunction.functionName())
            .functionVersion("2")
            .routingConfig(AliasRoutingConfigArgs.builder()
                .additionalVersionWeights(Map.of("1", 0.1))
                .build())
            .build());

    }
}

resources:
  example:
    type: aws:lambda:Alias
    properties:
      name: staging
      description: Staging environment with traffic splitting
      functionName: ${exampleAwsLambdaFunction.functionName}
      functionVersion: '2'
      routingConfig:
        additionalVersionWeights:
          '1': 0.1

The routingConfig property enables weighted traffic splitting. Here, 90% of invocations go to version 2 (the primary functionVersion), while 10% go to version 1 (specified in additionalVersionWeights). This canary pattern lets you monitor error rates before fully committing to the new version.

Track the latest unpublished function code

Development environments often test the most recent code changes without publishing numbered versions.

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const example = new aws.lambda.Alias("example", {
    name: "dev",
    description: "Development environment - always points to latest",
    functionName: exampleAwsLambdaFunction.functionName,
    functionVersion: "$LATEST",
});

import pulumi
import pulumi_aws as aws

example = aws.lambda_.Alias("example",
    name="dev",
    description="Development environment - always points to latest",
    function_name=example_aws_lambda_function["functionName"],
    function_version="$LATEST")

package main

import (
	"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/lambda"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := lambda.NewAlias(ctx, "example", &lambda.AliasArgs{
			Name:            pulumi.String("dev"),
			Description:     pulumi.String("Development environment - always points to latest"),
			FunctionName:    pulumi.Any(exampleAwsLambdaFunction.FunctionName),
			FunctionVersion: pulumi.String("$LATEST"),
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;

return await Deployment.RunAsync(() => 
{
    var example = new Aws.Lambda.Alias("example", new()
    {
        Name = "dev",
        Description = "Development environment - always points to latest",
        FunctionName = exampleAwsLambdaFunction.FunctionName,
        FunctionVersion = "$LATEST",
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.lambda.Alias;
import com.pulumi.aws.lambda.AliasArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var example = new Alias("example", AliasArgs.builder()
            .name("dev")
            .description("Development environment - always points to latest")
            .functionName(exampleAwsLambdaFunction.functionName())
            .functionVersion("$LATEST")
            .build());

    }
}

resources:
  example:
    type: aws:lambda:Alias
    properties:
      name: dev
      description: Development environment - always points to latest
      functionName: ${exampleAwsLambdaFunction.functionName}
      functionVersion: $LATEST

Setting functionVersion to “$LATEST” makes the alias always point to the unpublished function code. This is useful for development but not recommended for production, since “$LATEST” changes with every function update and doesn’t support traffic splitting.

Beyond these examples

These snippets focus on specific alias-level features: version pinning and stable references, and traffic splitting for canary deployments. They’re intentionally minimal rather than full deployment pipelines.

The examples reference pre-existing infrastructure such as Lambda functions with published versions. They focus on configuring the alias rather than managing function code or versions.

To keep things focused, common alias patterns are omitted, including:

API Gateway integration (invokeArn usage)
EventBridge or other trigger configuration
Alias lifecycle policies and rollback strategies
Monitoring and alarming on per-alias metrics

These omissions are intentional: the goal is to illustrate how each alias feature is wired, not provide drop-in deployment modules. See the Lambda Alias resource reference for all available configuration options.

Let's manage AWS Lambda Aliases

Get started with Pulumi Cloud, then follow our quick setup guide to deploy this infrastructure.

Try Pulumi Cloud for FREE

Frequently Asked Questions

Traffic Management & Deployment

What's a Lambda alias used for?

Aliases enable traffic management and deployment strategies by pointing to specific Lambda function versions. They’re commonly used for blue-green deployments, canary releases, and environment management (production, staging, dev).

How do I split traffic between Lambda versions?

Configure routingConfig with additionalVersionWeights to route a percentage of traffic to a secondary version. For example, setting "6": 0.05 routes 5% to version 6 and 95% to the primary functionVersion.

Can I point an alias to $LATEST?

Yes, set functionVersion to $LATEST to always point to the most recent unpublished version. This is useful for development environments.

What are the traffic weight limits for routing?

The additionalVersionWeights map specifies decimal weights (0.0 to 1.0) for secondary versions. The primary functionVersion receives the remaining traffic percentage.

Configuration & Constraints

What properties are immutable after creation?

Both functionName and name are immutable. Changing either property forces Pulumi to destroy and recreate the alias.

Why can't I name my alias with only numbers?

Alias names must match the pattern (?!^[0-9]+$)([a-zA-Z0-9-_]+), which rejects purely numeric names. Include at least one letter, hyphen, or underscore.

What version formats are valid for functionVersion?

The functionVersion must be either $LATEST or a numeric version string matching the pattern (\$LATEST|[0-9]+).

Integration & Usage

How do I invoke an alias from API Gateway?

Use the alias’s invokeArn output property as the uri in your aws.apigateway.Integration resource.

How do I import an existing Lambda alias?

Use the format function-name/alias-name, for example: pulumi import aws:lambda/alias:Alias example my-function/production.

Using a different cloud?

Explore serverless guides for other cloud providers:

Azure Guides GCP Guides