Lambda canary deployment

Gradually shift traffic to a new Lambda function version using weighted aliases, then promote fully once validated.

A Lambda canary deployment publishes a new function version, then uses a weighted alias to route a configurable percentage of traffic to it alongside the current version. Once you validate the canary, a second traffic shift routes all remaining traffic to the new version. If the canary fails, the alias is reset and the previous version continues serving all traffic.

---

What you will learn

• How a Lambda canary deployment works and when to use it.

• How to configure the Canary Deploy and Traffic Shift steps.

• How rollback works for canary deployments.

---

Before you begin

Before you configure a canary stage, make sure you have the following in place:

• A Lambda service: Go to Lambda services to set up a service with a function definition and an artifact source. Whether you also need an alias definition depends on your artifact type — go to Alias and artifact type requirements to review the requirements.

• A Lambda infrastructure: Go to Lambda infrastructure to connect an AWS account and region.

---

How canary deployments work

When Harness runs a Lambda canary deployment, it:

1. Publishes a new version of the Lambda function with the updated code and configuration.

2. Creates or updates a weighted alias that splits traffic between the previous version and the new version according to the traffic percentage you configure.

3. Shifts all remaining traffic to the new version in a second step once the canary is validated.

If anything fails, the rollback step resets the alias weights back to the previous version, so the stable version immediately handles 100% of traffic again.

When to use canary:

• You want to test the new function version against real production traffic before a full switch.

• You need to observe error rates, latency, or downstream effects on a small percentage of requests first.

• You want the lowest-risk rollout: only the configured traffic percentage is affected if the new version has issues.

---

Configure a canary stage

A canary stage requires two kinds of configuration: selecting the strategy and then configuring each step Harness adds to the stage canvas.

Select the canary strategy

When creating a new stage, step 4 of the stage wizard asks you to choose a deployment strategy. Select AWS Lambda Canary Deploy Strategy from the list.

Harness automatically adds three steps to the stage canvas:

The three steps run in order:

1. AWS Lambda Canary Deploy: Publishes a new function version and creates a weighted alias that routes the initial traffic percentage to it.

2. AWS Lambda Traffic Shift (10%): Routes 10% of traffic to the new version via the alias. You can adjust this percentage or add more shift steps.

3. AWS Lambda Traffic Shift (100%): Routes all remaining traffic to the new version, completing the promotion.

Insert validation between steps

Place approval or verification steps between the traffic shift steps. For example, run a health check or approval gate after the 10% shift before committing the remaining 90%.

---

Configure the AWS Lambda Canary Deploy step

Click the AWS Lambda Canary Deploy step to open its configuration panel.

The step has two sections whose values are derived automatically from your service and infrastructure:

Service Configuration

Field	Value	Description
Function Definition	${{serviceOutput.manifests.awsLambdaFunction.paths}}	Path to the function definition manifest. Harness resolves this at runtime from the service.
Function Alias	${{serviceOutput.manifests.awsLambdaAlias.paths}}	Path to the alias definition manifest. Populated when your service includes an AwsLambdaFunctionAliasDefinition manifest. Required for ZIP artifact canary; not required for ECR image canary.

Infrastructure Configuration

Field	Value	Description
AWS Connector	Select a connector	The AWS connector used to authenticate to Lambda. Defaults to the connector configured in the infrastructure definition.
AWS Region	${{infra.region}}	The region where the function is deployed. Resolved automatically from the infrastructure definition.

You do not need to change these fields when you wire the step to a correctly configured service and infrastructure.

ECR image functions

When your artifact is a container image from ECR, the function definition uses packageType: Image — there is no handler or runtime field. Define functionName and role as service variables. The Function Alias field will be empty; this is expected and the canary deploy step handles alias management automatically.

When your artifact is a ZIP file, define functionName and runtime as service variables and add an alias definition manifest to populate the Function Alias field.

---

Configure the AWS Lambda Traffic Shift steps

Harness adds two traffic shift steps by default: one at 10% and one at 100%. Click either step to open its configuration panel.

Traffic Percentage

Field	Description	Required
Traffic Percentage	The percentage of traffic to route to the new function version via the alias. Must be between 0 and 100.	Yes

Service Configuration (auto-populated from the Canary Deploy step output)

Field	Value	Description
Function Name	<+stage.steps.awsLambdaCanaryDeployStep.output.outputVariables.functionName>	The Lambda function name, passed from the Canary Deploy step output.
Function Version	<+stage.steps.awsLambdaCanaryDeployStep.output.outputVariables.version>	The published version number of the new function, passed from the Canary Deploy step output.

