> 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-2/serverless-deployment.md).

# Serverless deployment

Configure and run Serverless Lambda deployments in Harness, including containerized steps, rollback, and framework version support.

A Serverless Lambda deployment in Harness packages and deploys your Lambda functions using the Serverless Framework CLI. You select a deployment strategy when adding the stage, and Harness adds the required steps automatically.

***

### What you will learn <a href="#what-you-will-learn" id="what-you-will-learn"></a>

* How Harness configures and executes a Serverless Lambda deployment.
* How to configure the Package, Deploy, and Rollback steps.
* The full deployment execution sequence, including rollback behavior.
* How to select container images and configure the runtime environment.

***

## Before you begin

Ensure the following are in place before configuring a Serverless Lambda deployment:

* A configured [Serverless service](/continuous-delivery/3.0/use-deployments/overview-2/serverless-services.md) with a manifest and artifact source.
* A configured [Serverless infrastructure](/continuous-delivery/3.0/use-deployments/overview-2/serverless-infrastructure.md) with an AWS connector, region, and stage.
* A Kubernetes cluster that the delegate can reach, to run the containerized step containers.

***

## Deployment strategy

Serverless Lambda supports one deployment strategy: **Serverless Deployment With Rollback**.

When you add a Serverless Lambda stage, Harness automatically adds three steps:

| Section   | Step         | What it does                                                                                                |
| --------- | ------------ | ----------------------------------------------------------------------------------------------------------- |
| Execution | **Package**  | Runs `serverless package` to bundle Lambda functions and prepare the CloudFormation template.               |
| Execution | **Deploy**   | Runs `serverless deploy` to create or update the CloudFormation stack and activate the new Lambda versions. |
| Rollback  | **Rollback** | Restores the deployment to the state captured before the Deploy step ran.                                   |

