> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/harness-platform/use-harness-platform/connectors/artifact-repositories/add-a-docker-registry-connector/connect-to-harness-container-image-registry-using-docker-connector.md). # 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](/harness-platform/use-harness-platform/connectors/artifact-repositories/add-a-docker-registry-connector/docker-registry-connector-settings-reference.md), to pull the required Harness images used for backend processes, such as [Harness CI images](https://github.com/harness/harness-developer-hub/tree/main/docs/delivery/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/harness-ci.md), 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 * How to [pull images anonymously from GAR or ECR](#pull-images-anonymously-from-gar-or-ecr). * How to [configure Harness to always use credentials instead of anonymous access](#configure-harness-to-always-use-credentials-to-pull-harness-images). * How to [use credentials to pull Harness images for specific stages](#use-credentials-to-pull-harness-images-for-specific-stages). * How to [pull Harness images from a private registry](#pull-harness-images-from-a-private-registry). *** ## 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](/harness-platform/use-harness-platform/platform-access-control/permissions-reference.md) to create, edit, and view connectors at the account [scope](/harness-platform/use-harness-platform/platform-access-control.md#permissions-hierarchy-scopes). {% hint style="info" %} **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](#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](#pull-images-anonymously-from-gar-or-ecr) for details. {% endhint %} *** ## 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](#pull-images-anonymously-from-gar-or-ecr) | | Security policy disallows anonymous pulls entirely | Account-wide | [Always use credentials](#configure-harness-to-always-use-credentials-to-pull-harness-images) | | Only one build infrastructure/stage cannot pull anonymously (e.g., private cloud) | Single stage | [Use credentials for specific stages](#use-credentials-to-pull-harness-images-for-specific-stages) | | Need full control over image provenance, or air-gapped environment | Account-wide | [Pull from a private registry](#pull-harness-images-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. 1. Go to your Harness Account. 2. In **Account Settings**, under Account-level resources, select **Connectors**. 3. 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. 4. Click **Edit details**. ### Overview 5. Click **Continue** to go to the **Details** settings. ### Details 6. Select a **Provider Type**, and enter the **Docker Registry URL** (see the option-specific table below). 7. 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 8. 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 9. In **Delegates Setup**, use any delegate or enter [tags](/harness-platform/use-harness-platform/delegates/delegate/manage-delegates/select-delegates-with-selectors.md) for the specific delegates that you want to allow to connect to this connector. Click **Save and Continue**. ### Connection Test 10. 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. {% hint style="warning" %} **ECR does not avoid rate limiting on Harness Cloud** If you use [Harness Cloud build infrastructure](https://github.com/harness/harness-developer-hub/tree/main/docs/delivery/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/use-harness-cloud-build-infrastructure.md), 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. {% endhint %} 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](#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](#create-or-edit-a-docker-connector), using the following configurations: * For **Provider Type**: * To pull [Harness images from GAR](https://us-docker.pkg.dev/gar-prod-setup/harness-public/harness/delegate): **Other (Docker V2 compliant)**. * To pull [Harness images from ECR](https://gallery.ecr.aws/harness): **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/harness/delegate): `https://us-docker.pkg.dev/gar-prod-setup/harness-public`. * To pull [Harness images from ECR](https://gallery.ecr.aws/harness): `https://public.ecr.aws/harness`. * To revert back to Docker Hub: `https://registry.hub.docker.com`. {% hint style="info" %} **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](#pull-images-anonymously-from-gar-or-ecr) to understand rate limiting behavior before choosing a registry. {% endhint %} ## 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](#use-credentials-to-pull-harness-images-for-specific-stages). Follow the steps in [Create or edit a Docker connector](#create-or-edit-a-docker-connector), using the following configurations: * For **Provider Type**: * To pull [Harness images from GAR](https://us-docker.pkg.dev/gar-prod-setup/harness-public/harness/delegate): **Other (Docker V2 compliant)**. * To pull [Harness images from ECR](https://gallery.ecr.aws/harness): **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/harness/delegate): `https://us-docker.pkg.dev/gar-prod-setup/harness-public`. * To pull [Harness images from ECR](https://gallery.ecr.aws/harness): `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](https://github.com/harness/harness-developer-hub/tree/main/docs/delivery/continuous-integration/use-harness-ci/use-harness-ci/prep-ci-pipeline-components.md#stages) by creating a dedicated [Docker connector](/harness-platform/use-harness-platform/connectors/artifact-repositories/add-a-docker-registry-connector/docker-registry-connector-settings-reference.md) 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](#configure-harness-to-always-use-credentials-to-pull-harness-images). Follow the steps in [Create or edit a Docker connector](#create-or-edit-a-docker-connector), using the following configurations: * For **Provider Type**: * To pull [Harness images from GAR](https://us-docker.pkg.dev/gar-prod-setup/harness-public/harness/delegate): **Other (Docker V2 compliant)**. * To pull [Harness images from ECR](https://gallery.ecr.aws/harness): **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/harness/delegate): `https://us-docker.pkg.dev/gar-prod-setup/harness-public`. * To pull [Harness images from ECR](https://gallery.ecr.aws/harness): `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](https://github.com/harness/harness-developer-hub/tree/main/docs/delivery/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/ci-stage-settings.md#infrastructure), 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](https://github.com/harness/harness-developer-hub/tree/main/docs/security/application-security-testing/security-testing-orchestration/troubleshooting-and-resources/sto-use-cases/set-up-sto-pipelines/configure-pipeline-to-use-sto-images-from-private-registry.md). ### Download Harness images to your registry 1. Download the images you need from the [Harness project on GAR](https://us-docker.pkg.dev/gar-prod-setup/harness-public/harness/delegate) or the [Harness ECR public gallery](https://gallery.ecr.aws/harness), 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.