Infrastructure Configuration

Field	Value	Description
AWS Connector	Select a connector	The AWS connector used to update the alias weights.
AWS Region	${{infra.region}}	Resolved from the infrastructure definition.

To add an intermediate traffic shift (for example, 50%), click + between the two existing traffic shift steps and add another AWS Lambda Traffic Shift step. Set the Traffic Percentage to your desired value.

---

Canary deploy step output variables

After the AWS Lambda Canary Deploy step completes, the following output variables are available for downstream steps:

Variable	Expression	Description
functionName	<+stage.steps.awsLambdaCanaryDeployStep.output.outputVariables.functionName>	The name of the deployed Lambda function. Used as input to traffic shift steps.
version	<+stage.steps.awsLambdaCanaryDeployStep.output.outputVariables.version>	The version number published by this deployment. Used as input to traffic shift steps.

The traffic shift steps are pre-wired to consume these expressions. If you add a custom step or approval gate between the canary deploy and a traffic shift, these expressions remain valid as long as the canary deploy step ran earlier in the same stage.

---

Rollback

Rollback is triggered by the on-failure: block in the stage configuration — without it, the rollback steps are never invoked regardless of failure. The pipeline YAML in the reference section below includes the required on-failure: block.

When any step in the canary stage fails, Harness runs the AWS Lambda Canary Rollback step. The rollback step reads state from the last successful execution of this stage, not from the failed run.

What the rollback does:

• Resets the weighted alias to route 100% of traffic back to the previous function version.

• Deletes the newly published version that was created by the Canary Deploy step.

After rollback, the alias points exclusively to the last known good version.

Why canary rollback differs from rolling rollback:

In a canary deployment, the previous function version is never removed from the alias — traffic is only split between versions. Rollback therefore does not need to re-deploy anything; it only resets the alias weights and removes the new version. Rolling rollback, by contrast, must re-deploy the previous version code because a rolling deploy fully replaces the function.

---

Complete YAML reference

Pipeline YAML

The same pipeline YAML works for both ZIP and ECR service configurations.

pipeline:
  name: Lambda Canary Deploy
  id: lambdaCanaryDeploy
  clone:
    disabled: true
  stages:
    - name: Stage
      id: stage
      service: <your-service-id>
      environment:
        id: <your-environment-id>
        deploy-to: <your-infrastructure-id>
      steps:
        - name: AWS Lambda Canary Deploy
          id: awsLambdaCanaryDeployStep
          template:
            uses: awsLambdaCanaryDeployStep
        - name: AWS Lambda Traffic Shift 10
          id: awsLambdaTrafficShift10
          template:
            uses: awsLambdaTrafficShiftStep
            with:
              traffic_percentage: "10"
              function_name: <+stage.steps.awsLambdaCanaryDeployStep.output.outputVariables.functionName>
              function_version: <+stage.steps.awsLambdaCanaryDeployStep.output.outputVariables.version>
        - name: AWS Lambda Traffic Shift 100
          id: awsLambdaTrafficShift100
          template:
            uses: awsLambdaTrafficShiftStep
            with:
              traffic_percentage: "100"
              function_name: <+stage.steps.awsLambdaCanaryDeployStep.output.outputVariables.functionName>
              function_version: <+stage.steps.awsLambdaCanaryDeployStep.output.outputVariables.version>
      rollback:
        - group:
            steps:
              - name: AWS Lambda Canary Rollback
                id: awsLambdaCanaryRollbackStep
                template:
                  uses: awsLambdaCanaryRollbackStep
      on-failure:
        errors: all
        action: stage-rollback
      runtime:
        kubernetes:
          namespace: <your-delegate-namespace>
          connector: <your-k8s-connector>
          automount-service-token: true
          pull: always

The runtime.kubernetes block shows one example of running step containers on a Kubernetes cluster via your delegate. Set namespace and connector to match your delegate's Kubernetes namespace and cluster connector. You can also select Harness Cloud or Delegate as the runtime — go to Stage runtime for the full list of options.

The function_name and function_version inputs on each traffic shift step reference the canary deploy step's output variables. This ensures each traffic shift targets exactly the version published in the same stage execution.

---

Next steps

• Go to Lambda rolling deployment to configure the rolling strategy.

• Go to Lambda services to review function definition and alias definition requirements.

• Go to AWS Lambda Canary Deploy step reference for the full field reference.

• Go to AWS Lambda Traffic Shift step reference for the full field reference.

• Go to AWS Lambda Canary Rollback step reference for the rollback step reference.