Docker
Create a Docker registry, generate an identity token, then log in, push, and pull container images with the Docker CLI through Harness Artifacts.
Use a Docker registry to host private container images. The registry works with the Docker CLI.
What you will learn from this topic
By the end of this quickstart guide, you will be able to:
Create a registry in Harness Artifacts.
Publish an image to the registry.
Pull the image from the registry, and confirm that it works.
Before you begin
Install the Docker CLI (
docker) on your local machine.Make sure you have access to a Harness account with permission to create registries and connectors.
Create a Docker Registry
To create a Docker Registry, perform the following steps:
In Artifact Registry, select Registries.
Click + Create Registry.
Specify the Registry name.
Optionally, add a Description.
Choose visibility between Public and Private. The default is Private.
Select Docker as the Registry type.
Click Save.
Select Create to finalize.
Configure an upstream proxy (optional)
An upstream proxy allows your registry to fetch Docker images from external container registries when they are not available locally.
Create upstream proxy
To create an upstream proxy, perform the following steps:
In Artifact Registry, select Registries.
Click the drop-down next to + Create Registry and select Upstream Proxy.
Specify the Registry name.
Optionally, add a Description.
Choose visibility between Public and Private. The default is Private.
Select Docker as the Registry type.
Select the Source:
Docker Hub: No remote registry URL required.
AWS ECR: Specify the Remote registry URL.
Custom: Specify the Remote registry URL.
Select the Authentication method:
Docker Hub:
Username and password: Specify the username and password. Use an existing secret, or create a new secret by specifying the Name and entering the Secret text.
Anonymous: No credentials required. This works for public Docker Hub images.
AWS ECR:
Access key: Specify the access key as plain text or as an encrypted secret, then specify the secret key by creating a new secret or selecting an existing one.
Anonymous: No credentials required. This works for public ECR repositories.
Custom:
Username and password: Specify the username and password. Use an existing secret, or create a new secret by specifying the Name and entering the Secret text.
Anonymous: No credentials required. This works for registries that need no authentication.
Select Create to finalize.
Configure the upstream proxy in your registry
To configure the upstream proxy in your registry, perform the following steps:
In Artifact Registry, select an existing Docker artifact.
Navigate to the Configuration tab.
Select Edit in the Upstream proxy section.
Click + Add upstream proxy.
Select the required proxy from the list.
Select Apply.
Click Update to finalize.
Docker client setup
In your Harness Docker Artifact, select Set Up Client. The dialog gives you an identity token, then setup instructions for logging in, publishing, and pulling images with the Docker CLI.
Generate an identity token
An identity token serves as the password for authenticating with the registry.
In your Docker Artifact, select Set Up Client.
Select Generate Token.
Select an Expiration for the token:
30 Days
90 Days
180 Days
Custom
Copy the token. You use it in the following steps in place of
<IDENTITY_TOKEN>.
Configure the client
Replace the values in angle brackets with your own values.
1. Configure
Run the following command in your terminal to authenticate the Docker CLI with the registry:
At the prompts, enter the following:
Username: your Harness account email address.
Password:
<IDENTITY_TOKEN>.
2. Publish an image
Tag the image to match the registry path, then push it:
3. Use the image
Make sure you are authenticated with the registry (see step 1), then pull the image by tag or by digest:
Setup verification
Confirm that your registry serves the image you published. To verify your setup, perform the following steps:
On a host with no locally cached layers for the image you pushed, pull the image using the client command from the steps above.
Confirm that the client pulled the image from your Harness registry address, which is shown in Set Up Client.
In Harness, open your registry and confirm that the image and tag appear in the artifact list.
If a step fails, go to Troubleshooting to resolve common authentication and resolution issues before you retry.
Pipeline automation (optional)
Publishing from a pipeline gives you a repeatable release process. Run the publish step when you create a version tag, so each release maps to one image tag in the registry.
The following Run step shows the shape of a publish step. Replace <ACCOUNT_ID>, <REGISTRY_NAME>, and <IMAGE_NAME> with the values from the steps above. Store the identity token as a Harness secret, and do not write it into the pipeline YAML.
Troubleshooting
Next steps
To add a pipeline that publishes a new version for every release tag, go to Harness CI.
To control who can publish and consume packages in your registry, go to RBAC and permissions.
To set retention and lifecycle rules for old versions, go to Lifecycle Management overview.
Last updated
Was this helpful?