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

# Overview

Set up an AWS SAM deployment pipeline in Harness: configure the Deploy stage, select a runtime, and understand the three steps Harness adds automatically.

A SAM stage lets you build and deploy AWS Serverless Application Model applications by running `sam build` and `sam deploy` inside containerized steps on a Kubernetes cluster. You define the service (your SAM directory manifest), the target infrastructure (AWS connector and region), and Harness manages the build, packaging, and CloudFormation stack update.

***

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

Before you add a SAM deployment stage to a pipeline, make sure you have:

* A Kubernetes cluster for running the containerized SAM steps, with outbound HTTPS access to `app.harness.io`.
* A Harness Kubernetes connector and a namespace in that cluster.
* An AWS connector with the permissions listed in [AWS IAM permissions](#aws-iam-permissions).
* An AWS SAM service with a SAM directory manifest configured. Go to [SAM services](/continuous-delivery/3.0/use-deployments/aws-sam/sam-services.md) to set one up.
* A Harness environment with an AWS SAM infrastructure definition. Go to [SAM infrastructure](/continuous-delivery/3.0/use-deployments/aws-sam/sam-infrastructure.md) to set one up.

***

### AWS IAM permissions <a href="#aws-iam-permissions" id="aws-iam-permissions"></a>

The AWS connector used in the SAM Build and SAM Deploy steps must have permissions across the following AWS services. The exact actions required depend on your SAM template, but the following are the common permissions needed for a standard SAM deployment.

**CloudFormation**

The connector must be able to create, update, describe, and delete CloudFormation stacks. At minimum: `cloudformation:CreateStack`, `cloudformation:UpdateStack`, `cloudformation:DeleteStack`, `cloudformation:DescribeStacks`, `cloudformation:DescribeStackEvents`, `cloudformation:DescribeStackResources`, `cloudformation:GetTemplate`, `cloudformation:ValidateTemplate`, `cloudformation:CreateChangeSet`, `cloudformation:ExecuteChangeSet`, `cloudformation:DescribeChangeSets`, `cloudformation:DeleteChangeSet`.

**S3**

SAM uses S3 to store deployment artifacts. Required actions: `s3:GetObject`, `s3:PutObject`, `s3:GetBucketLocation`, `s3:ListBucket`, `s3:CreateBucket`.

**Lambda**

To create or update Lambda functions: `lambda:CreateFunction`, `lambda:UpdateFunctionCode`, `lambda:UpdateFunctionConfiguration`, `lambda:GetFunction`, `lambda:DeleteFunction`, `lambda:AddPermission`, `lambda:RemovePermission`, `lambda:CreateAlias`, `lambda:UpdateAlias`, `lambda:GetAlias`, `lambda:ListFunctions`.

**IAM**

When the SAM template creates IAM roles such as Lambda execution roles: `iam:CreateRole`, `iam:DeleteRole`, `iam:GetRole`, `iam:PutRolePolicy`, `iam:DeleteRolePolicy`, `iam:AttachRolePolicy`, `iam:DetachRolePolicy`, `iam:PassRole`.

**API Gateway (if your SAM template includes APIs)**

`apigateway:POST`, `apigateway:GET`, `apigateway:PUT`, `apigateway:DELETE`, `apigateway:PATCH`.

**CloudWatch Logs (if your Lambda functions write logs)**

`logs:CreateLogGroup`, `logs:DeleteLogGroup`, `logs:DescribeLogGroups`, `logs:PutRetentionPolicy`.

***

### Set up a SAM deployment <a href="#set-up-a-sam-deployment" id="set-up-a-sam-deployment"></a>

When you create a pipeline, Harness adds a default Stage 1 automatically. Editing an existing stage does not give you the deployment strategy wizard. To get the full wizard, including the execution strategy step where you select the AWS SAM Deploy strategy and configure the Kubernetes runtime, you need to create a new stage.

1. Go to **Pipelines** and select **Create Pipeline**.
2. Enter a pipeline name. Under **Storage**, select **Inline** or a Git repository. Select **Create**.
3. Delete the default **Stage 1**, then select the **+** icon to add a new stage.
4. When prompted with "What would you like to do?", select **Deploy** and select **Next**.
5. Enter a stage name, set **Deployment Target** to **AWS SAM**, and select **Next**.

The wizard then walks you through service, environment, deployment strategy, and runtime in sequence.

**Configure service and environment:**

6. On the **Service** tab, select your AWS SAM service or create a new one. Go to [SAM services](/continuous-delivery/3.0/use-deployments/aws-sam/sam-services.md) to configure a service.
7. On the **Environment** tab, select your environment and infrastructure definition. Go to [SAM infrastructure](/continuous-delivery/3.0/use-deployments/aws-sam/sam-infrastructure.md) to configure an environment and infrastructure definition.

**Select the deployment strategy:**

8. On the **Deployment Strategy** tab, select **AWS SAM Deploy**.
9. Select **Next**.

**Configure the runtime:**

10. On the **Runtime** tab, select your runner: **Harness Cloud**, **Delegate**, or **Kubernetes** (Ephemeral Pod).
11. For **Kubernetes**: set **Connector** to your Kubernetes cluster connector and **Namespace** to the namespace where step group pods run.
12. Select **Use**.

Harness adds three steps to the stage and opens the execution view. Go to [Execution steps](#execution-steps) for details on each step.

***

### Execution steps <a href="#execution-steps" id="execution-steps"></a>

Harness adds the following steps when you select the AWS SAM Deploy strategy. A Service step also runs automatically before these to fetch your SAM directory and Values YAML manifests.

**Docker in Docker (background step)**

The DinD step starts a Docker daemon inside the pod. SAM Build requires this daemon when `--use-container` is set, so that Lambda packages are built inside a Lambda-compatible container. The step stays active for the duration of the stage. Harness sets `/var/lib/docker` and `/var/run` as shared paths so the Docker socket is accessible to the SAM Build and SAM Deploy containers.

**AWS SAM Build**

Runs `sam build` against the downloaded SAM directory. Configure the command options, Docker registry credentials, and step container image in this step. Go to [SAM Build](/continuous-delivery/3.0/use-deployments/aws-sam/sam-build.md) for the full field reference.

**AWS SAM Deploy**

Runs `sam deploy` to package and deploy the CloudFormation stack. Configure the stack name, deploy command options, and container registry credentials in this step. Go to [SAM Deploy](/continuous-delivery/3.0/use-deployments/aws-sam/sam-deploy.md) for the full field reference.

***

### Stage settings <a href="#stage-settings" id="stage-settings"></a>

Each stage has a set of settings accessible from the stage editor, organized into four sections: **Code & build**, **Inputs & outputs**, **Execution controls**, and **Runtime Environment**.

***

#### Code & build <a href="#code-and-build" id="code-and-build"></a>

Controls whether the stage clones source code before running steps. SAM stages do not need this; the Service step fetches SAM directory manifests separately.

```yaml
clone:
  disabled: true
```

***

#### Inputs & outputs <a href="#inputs-and-outputs" id="inputs-and-outputs"></a>

Define this stage's inputs, environment variables, and outputs.

**Inputs:** declare typed inputs available as `${{inputs.<name>}}` within the stage.

**Outputs:** declare typed outputs the stage produces, available to downstream stages.

**Environment variables:** set key-value pairs available to all steps in the stage.

***

#### Execution controls <a href="#execution-controls" id="execution-controls"></a>

Set conditions, looping strategy, concurrency, failure strategy, and timeout.

**Strategy** — configures a looping strategy so the stage runs multiple times across a set of values or conditions.

Use **Matrix** to deploy the same SAM service to multiple infrastructure definitions in a single run. Reference the matrix variable with `${{matrix.<key>}}` in `deploy-to`.

```yaml
environment:
  id: <environment-id>
  deploy-to: ${{matrix.infra}}
strategy:
  matrix:
    infra:
      - <infra-id-1>
      - <infra-id-2>
```

Harness runs one parallel deployment per matrix value. Each deployment uses the connector and region from that infrastructure definition.

Use **For loop** to run the stage a fixed number of times.

```yaml
strategy:
  for:
    iterations: 3
```

Add `fast-fail: true` to any strategy to stop remaining iterations immediately if one fails.

**Concurrency** — limits how many instances of this stage can run simultaneously across pipeline executions.

**On failure** — defines what Harness does when the stage fails. Rollback is not triggered automatically — it only runs when `on-failure` is explicitly configured with `action: stage-rollback`. Harness adds this by default when you create a SAM stage through the wizard. CloudFormation handles the actual stack rollback independently.

```yaml
on-failure:
  errors: all
  action: stage-rollback
```

**Conditional execution** — controls whether the stage runs based on an expression evaluated at runtime.

```yaml
when:
  condition: "${{inputs.deploy_env == 'prod'}}"
```

**Timeout duration** — maximum time the stage is allowed to run before Harness terminates it. Default: `24h`.

```yaml
timeout: 20m
```

***

#### Runtime environment <a href="#runtime-environment" id="runtime-environment"></a>

Configure where the stage runs.

**Platform** — sets the operating system and CPU architecture for the stage execution environment.

```yaml
platform:
  os: linux
  arch: amd64
```

**Runtime** — defines which runner executes the stage steps. All three runtime options are supported.

**Harness Cloud** — steps run on Harness-managed infrastructure.

```yaml
runtime:
  cloud: {}
```

**Delegate** — steps run on a configured Harness delegate.

```yaml
runtime:
  delegate: {}
```

**Kubernetes (Ephemeral Pod)** — steps run as pods on a cluster you specify.

```yaml
runtime:
  kubernetes:
    namespace: <target-namespace>
    connector: <kubernetes-connector-id>
    automount-service-token: true
    pull: always
```

The following fields are available in the `runtime.kubernetes` block.

| Field                       | Required | Description                                                                                                                                        |
| --------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Connector**               | Yes      | A Harness Kubernetes cluster connector for the cluster where steps run.                                                                            |
| **Namespace**               | Yes      | The Kubernetes namespace for the step group pods.                                                                                                  |
| **Automount service token** | Optional | Mount the pod service account token. Enable this when using AWS IRSA to authenticate via a Kubernetes service account with an IAM role annotation. |
| **Pull**                    | Optional | Image pull policy for the step containers. Set to `always` to ensure the latest plugin image is used.                                              |

**Shared paths:** Harness sets the following paths automatically when you select the AWS SAM Deploy strategy. Do not remove them; SAM Build requires the Docker socket exposed by the DinD container.

```yaml
shared-paths:
  - /var/lib/docker
  - /var/run
```

***

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

* Go to [SAM services](/continuous-delivery/3.0/use-deployments/aws-sam/sam-services.md) to configure the SAM directory manifest and values file.
* Go to [SAM infrastructure](/continuous-delivery/3.0/use-deployments/aws-sam/sam-infrastructure.md) to configure environments and infrastructure definitions.
* Go to [AWS SAM Deploy](/continuous-delivery/3.0/use-deployments/aws-sam/aws-sam-deploy.md) for the full strategy walkthrough, step configuration, and stage YAML reference.
* Go to [SAM Build](/continuous-delivery/3.0/use-deployments/aws-sam/sam-build.md) for the build step field reference.
* Go to [SAM Deploy](/continuous-delivery/3.0/use-deployments/aws-sam/sam-deploy.md) for the deploy step field reference.

{% @harness-feedback/feedback %}