Docker in Docker

Reference for the Docker in Docker background step — starts a Docker daemon inside the pod so SAM Build can run container-based builds.

What you will learn

• What the Docker in Docker background step does and why SAM Build requires it for container-based builds.

• How to configure the DinD step image and connector when your cluster cannot reach Docker Hub directly.

---

The Docker in Docker (DinD) step is a background step that runs a Docker daemon inside the Kubernetes pod for the duration of the SAM stage. SAM Build requires a running Docker daemon when --use-container is set in the build command options, so that Lambda packages are built inside a Lambda-compatible container rather than on the host directly.

Harness configures this step automatically when you select the AWS SAM Deploy strategy. For most deployments you do not need to change any settings. The only reason to modify this step is if your Kubernetes cluster cannot pull docker:dind from Docker Hub directly — in that case, update the Image and Image connector fields to point to your private registry.

---

How it works

When the stage starts, the DinD container launches and starts the Docker daemon process. 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 running in the same pod. SAM Build polls for a running daemon before starting (controlled by Docker Retry Count on the build step), then connects through the shared socket to build Lambda packages inside a container.

The DinD step runs as a background step — it does not complete on its own and stays active until the stage finishes.

---

Settings

The following fields are available when you edit the Docker in Docker step.

Field	Required	Description
Name	Yes	Display name for the step. Default: Docker in Docker.
Shell	Optional	Shell used to run the script. Default: Sh.
Script	Optional	Script to run inside the container on startup.
Environment variables	No	Key-value pairs to set as environment variables inside the DinD container.
Image	Yes	The Docker image to run. Default: docker:dind.
Image connector	Yes	Harness connector for the registry that hosts the image. Default: harnessImage (Docker Hub via Harness).
Pull	Optional	Image pull policy. Default: Always.
Entrypoint	Optional	Override the container entrypoint.
Args	Optional	Arguments to pass to the container.
DNS	Optional	Custom DNS servers for the container.
Environment	Optional	Additional environment variables set at the container level.
Extra hosts	Optional	Additional host entries to add to /etc/hosts inside the container.
Network	Optional	Network mode for the container.

---

Step YAML

- name: Docker in Docker
  id: dind
  background:
    shell: sh
    container:
      image: docker:dind
      connector: account.harnessImage
      privileged: true
      pull: always

---

Next steps

• Go to SAM Build for the build step that connects to the Docker daemon this step provides.

• Go to AWS SAM Deploy for the full stage walkthrough including shared paths configuration.