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 traffic management and deployment strategies. This guide focuses on three capabilities: version pinning with stable names, traffic splitting between versions, and $LATEST tracking for development.

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 automation.

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 name property creates a stable identifier like “production” that clients reference. The functionVersion property pins the alias to a specific published version. When you update functionVersion, all traffic shifts to the new version immediately.

Split traffic between two function versions

When testing new code in production, teams route a small percentage of traffic to the new version while keeping most on the stable 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 lets you validate new code with real production traffic before full rollout.

Track the latest unpublished function code

Development environments often test the most recent changes without publishing numbered versions for every iteration.

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.

Beyond these examples

These snippets focus on specific alias-level features: version pinning and stable references, traffic splitting for gradual rollouts, and $LATEST tracking for development. 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 provisioning the underlying functions or deployment automation.

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

  • API Gateway integration (invokeArn usage)
  • EventBridge or other trigger configuration
  • Alias update strategies and automation
  • Monitoring and rollback procedures

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 & Routing
How do I split traffic between two Lambda versions?
Use routingConfig.additionalVersionWeights with a map of version numbers to traffic weights. For example, {'1': 0.1} sends 10% of traffic to version 1, with the remaining 90% going to the version specified in functionVersion.
How do I implement a blue-green deployment with gradual rollout?
Set functionVersion to your stable version and use routingConfig.additionalVersionWeights to route a small percentage to the new version. For example, functionVersion: '5' with additionalVersionWeights: {'6': 0.05} sends 95% to version 5 and 5% to version 6.
What's the difference between functionVersion and additionalVersionWeights?
functionVersion specifies the primary version that receives most traffic. additionalVersionWeights routes a percentage of traffic to other versions for testing or gradual rollouts.
Versioning & Updates
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.
How do I update an alias to point to a different version?
Update the functionVersion property to the new version number. This property is mutable and won’t force resource replacement.
Configuration & Constraints
What properties can't I change after creating an alias?
Both functionName and name are immutable. Changing either will force replacement of the alias resource. Use functionVersion updates to change which version the alias points to.
Why can't I name my alias with only numbers?
Alias names must match the pattern (?!^[0-9]+$)([a-zA-Z0-9-_]+), which rejects all-numeric names. Include at least one letter, hyphen, or underscore.
Integration
How do I use this alias with API Gateway?
Use the invokeArn output property in aws.apigateway.Integration’s uri field to invoke the Lambda function through the alias.

Using a different cloud?

Explore serverless guides for other cloud providers:

Azure Guides GCP Guides