2. **Recommended**: [Specify the images to use in your pipelines](https://github.com/harness/harness-developer-hub/tree/main/docs/delivery/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/harness-ci.md#specify-the-harness-ci-images-used-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](#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](https://github.com/harness/harness-developer-hub/tree/main/docs/delivery/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/ci-stage-settings.md#infrastructure), 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. ![Override Image Connector field in the Build stage Infrastructure settings](https://173309742-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3F2TpHXhur2QtQnORSM9%2Fuploads%2Fgit-blob-b28e3ffe96c6ecf0f603169ea428cdc7078881a7%2Fconnect-to-harness-container-image-registry-using-docker-connector-49.png?alt=media) ### 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](https://docs.aws.amazon.com/AmazonECR/latest/userguide/registry_auth.html#registry-auth-token), 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: 1. Check for a connector specified at the stage level, such as when [pulling Harness images from a private registry](#pull-harness-images-from-a-private-registry) or [using credentials to pull Harness images for specific stages](#use-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](#configure-harness-to-always-use-credentials-to-pull-harness-images). ## End of life notice: app.harness Docker registry [Harness images](https://github.com/harness/harness-developer-hub/tree/main/docs/delivery/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/harness-ci.md) are available on Docker Hub, the [Harness project on GAR](https://us-docker.pkg.dev/gar-prod-setup/harness-public/harness/delegate), and the [Harness ECR public gallery](https://gallery.ecr.aws/harness). 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](#configure-harness-to-always-use-credentials-to-pull-harness-images). * You [pull Harness images from a private registry](#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](https://us-docker.pkg.dev/gar-prod-setup/harness-public/harness/delegate) or the [Harness ECR public gallery](https://gallery.ecr.aws/harness). * 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 ```yaml 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](https://github.com/harness/harness-developer-hub/tree/main/docs/delivery/continuous-integration/troubleshooting-and-resources/ci-articles-and-faqs/continuous-integration-faqs.md) for questions and issues related to Harness-required images, connectors, and pipeline initialization, such as: * [How do I get a list of tags available for an image in the Harness image registry?](https://github.com/harness/harness-developer-hub/tree/main/docs/delivery/continuous-integration/troubleshooting-and-resources/ci-articles-and-faqs/continuous-integration-faqs.md#how-do-i-get-a-list-of-tags-available-for-an-image-in-the-harness-image-registry) * [Build failed with "failed to pull image" or "ErrImagePull"](https://github.com/harness/harness-developer-hub/tree/main/docs/delivery/continuous-integration/troubleshooting-and-resources/ci-articles-and-faqs/continuous-integration-faqs.md#build-failed-with-failed-to-pull-image-or-errimagepull) * [What access does Harness use to pull the Harness internal images from the public image repo?](https://github.com/harness/harness-developer-hub/tree/main/docs/delivery/continuous-integration/troubleshooting-and-resources/ci-articles-and-faqs/continuous-integration-faqs.md#what-access-does-harness-use-to-pull-the-harness-internal-images-from-the-public-image-repo) * [Can I use my own private registry to store Harness CI images?](#pull-harness-images-from-a-private-registry) * [Docker Hub rate limiting](https://github.com/harness/harness-developer-hub/tree/main/docs/delivery/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/harness-ci.md#docker-hub-rate-limiting) *** ## Next steps * [Docker Connector Settings Reference](/harness-platform/use-harness-platform/connectors/artifact-repositories/add-a-docker-registry-connector/docker-registry-connector-settings-reference.md): review all available settings for a Docker connector. * [Use delegate selectors](/harness-platform/use-harness-platform/delegates/delegate/manage-delegates/select-delegates-with-selectors.md): control which delegates can connect to a Docker connector.