Rollback state is captured automatically before the Deploy step runs; it is not a separate step you configure. If the Deploy step fails, Harness triggers the Rollback step using the saved state. Go to [Deployment execution sequence](#deployment-execution-sequence) for the full execution flow.

***

## Configure the Package step

The Package step runs `serverless package` to bundle your Lambda functions and prepare the CloudFormation template.

| Field                     | Required | Description                                                                                                        |
| ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| **Name**                  | Yes      | Display name for this step in the stage canvas.                                                                    |
| **Container Registry**    | Yes      | A connector pointing to the registry that hosts the step image.                                                    |
| **Image**                 | Yes      | The `serverless-plugin` image and tag to use. Use the tag that matches your Lambda function's runtime.             |
| **Command Options**       | No       | Additional flags passed to `serverless package`, for example `--verbose`. Appended after `--stage` and `--region`. |
| **Pre-Execute Command**   | No       | Shell command that runs before the step logic. Use this to install dependencies or navigate to a sub-directory.    |
| **Environment Variables** | No       | Key-value pairs injected into the container.                                                                       |

***

## Configure the Deploy step

The Deploy step runs `serverless deploy` to create or update the CloudFormation stack and register the new Lambda function versions.

| Field                     | Required | Description                                                                                                                 |
| ------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Name**                  | Yes      | Display name for this step in the stage canvas.                                                                             |
| **Container Registry**    | Yes      | A connector pointing to the registry that hosts the step image.                                                             |
| **Image**                 | Yes      | The `serverless-plugin` image and tag to use. Use the same image as the Package step.                                       |
| **Command Options**       | No       | Additional flags passed to `serverless deploy`, for example `--aws-s3-accelerate`. Appended after `--stage` and `--region`. |
| **Pre-Execute Command**   | No       | Shell command that runs before the step logic.                                                                              |
| **Environment Variables** | No       | Key-value pairs injected into the container. For Serverless V4, add `SERVERLESS_ACCESS_KEY` here.                           |

***

## Configure the Rollback step

The Rollback step is added to the rollback section of the stage inside a step group. Toggle **Rollback** in the execution view to see and configure it.

| Field                     | Required | Description                                                               |
| ------------------------- | -------- | ------------------------------------------------------------------------- |
| **Name**                  | Yes      | Display name for this step in the stage canvas.                           |
| **Container Registry**    | Yes      | A connector pointing to the registry that hosts the step image.           |
| **Image**                 | Yes      | The `serverless-plugin` image and tag to use.                             |
| **Pre-Execute Command**   | No       | Shell command that runs before the step logic, for example `npm install`. |
| **Environment Variables** | No       | Key-value pairs injected into the container.                              |

When triggered, the Rollback step restores the AWS CloudFormation stack for your Serverless service to its previous state.

***

## Deployment execution sequence

When a Serverless Lambda stage triggers, Harness runs a set of platform-managed steps before your configured Package and Deploy steps execute. The full sequence, from trigger to completion, is:

| Step                            | What it does                                                                                                                                                                                                                                                                              |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Initialize**                  | Prepares the container runtime environment.                                                                                                                                                                                                                                               |
| **Service**                     | Fetches manifest files and artifact metadata from their configured sources.                                                                                                                                                                                                               |
| **Infrastructure**              | Resolves AWS credentials from the connector in the infrastructure definition.                                                                                                                                                                                                             |
| **Harness Manifest Rendering**  | Downloads manifest files into the container at `/harness/<manifest-id>/<folder-path>/`. Searches for `serverless.yml`, `serverless.yaml`, `serverless.json`, or `serverlessDefaultStack.yml` in the configured folder path.                                                               |
| **Harness Manifest Templating** | Renders Go template expressions in the manifest using the values YAML file. Updates the manifest in place at its fetched path.                                                                                                                                                            |
| **Resource Constraint**         | Checks pipeline concurrency limits.                                                                                                                                                                                                                                                       |
| **Package**                     | Downloads the artifact (**Download Artifact Action**), then runs `serverless package` (**Serverless Package Action**).                                                                                                                                                                    |
| **Deploy**                      | Downloads the artifact again (**Download Artifact Action**), captures the current stack state for rollback, then runs `serverless deploy` (**Serverless Deploy Action**). After a successful deploy, fetches the updated stack template to record deployed function and endpoint details. |

### Artifact path in the container <a href="#artifact-path-in-the-container" id="artifact-path-in-the-container"></a>

Both the Package and Deploy steps download the artifact to `/harness/artifacts/primary/<filename>`. This path is also available as the `ARTIFACT_DOWNLOAD_PATH` environment variable.

When using a values YAML file, map the artifact path expression so the rendered manifest points to this location:

```yaml
# values.yaml
artifactPath: <+artifact.path>
```

After templating, `serverless.yaml` contains the resolved path:

```yaml
package:
  artifact: /harness/artifacts/primary/handler1.zip
```

The Serverless CLI reads this path when packaging and uploads the artifact to S3 under the key prefix `serverless/<service>/<stage>/code-artifacts/`.

### Stack name <a href="#stack-name" id="stack-name"></a>

The Serverless Framework creates a stack named `<service>-<stage>`. The `<service>` value comes from the `service:` field in `serverless.yaml`. The `<stage>` value comes from the **Stage** field in the infrastructure definition.

### First deployment <a href="#first-deployment" id="first-deployment"></a>

On a first deployment, no prior stack exists. The deploy step detects this and proceeds without saved rollback state. If the deployment fails, the Rollback step exits without action. Delete the incomplete stack from the AWS console before retrying.

### Subsequent deployments <a href="#subsequent-deployments" id="subsequent-deployments"></a>

Before the Deploy step runs, the platform captures the current stack state. If the deployment fails, the Rollback step uses the saved state to restore all Lambda functions to their previous version.

***

## Select container images

Each step requires a container registry connector and an image. The image tag encodes the Lambda runtime and the Serverless Framework version, for example `nodejs20.x-3.39.0-1.1.0-beta-linux-amd64`. Use the tag that matches your Lambda function's runtime and the Serverless Framework version you want to deploy with.

***

## Use the manifest directory in pre-execute command

After the manifest download runs, the manifest is placed in a directory available via the `PLUGIN_WORK_DIR` environment variable. Use this in the **Pre-Execute Command** to navigate to the manifest directory before running custom commands:

```bash
cd "$(echo ${PLUGIN_WORK_DIR} | tr -d '"' | sed 's:/*$::')"
```

***

## Serverless V4 authentication

Serverless Framework V4 requires CLI authentication. Add a `SERVERLESS_ACCESS_KEY` environment variable to the Deploy step with a Harness secret that holds your Serverless access key.

{% hint style="warning" %}
**Breaking change in V4**

Upgrading from V3 to V4 requires adding `SERVERLESS_ACCESS_KEY` to all steps. Existing V3 deployments should be tested before switching to V4.
{% endhint %}

***

## Rollback behavior

When the Deploy step fails, Harness triggers the Rollback step in the stage rollback section. The Rollback step restores the AWS CloudFormation stack to the state captured before the Deploy step ran.

Go to [First deployment](#first-deployment) and [Subsequent deployments](#subsequent-deployments) in the execution flow section above for details on how stack state is captured.

One additional case applies:

* **Rollback not configured:** If the Rollback step is missing from the rollback section, or the stage failure strategy is not set to **Stage Rollback**, no rollback runs on failure.

***

## Stage YAML reference

The following is a complete Serverless Lambda stage YAML with the rollback strategy configured:

```yaml
stages:
- name: Stage
  id: stage
  service: <your-service-id>
  environment:
    id: <your-environment-id>
    deploy-to: <your-infra-id>
  steps:
  - name: Package
    id: packagestep
    template:
      uses: serverlessPackageStep
      with:
        pre_exec_cmd: cd "$(echo ${PLUGIN_WORK_DIR} | tr -d '"' | sed 's:/*$::')" && npm install
  - name: Deploy
    id: deploystep
    template:
      uses: serverlessDeployStep
      with:
        pre_exec_cmd: cd "$(echo ${PLUGIN_WORK_DIR} | tr -d '"' | sed 's:/*$::')" && npm install
        cmd_opts: --aws-s3-accelerate
  rollback:
  - group:
      steps:
      - name: Rollback
        id: rollbackstep
        template:
          uses: serverlessRollbackStep
  on-failure:
    errors: all
    action: stage-rollback
  runtime:
    kubernetes:
      namespace: <your-k8s-namespace>
      connector: <your-k8s-connector>
      pull: always
  timeout: 10m
```

Key YAML fields:

| YAML key                            | UI label                | Description                                                     |
| ----------------------------------- | ----------------------- | --------------------------------------------------------------- |
| `pre_exec_cmd`                      | **Pre-Execute Command** | Shell command that runs before the step logic.                  |
| `cmd_opts`                          | **Command Options**     | Additional flags appended to the Serverless CLI command.        |
| `on-failure.action: stage-rollback` | Failure strategy        | Triggers the rollback section when any step in the stage fails. |
| `runtime.kubernetes`                | Runtime Environment     | The Kubernetes cluster used to run the step containers.         |

***

## Limitations

{% hint style="warning" %}
**Unsupported features**

* **Sidecar artifacts:** The `serverless-plugin` container image processes only the primary artifact. If you add a sidecar artifact, the sidecar expression is not resolved and the deployment fails.
* **Serverless V4 with a custom config file and a default `serverless.yml` in the same directory:** V4 reads the default filename even when `--config` is set, and fails if the default file is invalid. Remove or rename `serverless.yml` when using a custom config file path with V4.
  {% endhint %}

***

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

* Go to [Serverless Package](/continuous-delivery/3.0/use-deployments/overview-2/serverless-package.md) to review the Package step parameters.
* Go to [Serverless Deploy](/continuous-delivery/3.0/use-deployments/overview-2/serverless-package/serverless-deploy.md) to review the Deploy step parameters.
* Go to [Serverless Rollback](/continuous-delivery/3.0/use-deployments/overview-2/serverless-package/serverless-rollback.md) to review the Rollback step parameters.

{% @harness-feedback/feedback %}