For the complete documentation index, see llms.txt. This page is also available as Markdown.

Run health checks on background services

Use step groups to run health checks on separate background services.

In a CI pipeline, health checks confirm that services are running before the build runs other steps that need to interact with those services. This topic explains how to run a health check on services running in Background steps before running the rest of the steps in the stage. This example uses step groups to run health checks on multiple background services.

What you will learn from this topic

  • How to organize background services into step groups and run them in parallel

  • How to add health check Run steps to each step group to verify services are ready

  • How to configure and finalize the full pipeline for parallel background service health checks

Before you begin

Configure health checks

Create step groups

Add one step group for each background service that you want to run a health check on. If you have multiple health check step groups, organize the step groups to run in parallel.

For example, if you want to run health checks on two services, create two step groups and run them in parallel, as shown in the following YAML example.

 stages:
    - stage:
        identifier: build
        type: CI
        name: build
        spec:
          cloneCodebase: false
          execution:
            steps:
              - parallel: ## Parallel flag.
                  - stepGroup: ## First step group.
                      name: group 1
                      identifier: sg1
                      steps:
                        ...
                  - stepGroup: ## Second step group.
                      name: group 2
                      identifier: sg2
                      steps:
                        ...

Add Background steps

Add a Background step to each step group. A Background step runs a service in the background. Required Background step settings depend on the service you are running and your build infrastructure. The following YAML examples use Background steps to run multiple PostgreSQL instances.

For a Background step to run a service, the build environment must have the necessary binaries. Depending on the stage's build infrastructure, Background steps can use binaries that exist in the build environment or pull an image, such as a public or private Docker image, that contains the required binaries. For more information about when and how to specify images, go to the Background step Container Registry and Image settings.

Add health checks

In each step group, after the Background step, add a Run step that runs a health check on that service. The commands necessary for a health check depend on the service you are running. The following YAML examples use psql commands to run health checks on PostgreSQL services. For more information about this use case, go to Run multiple PostgreSQL instances in Background steps.

For the Run step to run the health check commands, the build environment must have the necessary binaries. Depending on the stage's build infrastructure, Run steps can use binaries that exist in the build environment or pull an image, such as a public or private Docker image, that contains the required binaries. For more information about when and how to specify images, go to the Run step Container Registry and Image settings.

Test and finalize the pipeline

Run your pipeline to test your background services and health checks. You can monitor and review build logs on the Build details page.

Once you have confirmed that the background services and health checks are functioning as expected, configure any remaining steps in this stage, as necessary. Make sure these steps are not in your background service step groups or in parallel with the step groups.

Background steps do not persist across stages.

Pipeline YAML examples

These pipeline YAML examples use two step groups to run health checks on two PostgreSQL services.

Troubleshooting

Health check fails before the background service is ready

If the health check Run step fails because the background service has not finished initializing, increase the sleep duration at the start of the health check command. The default sleep 15 may not be long enough for all services. Increase the value and re-run the pipeline until the service is consistently ready before the health check runs.

Next steps

Last updated

Was this helpful?