AWS SAM Deploy

Configure and run an AWS SAM deployment in Harness: three auto-added steps, how to configure each one, and what happens during execution.

What you will learn

How to configure the three steps Harness adds automatically when you select the AWS SAM Deploy strategy: Docker in Docker, SAM Build, and SAM Deploy.
What happens during execution and how CloudFormation handles rollback when a deployment fails.

When you select AWS SAM Deploy as the deployment strategy, Harness adds three steps to the stage automatically: a Docker in Docker background step, an AWS SAM Build step, and an AWS SAM Deploy step. You configure each step with your AWS connector, region, stack name, and command options before running the pipeline.

Select the strategy

When adding a Deploy stage with AWS SAM as the deployment target:

On the Deployment Strategy tab, select AWS SAM Deploy.
Select Next.
On the Runtime tab, select your runner: Harness Cloud, Delegate, or Kubernetes (Ephemeral Pod). For Kubernetes, configure the cluster connector and namespace.
Select Use.

Harness opens the execution view with three steps already added to the stage.

Step 1: Docker in Docker

The Docker in Docker (DinD) step is a background step that starts a Docker daemon inside the pod and keeps it running for the duration of the stage. SAM Build connects to this daemon when --use-container is set, so that Lambda packages are built inside a Lambda-compatible container rather than on the host directly.

Harness configures this step automatically. The stage sets /var/lib/docker and /var/run as shared paths, which exposes the Docker socket to the SAM Build and SAM Deploy containers in the same pod.

By default the step runs docker:dind pulled via the harnessImage connector (Docker Hub). You do not need to change any settings for most deployments. If your cluster cannot reach Docker Hub, update the Image and Image connector fields under Container to point to your private registry.

Go to Docker in Docker for the full field reference.

Step 2: Configure the SAM Build step

The SAM Build step runs sam build against the SAM directory downloaded from your service manifest. Select the step in the execution view to open its settings.

Field

Required

Description

Template File Path

Optional

Overrides the template file defined in the service. Path is relative to the SAM directory root, for example template.yaml. If not set, Harness uses the template from the service configuration.

Command Options

Optional

Flags passed to sam build. Default: --use-container. Include --use-container to build inside a Lambda-compatible container. This flag is required for most runtimes.

Pre-Execute Command

Optional

Shell command to run before sam build, for example npm install.

Working Directory

Optional

Working directory for the build. Derived from the service configuration.

AWS Connector

Yes

A Harness AWS connector with CloudFormation and S3 permissions. Derived from the infrastructure definition.

Region

Yes

The AWS region for the build, for example us-east-1. Derived from the infrastructure definition.

Docker Retry Count

Optional

Number of times Harness polls for a running Docker daemon before starting. Default: 3.

Docker Registry URL

Optional

Registry URL for pulling the Lambda build container, for example https://index.docker.io/v2/. Required when --use-container is set.

Docker Registry Username

Optional

Username for the container registry.

Docker Registry Password

Optional

Secret reference for the container registry password.

Command Timeout

Optional

Maximum time the step can run, for example 10m.

Log Level

Optional

Logging verbosity. Default: info.

Container Registry

Optional

Harness connector for the registry that hosts the SAM plugin image. Leave empty to use the default image from Docker Hub.

Image

Optional

Container image for this step. Defaults to harnessdev/aws-sam-dev:0.0.12.

--USE-CONTAINER FLAG

Always include --use-container in Command Options. Without it, sam build runs on the host and may produce Lambda packages that are incompatible with the target runtime environment.

Step 3: Configure the SAM Deploy step

The SAM Deploy step packages the build output to S3 and creates or updates the CloudFormation stack. Select the step in the execution view to open its settings.

Field

Required

Description

Stack

Yes

The CloudFormation stack name to create or update.

Template File Path

Optional

Overrides the template file defined in the service. Path is relative to the SAM directory root, for example template.yaml. If not set, Harness uses the template from the service configuration.

Command Options

Optional

Flags passed to sam deploy, for example --capabilities CAPABILITY_IAM --resolve-s3 --no-fail-on-empty-changeset.

Pre-Execute Command

Optional

Shell command to run before sam deploy, for example npm install.

Working Directory

Optional

Working directory for the deploy. Derived from the service configuration.

AWS Connector

Yes

