Skip to main content

Run LocalStack as a Background Step

Background steps are useful for running services that need to run for the entire lifetime of a Build stage. This tutorial shows how to run LocalStack as a Background step in a Harness CI pipeline. LocalStack is software that emulates cloud services (such as AWS) when developing locally, or for testing in continuous integration pipelines.

tip

If you don't have a Harness account yet, you can create one for free at app.harness.io.

Create Your Pipeline​

  1. Create a new pipeline in Harness CI.
  2. Click Add Stage and select Build. Give your stage a name, optionally configure the repository to be cloned, then click Set Up Stage.
  3. Select Cloud in the Infrastructure tab.

Add Background Step​

This will run the LocalStack Docker image as a Background step in your pipeline.

  1. In the Execution tab of your pipeline stage, click Add Step. The Step Library dialogue window should appear, select the Background step.
  2. Enter "localstack" in the Name field.
  3. Expand the Additional Configuration section, click the Container Registry field and either select an existing Docker Hub connector, or create one.
  4. Enter the desired LocalStack Docker image in the Image field (for example, localstack/localstack:1.2.0).
  5. If you have a LocalStack API key, add a LOCALSTACK_API_KEY environment variable in the Environment Variables section.
  6. Click Apply Changes.

Add Step​

This will add a step to ensure the LocalStack service is healthy. The step will run the cURL command to poll the LocalStack service's /health endpoint until it returns successfully. This ensures that LocalStack is ready to receive traffic before the pipeline continues.

  1. In the Execution tab of your pipeline stage, click Add Step then select Run.
  2. Enter "localstack health" in the Name field.
  3. Enter the following command in the Command field.
    until curl --fail --silent --max-time 1 http://localstack:4566/health; do sleep 2; done
  4. Expand the Optional Configuration section, click the Container Registry field and select your Docker Hub connector.
  5. Enter curlimages/curl:7.83.1 in the Images field.
  6. Click Apply Changes.
note

Notice that the curl command is able to reach the LocalStack service at localstack:4566. This is because both the service and step share the same Docker network.

Optional YAML Configuration​

If you switch from Visual to YAML in the Pipeline Studio, your pipeline should look similar to this:

pipeline:
  name: my_pipeline
  identifier: my_pipeline
  projectIdentifier: My_Project
  orgIdentifier: default
  tags: {}
  stages:
    - stage:
        name: Stage 1
        identifier: Stage_1
        description: ""
        type: CI
        spec:
          cloneCodebase: false
          platform:
            os: Linux
            arch: Amd64
          runtime:
            type: Cloud
            spec: {}
          execution:
            steps:
              - step:
                  type: Background
                  name: localstack
                  identifier: localstack
                  spec:
                    connectorRef: docker_hub
                    image: localstack/localstack:1.2.0
                    shell: Sh
                    envVariables:
                      LOCALSTACK_API_KEY: <+secrets.getValue("localstack-api-key")>
              - step:
                  type: Run
                  name: localstack health
                  identifier: localstack_health
                  spec:
                    connectorRef: docker_hub
                    image: curlimages/curl:7.83.1
                    shell: Sh
                    command: until curl --fail --silent --max-time 1 http://localstack:4566/health; do sleep 2; done

Run Your Pipeline​

  1. Click the Save button, then click Run.
  2. Click Run Pipeline in the Run Pipeline dialogue window.
  3. Observe your pipeline execution.
  4. The localstack step logs should show a line similar to this:
    Running on https://0.0.0.0:4566 (CTRL + C to quit)
    Ready.
  5. The localstack health step should complete successfully when the LocalStack service is healthy.