Proxy Repository for Docker

Proxy Repository for Docker

To reduce duplicate downloads and improve download speeds for your developers and CI servers, you should proxy any registry you use for Docker images.

Basic Steps to Proxy a Docker Registry

To proxy a Docker registry, you simply create a new docker (proxy) as documented in Repository Management.
Minimal configuration steps are as follows:

  1. Define a Name
  2. Define a URL of the remote registry you want to proxy for Remote__Storage
  3. Enable Docker V1 API support if required by the remote repository
  4. Select the correct Docker index
  5. Further configure Location of Docker__index if needed
  6. Select Blob store for Storage

Create a Proxy for Docker Hub

Docker Hub is the most common registry used by all image creators and consumers.

In order to configure a proxy for Docker Hub, you create a new docker (proxy) as documented in Repository Management and make the following configurations:

  1. Define a Name
  2. Define the URL for Remote Storage as "https://registry-1.docker.io"
  3. Enable Docker V1 API support
  4. For the Docker__index, select Use Docker Hub
  5. Select Blob store for storage

Create a Proxy for Amazon Elastic Container Registry (ECR)

Amazon Elastic Container Registry (ECR) is a managed container registry service from AWS. Nexus Repository can proxy ECR registries to cache container images and reduce data transfer costs.

Nexus Repository 3.95 and later supports both long-lived AWS IAM access keys and short-lived AWS Security Token Service (STS) credentials for authenticating to ECR.

Prerequisites

Choose an AWS Credential Type

Credential Type Access Key ID Required Credential Fields Expiration
Long lived IAM credentials Starts with AKIA Access key ID and secret access key Does not have an STS session expiration. Rotate the credentials according to your organization's security policy.
Short-lived STS credentials Starts with ASIA Access key ID, secret access key, and session token Expires when the underlying AWS STS session expires. You must update the repository with fresh credentials before or after expiration.

To create a new ECR proxy repository, take the following steps:

  1. Select Settings→ Repository→ Repositories.

  2. Select the Create repository button.

  3. From the list of Recipes, select docker (proxy).

  4. In the form that appears, complete the required fields.

    • Repository Name, for example docker-ecr-proxy
    • Enter the remote storage URL, for example, https://<account-id>.dkr.ecr.<region>.amazonaws.com. Depending on the registry endpoint, the URL might not include dkr.
    • Blob store for self hosted deployments

  5. Under HTTP section, select the Authentication check box and set Authentication type to Username.

  6. Enter the AWS credentials

    • Username: AWS ECR Access Key
    • Password: AWS ECR Secret Access Key

  7. Under AWS ECR Authentication, configure AWS Session Token

    • For short-lived STS credentials, enter the session token associated with the access key ID and secret access key.
    • For long-lived IAM credentials, leave AWS Session Token blank.

  8. Complete the additional fields for configurations you wish to add for creating your repository. Available configurations differ by repository format and type. See Configurable Repository Fields for more details.

  9. Select Create repository.

Nexus Repository validates the AWS credentials when you create or update the repository. When a client first requests an image, Nexus Repository uses the configured AWS credentials to request an ECR authorization token.

Note

Nexus Repository cannot renew an AWS STS session token. It can refresh the ECR authorization token only while the configured AWS credentials remain valid. After the STS credentials expire, a cached ECR authorization token may continue to work until Nexus Repository must refresh it. Subsequent image pulls fail until you update the repository with valid AWS credentials.

When you pull the images using AWS CLI through Nexus docker repository, Nexus Repository caches the 12-hour ECR token on the first pull. Nexus Repository reuses the cached token for every subsequent pull and refreshes the authorization token every six hours though the ECR Token Refresh task.

ECR Token Refresh Task

The ECR Token Refresh task is active by default and does not require manual intervention. The task refreshes the ECR authorization token. It does not renew or replace the AWS access key, secret access key, or STS session token configured on the repository. If you wish to edit the task, take the following steps:

  1. Select Settings→ System → Tasks → ECR Token Refresh.

  2. Select Settings.

  3. Edit only the fields you wish to change.

    • To send email notifications, enter your email address in the Notification email field.
    • To force refresh, select the Force refresh checkbox. It evicts the cached ECR token by ignoring the 6-hour expiry horizon. Select this checkbox only if you want to change your credentials immediately.
    • To schedule the task at your own pace, edit the Task frequency and CRON expression fields.

  4. Select Save.

  5. If you wish to run the task immediately, select Run.

Rotate Short-Lived AWS Credentials

Take the following steps to rotate short-lived credentials before their STS session expires whenever possible:

  1. Select Settings → Repository → Repositories.
  2. Select your Docker proxy repository that connects to ECR.
  3. Under HTTP Authentication type, update the username and password values if they were rotated.
  4. Under AWS ECR Authentication, enter the new AWS Session Token.
  5. Select Save.

Configuring a Correct Remote Storage and Docker Index URL Pair

It is important to configure a correct pair of Remote Storage URL and Docker Index URL. If there is a mismatch, search results potentially will not reflect the remote repository's content, and other problems can occur.

The proxy configuration for a Docker proxy repository includes a configuration URL to access the Docker Index. The index is used for requests related to searches, users, Docker tokens and other aspects.

The same provider typically co-hosts the registry and the index; however, they can use different URLs. For example, the index for Docker Hub is exposed at https://index.docker.io/. By selecting the default option of Use proxy registry (specified above), Nexus Repository will attempt to retrieve any index data from the same URL configured as the _Remote Storage_URL.

The option to Use Docker Hub fulfills any index-related requests by querying the Docker Hub index at https://index.docker.io/. This configuration is desired when the proxy repository is Docker Hub itself or any of its mirrors.

The option to use a Custom index allows you to specify the URL of the index for the remote repository.