A Harness AWS connector with CloudFormation and S3 permissions. Derived from the infrastructure definition.

Region

Yes

The AWS region to deploy to. Derived from the infrastructure definition and passed as --region to sam deploy automatically.

Docker Registry URL

Optional

Registry URL, for example https://index.docker.io/v2/.

Docker Registry Username

Optional

Username for the container registry.

Docker Registry Password

Optional

Secret reference for the container registry password.

Command Timeout

Optional

Maximum time the step can run, for example 10m.

Log Level

Optional

Logging verbosity. Default: info.

Container Registry

Optional

Harness connector for the registry that hosts the SAM plugin image. Leave empty to use the default image from Docker Hub.

Image

Optional

Container image for this step. Defaults to harnessdev/aws-sam-dev:0.0.12.

COMMON DEPLOY FLAGS

--capabilities CAPABILITY_IAM is required when the SAM template creates IAM roles or policies. --resolve-s3 lets SAM automatically manage the S3 bucket for deployment artifacts. --no-fail-on-empty-changeset prevents the step from failing when the stack is already up to date.

What happens during execution

When the pipeline runs the SAM stage, the following sequence occurs:

Download Manifests — Harness fetches the SAM directory manifest (for example, from S3 or a Git repo) to /harness/<manifest-id>/. If a Values YAML manifest is configured, it is downloaded to its own directory. This step runs automatically before the three configured steps.
Docker in Docker starts — The DinD background step starts the Docker daemon. SAM Build waits until Docker is ready before proceeding, polling up to the number of times set in Docker Retry Count.
SAM Build — Harness runs sam build against the downloaded SAM directory. With --use-container, the build pulls the Lambda runtime container from your configured registry and builds the application packages inside it. Build artifacts are written to .aws-sam/build/ inside the stage workspace.
SAM Deploy — Harness runs sam deploy with your configured options. SAM packages the build artifacts to S3, then calls CloudFormation to create or update the stack. The step waits for the stack to reach a stable state (CREATE_COMPLETE or UPDATE_COMPLETE) and prints CloudFormation events and stack outputs to the step log.
On failure — If the SAM Deploy step fails, CloudFormation automatically rolls the stack back to the last stable state. On a first deployment failure where no previous stack state exists, CloudFormation deletes the partially created stack. Rollback is handled entirely by CloudFormation — Harness does not issue a separate rollback command.

Stage YAML reference

The following is a complete reference YAML for an AWS SAM stage using the unified platform pipeline format.

stages:
  - name: SAM stage
    id: sam_stage
    service: <your-service-id>
    environment:
      id: <your-environment-id>
      deploy-to: <your-infrastructure-id>
    steps:
      - name: Docker in Docker
        id: dind
        background:
          shell: sh
          container:
            image: docker:dind
            connector: account.harnessImage
            privileged: true
            pull: always
      - name: AWS SAM Build
        id: awsSamBuildStep
        template:
          uses: awsSamBuildStep
          with:
            connector: <aws-connector>
            region: <aws-region>
            stack: <cloudformation-stack-name>
            cmd_opts: --use-container
            docker_retry_count: '3'
            registry_url: https://index.docker.io/v2/
            registry_username: <registry-username>
            registry_pwd: <registry-password-secret>
      - name: AWS SAM Deploy
        id: awsSamDeployStep
        template:
          uses: awsSamDeployStep
          with:
            connector: <aws-connector>
            region: <aws-region>
            stack: <cloudformation-stack-name>
            cmd_opts: --capabilities CAPABILITY_IAM --resolve-s3 --no-fail-on-empty-changeset
            registry_url: https://index.docker.io/v2/
            registry_username: <registry-username>
            registry_pwd: <registry-password-secret>
    runtime:
      kubernetes:
        namespace: <kubernetes-namespace>
        connector: <kubernetes-connector>
        automount-service-token: true
        pull: always
    on-failure:
      errors: all
      action: stage-rollback
    timeout: 20m
    shared-paths:
      - /var/lib/docker
      - /var/run

Next steps

Go to SAM Build for the complete build step field reference.
Go to SAM Deploy for the complete deploy step field reference.
Go to SAM services to configure the SAM manifest and values file.
Go to SAM infrastructure to configure the AWS connector and region for the infrastructure definition.

PreviousSAM infrastructure

NextDocker in Docker

Last updated 23 days ago

Was this helpful?