View a markdown version of this page

Deploying and updating Lambda Managed Instances functions - AWS Lambda
Deployment strategiesChoosing between $LATEST.PUBLISHED and numeric versions with aliasesConfiguring scaling after a deploymentManaging deployments with infrastructure as codeNext steps

Deploying and updating Lambda Managed Instances functions

When you update a Lambda Managed Instances function, Lambda provisions execution environments for the new function version on your managed instances before shifting traffic to it. You can control deployment speed and safety by selecting a deployment strategy. This topic describes the deployment strategies available for Lambda Managed Instances functions and how to define them with infrastructure as code (IaC).

Note

Before you deploy a function, you must have a capacity provider. For more information, see capacity providers for Lambda Managed Instances.

Deployment strategies

Lambda Managed Instances supports the following strategies for releasing a new function version. Choose the strategy that matches how much control you want to retain over the rollout. Rolling updates are the simplest option. Blue/green and canary deployments give you more control over how traffic moves to the new version.

Rolling updates

To perform a rolling update, you publish your changes to the $LATEST.PUBLISHED version of your function. $LATEST.PUBLISHED is a version type specific to Lambda Managed Instances that you republish with new code or configuration instead of maintaining numbered versions. When you invoke a Lambda Managed Instances function with its unqualified Amazon Resource Name (ARN), Lambda invokes the $LATEST.PUBLISHED version. For more information, see $LATEST.PUBLISHED version in Lambda Managed Instances.

Each time you republish $LATEST.PUBLISHED, Lambda gradually replaces the execution environments on your managed instances with the new version, without requiring you to manage traffic shifting directly through a function alias. This is the simplest strategy.

Use rolling updates when you want an automated gradual shift of traffic from the old version to the new version, and you don't need direct control of the percentage of traffic sent to each version to manage the deployment or rollback.

Blue/green deployments with a weighted alias

In a blue/green deployment, you publish the new version alongside the current version and use an alias with a routing configuration to send a percentage of traffic to the new version. You invoke the function through the alias-qualified ARN. To roll the deployment forward, you increase the weight on the new version; to roll it back, you shift the weight back to the previous version.

The following example uses the AWS CLI to send 10 percent of traffic to version 2 while version 1 continues to serve the remaining 90 percent.

aws lambda update-alias \
  --function-name my-managed-instance-function \
  --name production \
  --function-version 1 \
  --routing-config AdditionalVersionWeights={"2"=0.1}

In this command:

  • my-managed-instance-function is the name of your function.

  • production is the name of the alias that you invoke.

  • --function-version 1 is the version that continues to receive the remaining traffic.

  • AdditionalVersionWeights={"2"=0.1} sends 10 percent of traffic to version 2.

To roll back, clear the routing configuration so that all traffic returns to the stable version.

aws lambda update-alias \
  --function-name my-managed-instance-function \
  --name production \
  --function-version 1 \
  --routing-config '{}'

In this command, --routing-config '{}' clears the routing configuration so that all traffic returns to the version in --function-version, version 1.

Canary deployments with AWS CodeDeploy

To automate a blue/green traffic shift, use AWS CodeDeploy. CodeDeploy shifts traffic from the current version to the new version according to a deployment configuration—for example, sending 10 percent of traffic to the new version, waiting five minutes, and then shifting the remainder. If a CloudWatch alarm associated with the deployment enters an alarm state during the shift, CodeDeploy rolls the deployment back automatically.

For more information about CodeDeploy deployment configurations for Lambda, see Deployment configurations on an Lambda compute platform in the AWS CodeDeploy User Guide.

Choosing between $LATEST.PUBLISHED and numeric versions with aliases

Both deployment models roll out changes gradually. Whether you update $LATEST.PUBLISHED or shift traffic with a weighted alias, Lambda Managed Instances replaces the old version's execution environments with the new version in steps, rather than all at once. This approach keeps instance utilization efficient during the rollout. Instead of provisioning a full second set of execution environments up front, Lambda replaces them in increments: at each step it reclaims capacity from the old version before bringing up the next batch of the new version, so the rollout avoids reaching double the baseline capacity.

How $LATEST.PUBLISHED rollouts progress

When you publish an update to $LATEST.PUBLISHED, Lambda begins rolling out the new version in steps. At each step, Lambda creates new execution environments—up to 20 percent of the old version's total—and gradually replaces the old version's execution environments.

