Background step settings

Use Background steps to manage dependent services.

Use Background steps to manage dependent services that need to run for the entire lifetime of a Build stage. For example, you can set up your pipeline to run multiple background services that implement a local, multi-service app.

A Background step starts a service and then proceeds. For any later step that relies on the service, it is good practice to verify that the service is running before sending requests.

• Background steps do not support failure strategies or output variables.

• If the pipeline runs on a VM build infrastructure, you can run the background service directly on the VM rather than in a container. To do this, leave the Container Registry and Image fields blank.

• Depending on the stage's build infrastructure, some settings might be unavailable, optional, or located under Additional Configuration.

Name and Id

Enter a name summarizing the step's purpose. Harness automatically assigns an Id (Entity Identifier Reference) based on the Name. You can change the Id until the step is saved; once saved, the Id is locked.

If you are using a VM, local runner, or the Harness Cloud build infrastructure where the background step is running a container, 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 BackgroundStepId:5000 where it might otherwise call localhost:5000.

If the Background step is inside a step group, you must include step group ID, such as curl StepGroupId_BackgroundStepId:5000, even if both steps are in the same step group.

If the Background step runs directly on the host or in a Kubernetes cluster build infrastructure, do not use the step ID to reference Background steps. Instead, use localhost:host_port. For Background steps running MySQL in a Kubernetes cluster build infrastructure, you must use the IP and host port, such as 127.0.0.1:7001. For more information, go to Port Bindings.

Container Registry and Image

The build environment must have the necessary binaries for the Background step to execute your test commands. Depending on the stage's build infrastructure, Background steps can use binaries that exist in the build environment, or use Container Registry and Image to pull an image, such as a public or private Docker image, that contains the required binaries.

The stage's build infrastructure determines whether these fields are required or optional:

• Kubernetes cluster build infrastructure: Container Registry and Image are always required.

• Local runner build infrastructure: Background steps can use binaries available on the host machine. The Container Registry and Image are required if the machine doesn't have the binaries you need.

• Self-managed AWS/GCP/Azure VM build infrastructure: Background steps can use binaries that you've made available on your build VMs. The Container Registry and Image are required if the VM doesn't have the necessary binaries. These fields are located under Optional Configuration for stages that use self-managed VM build infrastructure.

• Harness Cloud build infrastructure: Background steps can use binaries available on Harness Cloud machines, as described in the image specifications. The Container Registry and Image are required if the machine doesn't have the binary you need. These fields are located under Optional Configuration for stages that use Harness Cloud build infrastructure.

Shell, Entry Point, and Command

Use these fields to define the commands that you need to run in the Background step.

Shell

Select the shell type for the commands defined in Entry Point or Command. Options include: Bash, PowerShell, Pwsh (PowerShell Core), Sh, and Python. If the step includes commands that aren't supported for the selected shell type, the build fails. Required binaries must be available on the build machine or through a specified Container Registry and Image.

Entry Point

Supply a list of arguments in exec format. Entry Point arguments override the image ENTRYPOINT and any commands in the Command field. Enter each argument separately.

If you want to add your Entry Point arguments to the image ENTRYPOINT, include both the image ENTRYPOINT, such as dockerd-entrypoint.sh, and your additional arguments in Entry Point.

Visual

YAML

entrypoint:
  - dockerd-entrypoint.sh
  - "--mtu=1450"

In a Kubernetes cluster build infrastructure, you can use Entry Point to override port mappings when running multiple PostgreSQL instances in Background steps.

Command

Enter POSIX shell script commands (beyond the image ENTRYPOINT) for this step. If the step runs in a container, the commands are executed inside the container.

Bash

This Bash script example checks the Java version.

              - step:
                  ...
                  spec:
                    shell: Bash
                    command: |-
                      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

PowerShell

This is a simple PowerShell Wait-Event example.

              - step:
                  ...
                  spec:
                    shell: Powershell
                    command: Wait-Event -SourceIdentifier "ProcessStarted"

You can run PowerShell commands on Windows VMs running in AWS build farms.

Pwsh

This PowerShell Core example runs ForEach-Object over a list of events.

              - step:
                  ...
                  spec:
                    shell: Pwsh
                    command: |-
                      $Events = Get-EventLog -LogName System -Newest 1000
                      $events | ForEach-Object -Begin {Get-Date} -Process {Out-File -FilePath Events.txt -Append -InputObject $_.Message} -End {Get-Date}

