> 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-5/aws-sam-deploy.md).

# 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 <a href="#what-you-will-learn" id="what-you-will-learn"></a>

* 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 <a href="#select-the-strategy" id="select-the-strategy"></a>

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

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

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

***

### Step 1: Docker in Docker <a href="#step-1-dind" id="step-1-dind"></a>

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](/continuous-delivery/3.0/use-deployments/overview-5/docker-in-docker.md) for the full field reference.

***

### Step 2: Configure the SAM Build step <a href="#step-2-sam-build" id="step-2-sam-build"></a>

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`.                                                                                                                        |

{% hint style="info" %}
**`--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.
{% endhint %}

***

### Step 3: Configure the SAM Deploy step <a href="#step-3-sam-deploy" id="step-3-sam-deploy"></a>

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`.                                                                                                                        |

{% hint style="info" %}
**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.
{% endhint %}

***

### What happens during execution <a href="#what-happens-during-execution" id="what-happens-during-execution"></a>

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

1. **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.
2. **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**.
3. **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.
4. **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.
5. **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 <a href="#stage-yaml" id="stage-yaml"></a>

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

```yaml
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 <a href="#next-steps" id="next-steps"></a>

* Go to [SAM Build](/continuous-delivery/3.0/use-deployments/overview-5/sam-build.md) for the complete build step field reference.
* Go to [SAM Deploy](/continuous-delivery/3.0/use-deployments/overview-5/sam-deploy.md) for the complete deploy step field reference.
* Go to [SAM services](/continuous-delivery/3.0/use-deployments/overview-5/sam-services.md) to configure the SAM manifest and values file.
* Go to [SAM infrastructure](/continuous-delivery/3.0/use-deployments/overview-5/sam-infrastructure.md) to configure the AWS connector and region for the infrastructure definition.

{% @harness-feedback/feedback %}