> 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/docker-in-docker.md).

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

* 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 <a href="#how-it-works" id="how-it-works"></a>

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 <a href="#settings" id="settings"></a>

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

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

***

### 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 build step that connects to the Docker daemon this step provides.
* Go to [AWS SAM Deploy](/continuous-delivery/3.0/use-deployments/overview-5/aws-sam-deploy.md) for the full stage walkthrough including shared paths configuration.

{% @harness-feedback/feedback %}