> 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/use-continuous-delivery/cd-building-blocks/cd-steps/containerized-steps/background-step.md). # Background step Run dependent services, including Docker in Docker, for the lifetime of a Continuous Delivery step group or stage Background steps run dependent services needed for the entire lifetime of a Continuous Delivery step group or stage. For example, you can set up your stage to run multiple background services that implement a local, multi-service app. {% hint style="info" %} **Check that the service is running** A Background step starts a service and then proceeds. For any later step that relies on the service, verify that the service is running before you send requests. {% endhint %} *** ## What you will learn from this topic * How to [add a Background step for Docker in Docker](#docker-in-docker-dind) in a containerized step group * How to [name the step and call its service](#name-and-id) from a later step * How to set the [image](#image), [entry point](#entry-point), and [command](#shell-and-command) * How to [read the DinD setup in the step log](#dind-background-step-example) and confirm the Background step started *** ## Before you begin Review the following setup before you add a Background step: * **Containerized step group**: Add the Background step inside a containerized step group. Go to [Containerize step groups](/continuous-delivery/use-continuous-delivery/cd-building-blocks/cd-steps/containerized-steps/containerized-step-groups.md) to run Continuous Delivery steps on your Kubernetes cluster. * **Cluster and connector access**: You need a Kubernetes cluster and a Harness Kubernetes connector the step group can use. Go to [Containerize step groups](/continuous-delivery/use-continuous-delivery/cd-building-blocks/cd-steps/containerized-steps/containerized-step-groups.md) to review infrastructure requirements. * **Pipeline edit access**: View and Create/Edit permissions on Pipelines so you can add or edit steps. Go to [RBAC in Harness](https://developer.harness.io/docs/platform/role-based-access-control/rbac-in-harness) to configure roles. *** ## Docker in Docker (DinD) Some steps in a containerized step group might require Docker in Docker (DinD). For example, some deployment types might use DinD because of the requirements of their platforms. {% hint style="info" %} **When Docker in Docker is required** There is no DinD requirement for containerized step groups. Unless a step requires DinD, Harness needs only a Kubernetes cluster to run the containerized step. If a Harness deployment type requires DinD, the Background step is added automatically as part of the stage Execution setup. Whether the DinD step is added automatically or manually, you must configure it. {% endhint %} If any step in a containerized step group requires DinD, you can add a **Background** step that performs the Docker in Docker (DinD) setup. ![Background step inside a step group on the pipeline canvas](https://3694223630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fy1JhZ4oKIppwY7d5AhPj%2Fuploads%2Fgit-blob-40fed02619e4fab46e30e4fb4753ccecc3f2850a%2F709bba43286b3b8e4d1b2eb92808ed7bba988683567f70ea769bba38cee914cc.png?alt=media) The Background step creates the DinD environment. In this environment, each subsequent step group step runs inside the Kubernetes pod as containers. *** ## Background step settings The Background step has the following settings. ### Name and Id When you name the step, Harness automatically adds an [Id](https://developer.harness.io/docs/platform/references/entity-identifier-reference/) based on the name. You can use the Background step Id to call services started by Background steps in later steps, such as commands in Run steps. For example, a cURL command could call `STEPGROUPID_BACKGROUNDSTEPID:5000` where it might otherwise call `localhost:5000`. ![Background step Id pythonserver used by a Run step command that calls pythonserver on port 5000](https://3694223630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fy1JhZ4oKIppwY7d5AhPj%2Fuploads%2Fgit-blob-2de4864202cae4091b45dd38baeec01d6ac14357%2F1d52c641a8b442054d83fc2b8bacc1917371f53c7100a0fcf0a7b6666342ce2e.png?alt=media) You must include the step group Id, such as `curl STEP_GROUP_ID_BACKGROUND_STEP_ID:5000`, even if both steps are in the same step group. ### Container registry **Container Registry** is the Harness container registry connector that connects to the container registry hosting the image to use for this step. ### Image This is the container image to use for the background service. For example, `docker:dind`. The image name should include the tag, or it defaults to the `latest` tag if unspecified. You can use any Docker image from any Docker registry, including Docker images from private registries. Different container registries require different name formats: * **Docker Registry**: Enter the name of the artifact you want to use, such as `library/tomcat`. Wildcards are not supported. The fully qualified name (FQN) is required for images in private container registries. * **ECR**: Enter the FQN of the artifact you want to use. Images in repos must reference a path, for example: `.dkr.ecr.us-east-1.amazonaws.com/todolist:0.2`. * **GCR**: Enter the FQN of the artifact you want to use. Images in repos must reference a path starting with the project Id that the artifact is in, for example: `us.gcr.io//quickstart-image:latest`. {% hint style="warning" %} **Google Container Registry (GCR)** Google Container Registry (GCR) is deprecated. Go to [Google Container Registry (GCR)](/continuous-delivery/use-continuous-delivery/cd-building-blocks/services/artifact-sources.md#google-container-registry-gcr) to review the deprecation notice and migration guidance. {% endhint %} ### Entry point Supply a list of arguments in `exec` format. Enter each argument separately. {% tabs %} {% tab title="Visual" %} ![Entry Point arguments dockerd-entrypoint.sh and --mtu=1450 in the visual editor](https://3694223630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fy1JhZ4oKIppwY7d5AhPj%2Fuploads%2Fgit-blob-992d4278e8dde5e6f9a49473064d74fbeef5b1f8%2F0c005ac860103a5b7fb3355c95dc13ff5eab09baae3d7636ec7bf40c7ccc166e.png?alt=media) {% endtab %} {% tab title="YAML" %} ```yaml entrypoint: - dockerd-entrypoint.sh - "--mtu=1450" ``` {% endtab %} {% endtabs %} **Entry Point** arguments override the image `ENTRYPOINT` and any commands in the **Command** field. ### Shell and command For **Shell**, select the shell script type for the arguments and commands defined in **Entry Point** and **Command**. In **Command**, enter POSIX shell script commands to execute inside the container. For example, a command that checks the Java version installed on the system and verifies if it is equal to 17: ```bash JAVA_VER=$(java -version 2>&1 | head -1 | cut -d'"' -f2 | sed '/^1\./s///' | cut -d'.' -f1) if [[ $JAVA_VER == 17 ]]; then echo successfully installed $JAVA_VER else exit 1 fi ``` The following notes apply to commands in this step: * You can use `docker-compose up` to start multiple services in one Background step. * You can run PowerShell commands on Windows VMs running in AWS build farms. * You can run PowerShell Core commands in pods or containers that have pwsh installed. ### Privileged Enable this option to run the container with escalated privileges. This is equivalent to running a container with the Docker `--privileged` flag. ### Report paths Specify the file paths or directories within the container where various reports or log files generated by applications or processes running inside the container are stored. ### Environment variables You can inject environment variables into a container and use them in the **Command** script. You must enter a **Name** and **Value** for each variable. You can reference environment variables in the **Command** script by their name. For example, a Bash script would use `$var_name` or `${var_name}`, and a Windows PowerShell script would use `$Env:varName`. ### Image pull policy Select an option to set the pull policy for the image: * **Always**: The kubelet queries the container image registry to resolve the name to an image digest every time the kubelet launches a container. If the kubelet encounters an exact digest cached locally, it uses its cached image; otherwise, the kubelet downloads (pulls) the image with the resolved digest, and uses that image to launch the container. * **If Not Present**: The image is pulled only if it is not already present locally. * **Never**: The image is assumed to exist locally. No attempt is made to pull the image. ### Set container resources Maximum resource limits for containers that run this Background step. Go to [Resource units in Kubernetes](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) to review Kubernetes resource units. ### DinD Background step example When you run a pipeline that uses a containerized step group and Background step, you can see the DinD set up in the step log in the pipeline execution. Select the step to see its log and how the DinD is set up. The general sequence is: 1. The log shows certificate requests being self-signed for the Docker in Docker (DinD) server and client. 2. The DinD environment is starting up. 3. It indicates that containerd is not running and starts the managed containerd process. 4. Containerd starts with information about the revision and version. 5. Various plugins are loaded, such as snapshotter, content, metadata, differ, event, GC scheduler, lease manager, NRI (disabled), runtime, sandbox, streaming, and services. 6. The log ends without further actions or errors. *** ## Advanced settings In **Advanced**, you can use the following options: * [Conditional execution](/continuous-delivery/use-continuous-delivery/cd-building-blocks/executions/step-and-stage-conditional-execution-settings.md) * [Failure strategy](/continuous-delivery/use-continuous-delivery/cd-building-blocks/executions/step-failure-strategy-settings.md) * [Looping strategy](https://developer.harness.io/docs/platform/pipelines/looping-strategies/looping-strategies-matrix-repeat-and-parallelism) * [Policy enforcement](/continuous-delivery/use-continuous-delivery/cd-building-blocks/advanced/cd-governance/harness-governance-overview.md) *** ## Troubleshooting
Later steps cannot reach the Background service on localhost Call the service with the step group Id and Background step Id, for example `STEP_GROUP_ID_BACKGROUND_STEP_ID:5000`. Do not use `localhost` alone when the caller runs in another container in the step group.
DinD Background step fails to start Confirm that **Privileged** is enabled when the image requires it (for example DinD), that the image and tag exist in the selected registry, and that the Kubernetes cluster allows privileged pods.
Background service is not ready when the next step runs A Background step starts the service and then proceeds. Add a check in a later Run step (for example a health or port check) before you send traffic to the service.
*** ## Next steps * [Containerize step groups](/continuous-delivery/use-continuous-delivery/cd-building-blocks/cd-steps/containerized-steps/containerized-step-groups.md): Enable container-based execution for Continuous Delivery steps. * [Run step](/continuous-delivery/use-continuous-delivery/cd-building-blocks/cd-steps/containerized-steps/run-step.md): Run scripts in a container image inside the same step group. * [Conditional execution settings](/continuous-delivery/use-continuous-delivery/cd-building-blocks/executions/step-and-stage-conditional-execution-settings.md): Control when the Background step runs. * [Failure strategy settings](/continuous-delivery/use-continuous-delivery/cd-building-blocks/executions/step-failure-strategy-settings.md): Configure what happens if the step fails. {% @harness-feedback/feedback %}