Ctrlk
Sign UpGet a DemoContact Us
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

  • 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

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

  • A configured Serverless service with a manifest and artifact source.

  • A configured Serverless infrastructure 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 for setup details.

Configure the step

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

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

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

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.

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.

Serverless config file path

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.

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.

Next steps

PreviousServerless Package
NextServerless Rollback

Last updated

Was this helpful?