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

• 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 with a manifest and artifact source.

• A configured Serverless infrastructure 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 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

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:

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

After templating, serverless.yaml contains the resolved path:

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

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

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

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:

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.

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.

---

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 and 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:

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

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.

---

Next steps

• Go to Serverless Package to review the Package step parameters.

• Go to Serverless Deploy to review the Deploy step parameters.

• Go to Serverless Rollback to review the Rollback step parameters.