Docker Subdomain Connector

Only available in Nexus Repository Pro. Interested in a free trial?  Start here.

NEW IN 3.40.0

A subdomain is a domain that is part of another domain. You can provision a subdomain and then configure a subdomain connector in Nexus Repository Pro to improve  Docker port scalability. This topic covers intended use cases and implementation steps for setting up a Docker subdomain connector.

Use Cases

Using a subdomain for Docker repositories is an option to consider for the following use cases:

  • You want to access Docker repository content with a native client.
  • You don't want to use port connectors or you need to improve scalability.
  • You don't want to use a reverse proxy.
    • If more than 20 connectors are needed, you must use either a reverse proxy or subdomain.

Note that Docker client expects secure connectivity (See our SSL documentation).

Implementation 

  1. To use a subdomain connector, you must first provision the subdomain that you wish to use and identify a Docker repository that you want to access.
    1. Each of these domains must be pointing at your Nexus Repository instance.
    2. Only the first subdomain host will be used to identify repository:
      1. a.a.example and a.b.example will be considered equivalent
      2. a.a.example and b.a.example will be distinct
  2. In your Nexus Repository instance, navigate to your Docker repository configuration page.
  3. In the Repository Connectors section, enable Allow Subdomain Routing.
  4. The text box will automatically use the Name of the given repository as long as it meets the naming requirements for a subdomain; you may modify this name as desired. Make sure the text field value matches the subdomain you have provisioned in step #1. Put only the subdomain value; do not use FQDN in this field.
The subdomain field must be a unique name that is a minimum of 1 and maximum of 63 characters (letters, numbers, and dashes) and must start with a letter and end with either a letter or number.

Example Usage 

In this example, you would complete the following steps:

1. Provision the subdomain you wish to use in your DNS by creating a new A or AAAA record pointing at the IP of your Nexus Repository (e.g., "docker.nexus.example")

2. In Nexus Repository, configure a Docker repository and enable subdomain routing; match the subdomain name to the one you provisioned in the previous step (e.g., "docker")

You can now access your Docker repository content via the subdomain you have just configured using regular commands such as the example below:

$ docker login docker.nexus.example
Username: <your username>
Password: <your password>
Login Succeeded
$ docker pull docker.nexus.example/alpine
Using default tag: latest
latest: Pulling from alpine
a0d0a0d46f8b: Pull complete
Digest: sha256:69704ef328d05a9f806b6b8502915e6a0a4faa4d72018dc42343f511490daf8a
Status: Downloaded newer image for docker.nexus.example/alpine:latest
docker.nexus.example/alpine:latest
$ docker push docker.nexus.example/alpine
Using default tag: latest
The push refers to repository [docker.nexus.example/alpine]
e2eb06d8af82: Layer already exists
latest: digest: sha256:69704ef328d05a9f806b6b8502915e6a0a4faa4d72018dc42343f511490daf8a size: 528

Migrating from Reverse Proxy to Subdomain Connector

It is not required that you deconfigure port connectors or reverse proxy configurations in order to use subdomain connectors. However, if desired, you can use the information below to migrate from using port connectors or a reverse proxy to using a subdomain connector.

Migrating from Port Connector to Subdomain Connector

  1. Begin by configuring a subdomain connector as documented above.
  2. Update any tools (e.g., Docker CLI, CI/CD pipelines, etc.) to point at the new subdomain (e.g., docker.nexus.example).
  3. Optionally, disable port connectors in your repository configuration by unchecking the box for enabling an HTTP or HTTPS connector in the repository configuration screen.
    1. If desired, you can keep port connectors enabled to allow users to gracefully migrate over time.

Migrating from Reverse Proxy to Subdomain Connector Using the Same Subdomain

  1. Note the subdomain you are using in your reverse proxy to route traffic to your Docker repository (e.g., docker.nexus.example).
  2. Configure a subdomain connector as documented above; ensure you give the subdomain connector the same name as the subdomain you were using in your reverse proxy.
  3. In your reverse proxy configuration, remove traffic routing for that subdomain. Instead, point it at your regular Nexus Repository endpoint (e.g., nexus.example:8081).
  4. You should not need to update tools (e.g., Docker CLI, CI/CD pipelines, etc.) as you should still be using the same subdomain that the reverse proxy once used (e.g., docker.nexus.example).

Migrating from Reverse Proxy to Subdomain Connector Using a Different Subdomain

  1. Note the subdomain you are using in your reverse proxy to route traffic to your Docker repository (e.g., docker.nexus.example).
  2. Provision a new subdomain as documented in the first step of our subdomain connector implementation above; ensure the new subdomain is different from your old one (e.g., new-docker.nexus.example).
  3. Configure a subdomain connector as documented above.
  4. Update any tools (e.g., Docker CLI, CI/CD pipelines, etc.) to point at the new subdomain (e.g., new-docker.nexus.example).
  5. Optionally, in your reverse proxy configuration, remove traffic routing for the original subdomain (docker.nexus.example in this example).