You can run PowerShell Core commands in pods or containers that have pwsh installed.

Sh

In this example, the pulls a python image and executes a shell script (Sh) that runs pytest with code coverage.

              - step:
                  ...
                  spec:
                    connectorRef: YOUR_IMAGE_REGISTRY_CONNECTOR
                    image: python:latest
                    shell: Sh
                    command: |-
                      echo "Welcome to Harness CI"
                      uname -a
                      pip install pytest
                      pip install pytest-cov
                      pip install -r requirements.txt

                      pytest -v --cov --junitxml="result.xml" test_api.py test_api_2.py test_api_3.py

Python

If the shell is Python, supply Python commands directly in command.

This example uses a basic print command.

            steps:
              - step:
                  ...
                  spec:
                    shell: Python
                    command: print('Hello, world!')

You can use docker-compose up to start multiple services in one Background step.

Privileged

Select this option to run the container with escalated privileges. This is the equivalent of running a container with the Docker --privileged flag.

Report Paths

The path to the files that store results in JUnit XML format. You can add multiple paths. If you specify multiple paths, make sure the files contain unique tests to avoid duplicates. Glob is supported.

This setting is required for commands run in the Background step to be able to publish test results.

Environment Variables

You can inject environment variables into the step container and use them in the Command script. You must input a Name and Value for each variable.

You can reference environment variables in the Command script by name. For example, a Bash script would use $var_name or ${var_name}, and a Windows PowerShell script would use $Env:varName.

Variable values can be fixed values, runtime inputs, or expressions. For example, if the value type is expression, you can input a value that references the value of some other setting in the stage or pipeline.

STAGE VARIABLES

Stage variables are inherently available to steps as environment variables.

Image Pull Policy

If the service is running in a container, you can 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.

Port Bindings

The host port and container port binding are similar to port mapping in Docker. Usually the ports are the same unless the default host port for the Background step is already in use by another local service or you are running multiple instances of the same service.

Depending on the Build stage's Infrastructure, some steps might run directly on VMs while other steps run in containers. The port used to communicate with a service started by a Background step depends on where the step is running. For example, assume you create a Background step with the Name and ID myloginservice. To call this service in later steps in the same stage, you use:

• myloginservice:container_port for containerized steps, such as those running in self-managed VM build infrastructures or running Docker images.

• localhost:host_post for steps running in a Kubernetes cluster build infrastructure or directly on the build machine (such as a service running from a binary already installed on the host machine). For steps running MySQL in a Kubernetes cluster build infrastructure, you must use 127.0.0.1:host_port.

SERVICE BINDING INSIDE THE CONTAINER

If your application binds only to 127.0.0.1 inside the container, it will not be reachable from outside the container — even if you configure Port Bindings in Harness. To make the service accessible, ensure the application listens on 0.0.0.0. This binds the service to all available network interfaces inside the container, allowing Docker’s -p port mapping (or Harness Port Bindings) to expose it.

For example, in a Node.js service:

app.listen(8080, "0.0.0.0", () => {
  console.log("Listening...");
});

If your build stage uses Harness Cloud build infrastructure and you are running a Docker image in a Background step, you must specify Port Bindings if you want to reference that Background step in a later step in the pipeline (such as in a cURL command in a Run step). More more information about referencing background services in other steps, go to Name and Id.

Run as User

If the service is running in a container, you can specify the user ID to use for all processes in the pod. For more information about how to set the value, go to Set the security context for a pod.

Set Container Resources

The maximum memory and cores that the container can use.

• Limit Memory: The maximum memory that the container can use. You can express memory as a plain integer or as a fixed-point number using the suffixes G or M. You can also use the power-of-two equivalents Gi and Mi. Do not include spaces when entering a fixed value. The default value is 500Mi.

• Limit CPU: The maximum number of cores that the container can use. CPU limits are measured in CPU units. Fractional requests are allowed; for example, you can specify one hundred millicpu as 0.1 or 100m. The default is 400m. For more information, go to Resource units in Kubernetes.

Troubleshoot Background steps

Go to the CI Knowledge Base for questions and issues related to Background steps, including:

• Do Background steps have limitations?

• Can Background steps run multiple services simultaneously?

• How can a step call a service started by a Background step?

• I can't connect to the hostname using the step ID from my Background step, and I get an "Unknown server host" error

• Why is Background step always marked as successful even if there are failures executing the entry point?

• How can I health check services running in Background steps?