Two factors determine how long the rollout takes:

  • Initialization time - Each step waits for the new execution environments to initialize before it proceeds. If initialization takes 10 minutes, each step waits at least 10 minutes.

  • Invoke duration - Before Lambda can remove an old execution environment, its in-flight invocations must finish (drain). If your average invoke duration is 5 minutes, draining takes about 5 minutes on average at each step.

Because Lambda Managed Instances keeps instance utilization high, both initialization and draining contribute to the total deployment time. Functions with long initialization or long-running invocations take longer to fully roll out.

How numeric versions with aliases progress

Weighted alias updates are gradual in the same way. When you change the routing weights on an alias—for example, from 90 percent version 1 and 10 percent version 2 to 100 percent version 2—Lambda Managed Instances slowly replaces the version 1 execution environments with version 2, without provisioning excess instance capacity.

Use numeric versions with an alias when you want tighter control over the gradual rollout and version-specific observability. Because each version is a distinct qualifier, you can compare per-version metrics for the canary and the stable version before you promote a change. For more information, see viewing metrics for your Lambda functions.

Configuring scaling after a deployment

Each function version that you deploy has its own scaling configuration, which controls the minimum and maximum number of execution environments that Lambda maintains for that version. Set the scaling configuration after you publish a version so that the new version can serve traffic at the capacity you expect.

The following example sets the scaling configuration for a specific version. Replace 2 with your version number or with $LATEST.PUBLISHED.

aws lambda put-function-scaling-config \
  --function-name my-managed-instance-function \
  --qualifier 2 \
  --function-scaling-config MinExecutionEnvironments=3,MaxExecutionEnvironments=20

Managing deployments with infrastructure as code

You can define and deploy Lambda Managed Instances functions and their capacity providers with infrastructure as code, including AWS CloudFormation, the AWS Cloud Development Kit (AWS CDK), and third-party tools such as HashiCorp Terraform. Model your capacity provider, function, versions, and alias as resources so that your deployment strategy is reproducible and reviewable.

Keep the following considerations in mind when you manage Lambda Managed Instances deployments with IaC:

  • Publish a version to activate a change. A new function version becomes active on the capacity provider's instances only after it is published. Model each version you want to keep in service—for example, both sides of a blue/green shift—as its own resource.

  • Scaling configuration is per version. Apply the minimum and maximum execution environment settings to each version or to $LATEST.PUBLISHED. If your IaC tool does not model scaling configuration directly, set it with the put-function-scaling-config AWS CLI command after deployment.

  • Deployment packages must come from Amazon S3 when you use the AWS Cloud Control API. The AWS Cloud Control API accepts a function's code only as an Amazon S3 location or a container image URI, not as a locally uploaded .zip file. If your IaC tool uses this API, upload your deployment package to an S3 bucket first and reference it by bucket and key. Use a versioned bucket so that updates to the object are detected.

Example: CloudFormation template

The following CloudFormation template shows a blue/green deployment. It creates a capacity provider, a Lambda Managed Instances function, two published versions (each with its own function scaling configuration), and an alias named production that routes 90 percent of traffic to the stable version and 10 percent to the canary version. To promote the canary, set the alias FunctionVersion to the canary version and remove the RoutingConfig. To roll back, remove the RoutingConfig so that all traffic returns to the stable version. Replace the subnet, security group, role, and Amazon S3 values with your own.

AWSTemplateFormatVersion: '2010-09-09'
Description: Lambda Managed Instances blue/green deployment with a weighted alias

Resources:
  MyCapacityProvider:
    Type: AWS::Lambda::CapacityProvider
    Properties:
      CapacityProviderName: my-capacity-provider
      VpcConfig:
        SubnetIds:
          - subnet-0123456789abcdef0
        SecurityGroupIds:
          - sg-0123456789abcdef0
      PermissionsConfig:
        CapacityProviderOperatorRoleArn: arn:aws:iam::111122223333:role/my-capacity-provider-operator-role
      InstanceRequirements:
        Architectures:
          - arm64

  MyFunction:
    Type: AWS::Lambda::Function
    Properties:
      FunctionName: my-managed-instance-function
      Role: arn:aws:iam::111122223333:role/my-function-execution-role
      Runtime: python3.13
      Handler: index.lambda_handler
      Architectures:
        - arm64
      Code:
        S3Bucket: my-deployment-bucket
        S3Key: function.zip
      CapacityProviderConfig:
        LambdaManagedInstancesCapacityProviderConfig:
          CapacityProviderArn: !GetAtt MyCapacityProvider.Arn

  # Stable version - receives the majority of traffic
  StableVersion:
    Type: AWS::Lambda::Version
    Properties:
      FunctionName: !Ref MyFunction
      FunctionScalingConfig:
        MinExecutionEnvironments: 10
        MaxExecutionEnvironments: 50

  # Canary version - receives a small percentage of traffic
  CanaryVersion:
    Type: AWS::Lambda::Version
    Properties:
      FunctionName: !Ref MyFunction
      FunctionScalingConfig:
        MinExecutionEnvironments: 3
        MaxExecutionEnvironments: 20

  ProductionAlias:
    Type: AWS::Lambda::Alias
    Properties:
      FunctionName: !Ref MyFunction
      Name: production
      FunctionVersion: !GetAtt StableVersion.Version
      RoutingConfig:
        AdditionalVersionWeights:
          - FunctionVersion: !GetAtt CanaryVersion.Version
            FunctionWeight: 0.1

