> 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-package/serverless-deploy.md).

# Serverless Deploy

Deploy a Serverless Lambda service to AWS using the Serverless Framework deploy command.

The Serverless Deploy step creates or updates the AWS CloudFormation stack for your Serverless service, registers the new Lambda function versions, and activates them. It runs after the Serverless Package step and is added automatically when you select the **Serverless Deployment With Rollback Strategy**.

***

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

* The parameters available on the Serverless Deploy step.
* How the Deploy step captures rollback state and runs `serverless deploy`.
* Serverless V4 authentication requirements.

***

### Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

Ensure the following are in place before adding this step to your stage:

* 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.
* The Serverless Package step must have run first to produce the packaged artifact.
* The stage runtime environment configured with a Kubernetes cluster connector. Go to [Serverless deployment](/continuous-delivery/3.0/use-deployments/overview-2/serverless-deployment.md) for setup details.

***

### Configure the step <a href="#configure-the-step" id="configure-the-step"></a>

The following parameters are available on the Serverless Deploy step.

| Parameter                 | Required | Description                                                                                                                                |
| ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Name**                  | Yes      | Display name for this step in the stage canvas. Default: `Serverless Aws Lambda Deploy V2`.                                                |
| **Container Registry**    | Yes      | A Harness Docker Registry connector pointing to the registry that hosts the step image.                                                    |
| **Image**                 | Yes      | The `harness/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` or `--verbose`. 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.                                          |

***

### How the step works <a href="#how-it-works" id="how-it-works"></a>

The Deploy step runs two sub-steps:

1. **Download Artifact Action:** Downloads the primary artifact to `/harness/artifacts/primary/<filename>`. This step runs independently from the Package step's download because each step runs in its own container.
2. **Serverless Deploy Action:** Performs the full deployment sequence:

   a. **Fetch current stack state (Prepare Rollback):** Runs `serverless print --format json` to read the service name from the manifest, then calls the AWS CloudFormation `DescribeStacks` API to capture the full stack state: template body, parameters, policy, tags, capabilities, rollback configuration, and role ARN. This state is saved automatically as a rollback property and passed to the Rollback step without any additional wiring. On a first deployment, `DescribeStacks` returns no stacks; the step logs `This is first time deployment` and proceeds. The Rollback step will exit without action if it is triggered for a first-time deployment.

   b. **Run `serverless deploy`:** Executes `serverless deploy --stage <stage> --region <region>` in the manifest directory, appending any Command Options. The Serverless CLI creates or updates the CloudFormation stack and activates the new Lambda function versions.

   c. **Record deployment results:** After a successful deploy, fetches the updated CloudFormation template to extract function names, ARNs, and API Gateway endpoints. These are logged and saved as step outputs.

The CloudFormation stack is named `<service>-<stage>`, where `<service>` is the `service:` field in `serverless.yaml` and `<stage>` is from the infrastructure definition.

***

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

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

***

### Serverless V4 authentication <a href="#v4-auth" id="v4-auth"></a>

Serverless Framework V4 requires CLI authentication. Add a `SERVERLESS_ACCESS_KEY` environment variable to this 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 the Package, Deploy, and Rollback steps. Existing V3 deployments should be tested before switching to V4 images.
{% endhint %}

***

### Serverless config file path <a href="#config-file" id="config-file"></a>

If your manifest uses a non-default filename, set the **Serverless Config File Path** in the manifest's **Advanced** settings (in the service configuration). By default, Harness searches for `serverless.yml`, `serverless.yaml`, `serverless.json`, or `serverlessDefaultStack.yml`. The custom path is passed as `--config` to the CLI and applies to both the Package and Deploy steps.

{% hint style="warning" %}
**V4 and custom config files**

When using Serverless V4 with a custom config file path, remove any default `serverless.yml` from the same directory. V4 reads the default filename even when `--config` is set, and fails if the default file is invalid.
{% endhint %}

***

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

* Go to [Serverless Rollback](/continuous-delivery/3.0/use-deployments/overview-2/serverless-package/serverless-rollback.md) to review how rollback works when this step fails

{% @harness-feedback/feedback %}