AWS SAM
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
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.
An AWS SAM service with a SAM directory manifest configured. Go to SAM services to set one up.
A Harness environment with an AWS SAM infrastructure definition. Go to SAM infrastructure to set one up.
AWS IAM permissions
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
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.
Go to Pipelines and select Create Pipeline.
Enter a pipeline name. Under Storage, select Inline or a Git repository. Select Create.
Delete the default Stage 1, then select the + icon to add a new stage.
When prompted with "What would you like to do?", select Deploy and select Next.
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:
On the Service tab, select your AWS SAM service or create a new one. Go to SAM services to configure a service.
On the Environment tab, select your environment and infrastructure definition. Go to SAM infrastructure to configure an environment and infrastructure definition.
Select the deployment strategy:
On the Deployment Strategy tab, select AWS SAM Deploy.
Select Next.
Configure the runtime:
On the Runtime tab, select your runner: Harness Cloud, Delegate, or Kubernetes (Ephemeral Pod).
For Kubernetes: set Connector to your Kubernetes cluster connector and Namespace to the namespace where step group pods run.
Select Use.
Harness adds three steps to the stage and opens the execution view. Go to Execution steps for details on each step.
Execution steps
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 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 for the full field reference.
Stage settings
Each stage has a set of settings accessible from the stage editor, organized into four sections: Runtime Environment, Code & build, Inputs & outputs, and Execution controls.
Runtime environment
Configure where the stage runs.
Platform — sets the operating system and CPU architecture for the stage execution environment.
Runtime — defines which runner executes the stage steps. All three runtime options are supported.
Harness Cloud — steps run on Harness-managed infrastructure.
Delegate — steps run on a configured Classic Delegate or Delegate 3.x (on Harness Cloud for deployments).
Kubernetes (Ephemeral Pod) — steps run as pods on a cluster you specify.
The following fields are available in the runtime.kubernetes block.
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.
Next steps
Go to SAM services to configure the SAM directory manifest and values file.
Go to SAM infrastructure to configure environments and infrastructure definitions.
Go to AWS SAM Deploy for the full strategy walkthrough, step configuration, and stage YAML reference.
Go to SAM Build for the build step field reference.
Go to SAM Deploy for the deploy step field reference.
Last updated
Was this helpful?