Example: CDK

The following CDK example (TypeScript) defines the same capacity provider and function using the level 1 (L1) constructs from the aws-cdk-lib/aws-lambda module. operatorRole and executionRole are IAM roles defined elsewhere in your stack.

import * as cdk from 'aws-cdk-lib';
import * as lambda from 'aws-cdk-lib/aws-lambda';

const capacityProvider = new lambda.CfnCapacityProvider(this, 'MyCapacityProvider', {
  capacityProviderName: 'my-capacity-provider',
  vpcConfig: {
    subnetIds: ['subnet-0123456789abcdef0'],
    securityGroupIds: ['sg-0123456789abcdef0'],
  },
  permissionsConfig: {
    capacityProviderOperatorRoleArn: operatorRole.roleArn,
  },
  instanceRequirements: {
    architectures: ['arm64'],
  },
});

const fn = new lambda.CfnFunction(this, 'MyFunction', {
  functionName: 'my-managed-instance-function',
  role: executionRole.roleArn,
  runtime: 'python3.13',
  handler: 'index.lambda_handler',
  architectures: ['arm64'],
  code: { s3Bucket: 'my-deployment-bucket', s3Key: 'function.zip' },
  capacityProviderConfig: {
    lambdaManagedInstancesCapacityProviderConfig: {
      capacityProviderArn: capacityProvider.attrArn,
    },
  },
  functionScalingConfig: {
    minExecutionEnvironments: 3,
    maxExecutionEnvironments: 20,
  },
  publishToLatestPublished: true,
});
fn.addDependency(capacityProvider);

Example: canary deployment with AWS CodeDeploy

The following CDK example (TypeScript) uses AWS CodeDeploy to shift traffic to a new function version automatically. The LambdaDeploymentGroup sends 10 percent of traffic to the new version for five minutes and then shifts the rest. If the CloudWatch alarm enters an alarm state during the deployment, CodeDeploy rolls back to the previous version.

fn is the L1 CfnFunction from the previous example. Because CodeDeploy's LambdaDeploymentGroup works with the level 2 (L2) alias and function constructs, import the L1 function by ARN and build the version and alias from it.

import * as cdk from 'aws-cdk-lib';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as codedeploy from 'aws-cdk-lib/aws-codedeploy';
import * as cloudwatch from 'aws-cdk-lib/aws-cloudwatch';

// Import the L1 function so that L2 constructs can reference it.
const importedFn = lambda.Function.fromFunctionArn(this, 'ImportedFunction', fn.attrArn);

// Publish the version that CodeDeploy shifts traffic to.
const canaryVersion = new lambda.CfnVersion(this, 'CanaryVersion', {
  functionName: fn.ref,
});

// Create the alias that CodeDeploy shifts traffic on.
const alias = new lambda.Alias(this, 'ProductionAlias', {
  aliasName: 'production',
  version: lambda.Version.fromVersionAttributes(this, 'CanaryVersionRef', {
    lambda: importedFn,
    version: canaryVersion.attrVersion,
  }),
});

// Roll back automatically if this alarm fires during the deployment.
const errorAlarm = new cloudwatch.Alarm(this, 'ErrorAlarm', {
  metric: importedFn.metricErrors({ period: cdk.Duration.minutes(1) }),
  threshold: 5,
  evaluationPeriods: 1,
  comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
});

new codedeploy.LambdaDeploymentGroup(this, 'CanaryDeployment', {
  alias,
  deploymentConfig: codedeploy.LambdaDeploymentConfig.CANARY_10PERCENT_5MINUTES,
  alarms: [errorAlarm],
  autoRollback: {
    failedDeployment: true,
    deploymentInAlarm: true,
  },
});

Next steps