Skip to main content

Docker Subdomain Connector

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

120521639.png

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 port connectors are needed, you must use either a reverse proxy or subdomain.

Note

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 yourDocker 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.

Note

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.

Create repository screen with Allow Subdomain Routing box checked

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.

  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; 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 section; ensure the new subdomain is different from your old one (e.g., new-docker.nexus.example).

  3. Configure a subdomain connector.

  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).