Create an upstream proxy
Create an upstream proxy to cache artifacts from an external registry such as Docker Hub, Amazon ECR, or a private server on demand.
An upstream proxy is a special registry configuration that fetches artifacts from an external source on demand and caches them locally. When a client requests an artifact that is not already in the cache, Harness retrieves it from the configured upstream source, stores it, and serves future requests from the local copy.
Use an upstream proxy to:
Cache open-source dependencies so builds continue even if the upstream source is down or rate-limiting requests.
Route all external artifact traffic through a single controlled access point.
Apply Dependency Firewall policies to artifacts fetched from public registries.
Artifacts cached through an upstream proxy are automatically scanned at ingest time when the Harness Supply Chain Security module is enabled.
Before you begin
Your role must include Create/Edit permission on Artifact Registry. Go to RBAC and permissions for details.
If the upstream source requires authentication, store the credentials in Harness Secret Manager before you create the proxy. Harness Artifacts does not support external secret managers for upstream authentication.
Create an upstream proxy
In the left navigation, select Registries.
Select Create registry.
In the Create a new artifact registry drawer, select the Upstream Proxy toggle or choose the package type and enable the upstream proxy option.
Select the registry type that matches the upstream source format.
Enter an Upstream Proxy Key.
The key must start with a letter and can only contain lowercase letters, numbers, underscores (
_), hyphens (-), and periods (.).Configure the Source for the upstream:
Source optionWhen to useDocker Hub
Public Docker Hub registry
AWS ECR
Amazon Elastic Container Registry
Custom
Any other registry, including on-premises servers (for example, JFrog Artifactory)
When you select Custom, enter the Remote registry URL. The URL must start with
https://. Use the base URL of the repository, not a specific artifact path.Set the Authentication method:
Anonymous: for public sources that do not require credentials.
Username and Password: for private sources. Select the Harness secrets that store your credentials.
Select Create upstream proxy.
After creation, attach the proxy to one or more registries so clients can use it. Go to Add and prioritise upstream proxies.
Configure metadata cache TTL
After creating the proxy, you can configure how long the proxy caches package metadata fetched from the upstream source.
Open the upstream proxy, select Configuration, then find the Metadata configuration section.
Metadata Cache TTL
How long cached package index metadata stays valid before Harness checks the upstream again
0–604,800 seconds (7 days)
600 seconds (10 min)
Negative Cache TTL
How long Harness caches a not-found response before retrying the upstream
0–604,800 seconds (7 days)
600 seconds (10 min)
A value of 0 means the field is unset and the default applies.
Delete cached artifacts
Deleting a cached artifact removes it from the local cache only. It does not appear in the Deleted view. Pull the artifact again through the proxy to re-cache it from the upstream source.
Troubleshooting
Next steps
Add and prioritise upstream proxies to attach the proxy to a registry.
Dependency Firewall overview to apply security policies to cached artifacts.
Last updated
Was this helpful?