> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/continuous-delivery/3.0/use-deployments/overview-4/canary.md).

# Deployment Strategies

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 <a href="#what-you-will-learn" id="what-you-will-learn"></a>

* 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 <a href="#before-you-begin" id="before-you-begin"></a>

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

* **A Lambda service:** Go to [Lambda services](/continuous-delivery/3.0/use-deployments/overview-4/lambda-services.md) 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](/continuous-delivery/3.0/use-deployments/overview-4/lambda-services.md#alias-and-artifact-type-requirements) to review the requirements.
* **A Lambda infrastructure:** Go to [Lambda infrastructure](/continuous-delivery/3.0/use-deployments/overview-4/lambda-infrastructure.md) to connect an AWS account and region.

***

## How canary deployments work <a href="#how-canary-deployments-work" id="how-canary-deployments-work"></a>

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 href="#configure-a-canary-stage" id="configure-a-canary-stage"></a>

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 <a href="#select-the-canary-strategy" id="select-the-canary-strategy"></a>

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.

{% hint style="success" %}
**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%.
{% endhint %}

***

### Configure the AWS Lambda Canary Deploy step <a href="#configure-the-aws-lambda-canary-deploy-step" id="configure-the-aws-lambda-canary-deploy-step"></a>

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.

{% hint style="info" %}
**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.
{% endhint %}

***

### Configure the AWS Lambda Traffic Shift steps <a href="#configure-the-aws-lambda-traffic-shift-steps" id="configure-the-aws-lambda-traffic-shift-steps"></a>

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 <a href="#canary-deploy-step-output-variables" id="canary-deploy-step-output-variables"></a>

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 <a href="#rollback" id="rollback"></a>

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 <a href="#complete-yaml-reference" id="complete-yaml-reference"></a>

<details>

<summary>Pipeline YAML</summary>

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

```yaml
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](/continuous-delivery/3.0/use-deployments/overview-4/lambda-infrastructure.md#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.

</details>

***

## Next steps <a href="#next-steps" id="next-steps"></a>

* Go to [Lambda rolling deployment](/continuous-delivery/3.0/use-deployments/overview-4/canary/rolling.md) to configure the rolling strategy.
* Go to [Lambda services](/continuous-delivery/3.0/use-deployments/overview-4/lambda-services.md) to review function definition and alias definition requirements.
* Go to [AWS Lambda Canary Deploy step reference](/continuous-delivery/3.0/use-deployments/overview-4/lambda-canary-deploy.md) for the full field reference.
* Go to [AWS Lambda Traffic Shift step reference](/continuous-delivery/3.0/use-deployments/overview-4/lambda-canary-deploy/lambda-traffic-shift.md) for the full field reference.
* Go to [AWS Lambda Canary Rollback step reference](/continuous-delivery/3.0/use-deployments/overview-4/lambda-canary-deploy/lambda-canary-rollback.md) for the rollback step reference.

{% @harness-feedback/feedback %}