Skip to main content

Connect to the Harness container image registry

When you run a Harness pipeline, the Harness Delegate makes an anonymous outbound connection, through a Docker connector, to pull the required Harness images used for backend processes, such as Harness CI images, from the public registry where they are stored.

By default, Harness uses the built-in Harness Image Docker connector with anonymous access to pull these images from a public container registry. There are three ways you can modify the default behavior for pulling Harness images:

All of these options require permissions to create, edit, and view connectors at the account scope.

Rate Limiting

To prevent rate limiting or throttling issues when pulling images, configure the built-in Harness Image Docker connector to use credentials (instead of anonymous access) and pull images from GCR (instead of Docker Hub). For instructions, go to Configure Harness to always use credentials to pull Harness images.

Configure Harness to always use credentials to pull Harness images

If you don't want to connect anonymously, you can configure Harness to always use credentials, instead of anonymous access, to pull the Harness images. This option changes the behavior for your entire account by editing the credentials of the built-in Harness Docker Connector. This is useful if your organization's security policies don't allow anonymous connections to public image repos.

If you don't want to change the behavior for your entire account, you can Use credentials to pull Harness images for specific stages.

  1. Go to Account Settings, select Account Resources, and then select Connectors.

  2. Select the Harness Docker Connector (Id: harnessImage).

    If there is no connector with the harnessImage identifier in your Account, you need to create a Docker connector with the exact Id of harnessImage. Harness gives precedence to the connector with the harnessImage identifier and uses it to pull the images.

  3. Select Edit Details.

  4. Select Continue to go to the Details settings.

  5. Recommended: To pull images from the Harness project on GCR instead of Docker Hub, select Other (Docker V2 compliant) for Provider Type, and then enter gcr.io/gcr-prod for Docker Registry URL. You can also pull images from Docker Hub by selecting Docker Hub and entering https://registry.hub.docker.com.

  6. For Authentication, select Username and Password, and provide a username and token to access Docker Hub or GCR,depending on the Docker Registry URL. The token needs read, write, and delete permissions.

  7. Select Continue to go to Select Connectivity Mode, and then configure the connector to connect through a Harness Delegate or the Harness Platform.

  8. Select Save and Continue, wait for the connectivity test to run, and then select Finish.

    If the connectivity test fails, make sure your connector's credentials are configured correctly and that the token has the necessary permissions.

Use credentials to pull Harness images for specific stages

If you don't want to connect anonymously, you can configure Harness to use credentials, instead of anonymous access, to pull the Harness images for specific stages in your pipelines. This option lets you override the Harness image pull behavior in individual Build stages by creating a dedicated Docker connector you can use for these specific use cases. This is useful when the delegate for that stage's build infrastructure can't anonymously access the public repo. For example, if the build infrastructure is running in a private cloud.

If you want to change the behavior for your entire account, you can configure Harness to always use credentials to pull Harness images.

  1. Go to Account Settings, select Account Resources, and then select Connectors.

    Although you will select the connector at the stage scope, you must create the Docker connector at the account scope.

  2. Select New Connector, and, under Artifact Repositories, select the Docker Registry connector.

  3. Enter a Name for the connector. The Description and Tags are optional.

    Harness automatically creates an Id (entity identifier) based on the Name. You can edit the Id while creating the connector only. After saving the connector, the Id can't be changed.

  4. Select Continue.

  5. For Provider Type, select Other (Docker V2 compliant).

  6. For Docker Registry URL, enter gcr.io/gcr-prod.

  7. For Authentication, select Username and Password, and provide a username and token to access GCR. The token needs Read, Write, Delete permissions.

  8. Select Continue to go to Select Connectivity Mode, and then configure the connector to connect through a Harness Delegate or the Harness Platform.

  9. Select Save and Continue, wait for the connectivity test to run, and then select Finish.

    If the connectivity test fails, make sure your connector's credentials are configured correctly and that the token has the necessary permissions.

  10. In the Build stage where you want to use your Docker connector, go to the Infrastructure settings, and select your Docker connector in the Override Image Connector field.

When the pipeline runs, Harness will use the specified connector to download images from the Harness project on GCR.

Pull Harness images from a private registry

Harness CI images are stored in a public container registry. If you don't want to pull the images directly from the public registry, you can download the images you need, perform any necessary security checks, upload them to your private registry, and then configure your CI pipelines to pull the Harness CI images from your private registry.

You can also use a private registry for STO scanner images.

Download Harness images to your registry

  1. Download the images you need from the Harness project on GCR, perform any tests or validations necessary for your organization's security policies, and then store the images in your private registry.

    warning

    Do not change the image names in your private registry. The image names must match the names specified by Harness.

  2. Recommended: Specify the images to use in your pipelines. This is recommended especially if your registry automatically downloads the latest images from the public Harness registry. This ensures your pipelines use specific image versions that you have validated, rather than automatically using the latest version. You must update this specification when you want to adopt a new version of an image.

Create a Docker connector for your registry

Create a Docker connector that connects to your private registry.

  1. Go to Account Settings, select Account Resources, and then select Connectors. You must create the Docker connector at the account scope.

  2. Select New Connector, and, under Artifact Repositories, select the Docker Registry connector.

  3. Enter a Name for the connector. The Description and Tags are optional.

    Harness automatically creates an Id (entity identifier) based on the Name. You can edit the Id while creating the connector only. After saving the connector, the Id can't be changed.

  4. Select Continue.

  5. For Provider Type, select Other (Docker V2 compliant).

  6. For Docker Registry URL, enter the path for your container registry. For example, the path for the public Harness GCR project is gcr.io/gcr-prod.

  7. For Authentication, select Username and Password, and provide a username and token to access your registry. The token needs Read, Write, Delete permissions.

  8. Select Continue to go to Select Connectivity Mode, and then configure the connector to connect through a Harness Delegate or the Harness Platform.

  9. Select Save and Continue, wait for the connectivity test to run, and then select Finish.

    If the connectivity test fails, make sure your connector's credentials are configured correctly and that the token has the necessary permissions.

  10. Configure your pipelines to download Harness images from your private registry. In each Build stage where you want to pull from your private registry, go to the Infrastructure settings, and select your Docker connector in the Override Image Connector field.

When the pipeline runs, Harness will use the specified connector to download images from your private registry.

Connector selection hierarchy

When selecting the connector to use to pull images, Harness follows this hierarchy:

  1. Check for a connector specified at the stage level, such as when pulling Harness images from a private registry or using credentials to pull Harness images for specific stages.
  2. If there is no stage-level connector, use the account-level Harness Image connector (ID: account.harnessImage), which can use the default anonymous access configuration or you can configure it to always use credentials to pull Harness images.

Deprecation notice: app.harness Docker registry

Harness images are available on Docker Hub and the Harness project on GCR. In a continuation of this effort, and to improve stability when pulling Harness-required images, Harness is deprecating the Harness-hosted app.harness Docker registry effective 15 February 2024.

You will be impacted by this deprecation if:

Troubleshoot Harness images

Go to the CI Knowledge Base for questions and issues related to Harness-required images, connectors, and pipeline initialization, such as: