Connect to Harness container image registry

Configure how Harness pulls its required container images: anonymously from GAR or ECR, with credentials, for specific stages, or from a private 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 (Id: harnessImage) with anonymous access to pull these images from a public Docker Hub container registry. This topic shows you four ways to modify that default behavior.

What you will learn from this topic

Before you begin

Confirm the following before you configure how Harness pulls its container images:

Permissions: To configure any of the options in this topic, you need 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 GAR or ECR (instead of Docker Hub). For instructions, go to Configure Harness to always use credentials to pull Harness images.

If you use anonymous access on Harness Cloud build infrastructure, use GAR to avoid ECR Public's anonymous pull limit. Public ECR enforces this limit per source IP, and Harness Cloud runners run on GCP, so anonymous ECR pulls see the same limit as any other anonymous caller. This limit does not apply to credentialed ECR access. Go to Pull images anonymously from GAR or ECR for details.

Which option do you need?

Use the following table to match your situation to the option that addresses it:

Situation

Scope of change

Go to

Hitting Docker Hub rate limits and want to stay anonymous

Account-wide

Pull anonymously from GAR or ECR

Security policy disallows anonymous pulls entirely

Account-wide

Always use credentials

Only one build infrastructure/stage cannot pull anonymously (e.g., private cloud)

Single stage

Use credentials for specific stages

Need full control over image provenance, or air-gapped environment

Account-wide

Pull from a private registry

All four options are built on the same underlying action: create or edit a Docker connector. The steps below cover that shared procedure once. Each option after it only calls out what is different (registry URL, auth type, and where the connector lives).

Create or edit a Docker connector

Use this procedure for any of the four options. Where a step differs by option, it is called out inline in that option's section below.

Go to your Harness Account.
In Account Settings, under Account-level resources, select Connectors.
Do one of the following:
- Edit the built-in connector: Select the connector with Id harnessImage. Harness gives this Id precedence for pulling its own images.
- Create a new connector: If the connector with Id harnessImage does not exist, create a new Docker connector with the exact Id.
Click Edit details.

Overview

Click Continue to go to the Details settings.

Details

Select a Provider Type, and enter the Docker Registry URL (see the option-specific table below).
In Authentication, select one of the following options:
- Username and Password: Enter the Username for the account. For Password, create a new Harness Encrypted Text secret or use an existing one.
- Anonymous (no credentials required). For more details, see the option-specific table below. Click Continue.

Select Connectivity Mode

Under Select Connectivity Mode, select how you want Harness to connect to Docker:
- Connect through Harness Platform: Use a direct, secure communication between Harness and Docker.
- Connect through a Harness Delegate: Harness communicates with Docker through a Harness Delegate.

Delegates Setup

In Delegates Setup, use any delegate or enter tags for the specific delegates that you want to allow to connect to this connector. Click Save and Continue.

Connection Test

Click Finish after the connection test succeeds. The connector is listed in Connectors.

Pull images anonymously from GAR or ECR

By default, Harness pulls Harness images from GAR with anonymous access. You can also pull Harness images with anonymous access from GAR or ECR. This option changes the behavior for your entire account by editing the configuration of the built-in Harness Docker Connector. This is useful if you experience rate limiting issues when pulling from Docker Hub.

ECR does not avoid rate limiting on Harness Cloud

If you use Harness Cloud build infrastructure, switching anonymous access to ECR does not resolve rate limiting. Public ECR enforces its own fixed anonymous pull limit per source IP, and Harness Cloud runners run on GCP, so they receive no AWS-side preferential treatment and hit the same limit as any other anonymous caller. GAR is the only anonymous option that avoids this limit on Harness Cloud.

If you do not want to change the behavior for your entire account, follow the steps in Use credentials to pull Harness images for specific stages to modify the behavior for specific stages only.

Follow the steps in Create or edit a Docker connector, using the following configurations:

For Provider Type:
- To pull Harness images from GAR: Other (Docker V2 compliant).
- To pull Harness images from ECR: Other (Docker V2 compliant).
- To revert back to Docker Hub: Docker Hub.
For Docker Registry URL:
- To pull Harness images from GAR: https://us-docker.pkg.dev/gar-prod-setup/harness-public.
- To pull Harness images from ECR: https://public.ecr.aws/harness.
- To revert back to Docker Hub: https://registry.hub.docker.com.

Anonymous access to public Docker registries

Harness now supports anonymous access to all public Docker registries, including Amazon ECR and Artifactory Public. You can now pull images without requiring authentication. If you use Harness Cloud build infrastructure, go to Pull images anonymously from GAR or ECR to understand rate limiting behavior before choosing a registry.

Configure Harness to always use credentials to pull Harness images

If you do not 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 do not allow anonymous connections to public image repos.

If you do not want to change the behavior for your entire account, you can use credentials to pull Harness images for specific stages.

Follow the steps in Create or edit a Docker connector, using the following configurations:

For Provider Type:
- To pull Harness images from GAR: Other (Docker V2 compliant).
- To pull Harness images from ECR: Other (Docker V2 compliant).
- To revert back to Docker Hub: Docker Hub.
For Docker Registry URL:
- To pull Harness images from GAR: https://us-docker.pkg.dev/gar-prod-setup/harness-public.
- To pull Harness images from ECR: https://public.ecr.aws/harness.
- To revert back to Docker Hub: https://registry.hub.docker.com.
For Authentication, select Username and Password.
- Enter your Username.
- For Password, select or create a Harness secret to store the access token for your repository. The token needs Read, Write, and Delete permissions.

Use credentials to pull Harness images for specific stages

If you do not 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 cannot 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.

Follow the steps in Create or edit a Docker connector, using the following configurations:

For Provider Type:
- To pull Harness images from GAR: Other (Docker V2 compliant).
- To pull Harness images from ECR: Other (Docker V2 compliant).
- To revert back to Docker Hub: Docker Hub.
For Docker Registry URL:
- To pull Harness images from GAR: https://us-docker.pkg.dev/gar-prod-setup/harness-public.
- To pull Harness images from ECR: https://public.ecr.aws/harness.
- To revert back to Docker Hub: https://registry.hub.docker.com.
For Authentication, select Username and Password.
- Enter your Username.
- For Password, select or create a Harness secret to store the access token for your repository. The token needs Read, Write, and Delete permissions.

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 Harness images.

![Override Image Connector field in the Build stage Infrastructure settings](../../../.gitbook/assets/connect-to-harness-container-image-registry-using-docker-connector-49.png)

Pull Harness images from a private registry

Harness CI images are stored in a public container registry. If you do not 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

Download the images you need from the Harness project on GAR or the Harness ECR public gallery, perform any tests or validations necessary for your organization's security policies, and then store the images in your private registry.
Do not change the image names in your private registry. The image names must match the names specified by Harness.
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

Follow the steps in Create or edit a Docker connector, using the following configurations:

For Provider Type, select Other (Docker V2 compliant).
For Docker Registry URL, enter the path for your container registry.
For Authentication, select Username and Password.
- Enter your Username.
- For Password, select or create a Harness secret to store the access token for your repository. The token needs Read, Write, and Delete permissions.

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.

Authentication considerations for Amazon ECR private repositories

You can configure a Docker connector in Harness to authenticate and pull images from your private registry. You can either create your own Docker connector or use the built-in account-level Harness Docker connector (harnessImage). When configuring a Docker connector to access an Amazon ECR private repository, you must provide a username and password for authentication. According to AWS documentation, the authentication token obtained via the aws ecr get-login-password command is valid for 12 hours. Therefore, to maintain uninterrupted access, you need to update the connector with a new token every 12 hours. This requirement applies only to private ECR repositories. For public ECR repositories, you can configure the connector to use anonymous access, which does not require token-based authentication.

Connector selection hierarchy

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

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.
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.

End of life notice: app.harness Docker registry

Harness images are available on Docker Hub, the Harness project on GAR, and the Harness ECR public gallery. In a continuation of this effort, and to improve stability when pulling Harness-required images, Harness deprecated the Harness-hosted app.harness Docker registry effective 15 Feb 2024. The registry end point will be end of life on 15 May 2024.

The end of life could impact you if:

Your built-in Harness Docker connector (account.harnessImage) is configured to use the app.harness Docker registry. To avoid errors when the deprecation takes place, modify the target image registry by following the steps in Configure Harness to always use credentials to pull Harness images.
You pull Harness images from a private registry, and you are currently pulling the latest images from the app.harness Docker registry. To avoid errors post end of life, make sure you are pulling images from the Harness project on GAR or the Harness ECR public gallery.
You have other Docker connectors configured to the app.harness Docker registry. Edit these connectors to use https://registry.hub.docker.com instead.

Sample YAML

The following example shows the complete YAML for the connector created in this guide, that uses your credentials to pull Harness images from ECR.

YAML - Docker ECR connector

connector:
  name: your-docker-ecr-connector      # Display name for the connector in Harness
  identifier: yourdockerecrconnector   # Unique ID used in pipelines and API references; use "harnessImage" to override the built-in connector
  description: ""                      # Optional: brief description of this connector
  accountIdentifier: youraccountidentifier  # Your Harness account ID
  orgIdentifier: default               # Org where this connector is created; use "default" for the default org
  projectIdentifier: yourprojectidentifier  # Project where this connector is created
  type: DockerRegistry
  spec:
    dockerRegistryUrl: yourdockerregistryurl  # Registry URL: https://public.ecr.aws/harness (ECR), https://us-docker.pkg.dev/gar-prod-setup/harness-public (GAR), or your private registry URL
    providerType: Other                # Provider type: DockerHub, or Other (Docker V2 compliant) for GAR, ECR, and private registries
    auth:
      type: UsernamePassword           # Authentication method: UsernamePassword or Anonymous
      spec:
        username: username             # Username for the registry; use "AWS" for ECR or "_json_key_base64" for GCR with a JSON key
        passwordRef: password          # Reference to a Harness Encrypted Text secret containing the registry password or access token (note: ECR tokens expire every 12 hours)
    delegateSelectors:
      - your-delegate-selector         # Tag of the delegate that runs operations for this connector
    executeOnDelegate: true            # Set to false to connect through the Harness Platform instead of a delegate
    proxy: false                       # Set to true if the delegate connects to the registry through an HTTP proxy
    ignoreTestConnection: false        # Set to true to skip the connection test and save the connector anyway

Troubleshoot Harness images

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

Next steps

Docker Connector Settings Reference: review all available settings for a Docker connector.
Use delegate selectors: control which delegates can connect to a Docker connector.

PreviousDocker Registry connector settings reference

NextConnect to IBM cloud container registry

Last updated 13 days ago

Was this helpful?