<TABLE OF CONTENTS>
This article describes the process of configuring Docker repository connectors to allow a Docker client to connect to a Nexus 3 Docker repository.
What is a Repository Connector?
When you make a request using the Docker client, you provide a hostname and port followed by the Docker image. Docker does not support the use of a context to specify the path to the repository.
Does not work:
docker pull centos7:8081/repository/docker-group/postgres:9.4
Does work:
docker pull centos7:18080/postgres:9.4
Since we cannot include the repository name in the Docker client request, we use a Repository Connector to assign a port to the Docker repository which can be used in Docker client commands. The Repository Connector is found in the settings for each docker repository.
As the Docker client requires SSL, we must provide an SSL connection either to Nexus directly or through a reverse proxy. The repository connector supports both HTTPS direct connections and HTTP connections forwarded from a reverse proxy.
The repository connector also provides the option to configure anonymous authentication using the Docker Bearer Token Realm.
In this article we will describe the following Repository Connector configuration options:
Some example configurations with screenshots are also provided.
Terminating SSL at Nexus or a Reverse Proxy Server
The Docker client requires an SSL connection. This can be provided in one of two ways:
1. Nexus Configured to serve SSL directly
If Nexus is configured to serve SSL directly, the Docker Repository Connector uses an HTTPS port. Docker client commands use the Nexus hostname and the HTTPS port in the repository connector to access the repository.
Prerequisites:
i) Follow the detailed steps in the following articles to configure Nexus for SSL:
Configuring to Serve Content via HTTPS
Using Self-Signed Certificates with Nexus Repository Manager and Docker Daemon
ii) Verify that you are able to connect to Nexus using an SSL connection before moving on to configure the Docker repository connector.
iii) Configure the Docker client to trust the Nexus certificate. The Docker documentation describes how to do this.
Docker Repository Connector steps:
i) In Nexus administration, configure the Docker Repository Connector to use an HTTPS port. The screenshot below uses 18080 as an example.
ii) Use the HTTPS port the repository connector is using in docker requests.
docker login <nexus hostname>:<HTTPS port>
Examples:
SSL Terminated at Nexus and Basic Authentication
SSL Terminated at Nexus and Anonymous Authentication
2. SSL Terminated at a Reverse Proxy
If SSL is terminated at a reverse proxy, the Docker Repository Connector uses an HTTP port. Docker client commands use the reverse proxy server hostname and the reverse proxy HTTPS port to access the repository.
Prerequisites:
i) Follow the steps in the documentation to configure Nexus with SSL terminated at a reverse proxy. The reverse proxy should accept requests on an SSL port and forward to the HTTP port used by the Docker repository connector.
ii) Configure the Docker client to trust the reverse proxy certificate using the steps in the Docker documentation.
Docker Repository Connector steps:
i) In Nexus administration, configure the Docker Repository Connector to use an HTTP port.
ii) In Docker client requests, use the HTTPS port the reverse proxy is configured to forward.
docker login <proxy hostname>:<proxy HTTPS port>
Example:
SSL Terminated at Reverse Proxy and Anonymous Authentication
Basic Authentication or Anonymous
By default, the Repository Connector is configured to require a username and password for Docker client requests. You can choose to enable Anonymous access.
1. Basic Authentication
Checking the 'Force basic authentication' checkbox requires a username and password from a Docker client. This is the default behavior and requires no configuration.
2. Anonymous
Enabling anonymous authentication allows the Docker client to connect without specifying credentials.
i) On the Docker Repository Connector, uncheck the 'Force basic authentication' checkbox.
ii) In Nexus Administration, select Security > Realms. Make sure the Docker Bearer Token Realm is listed as Active. More information on Realms is provided in the documentation.
iii) In Nexus Administration, select Security >Anonymous. Make sure Anonymous Access is enabled.
iv) Grant the Anonymous user access to the docker repositories. By default, the Anonymous user is granted the nx-anonymous role which includes privileges to browse, read and search all repositories. To grant additional access to the docker repositories, you can create a new role with additional privileges and assign the role to the Anonymous user. Steps for creating Roles and adding Privileges (including screenshots) are provided in the Security documentation.
Note: Do not change the default realm of the Anonymous user. The Anonymous user is in the Local Authorizing Realm. That does not need to be changed.
Example:
SSL Terminated at Nexus and Anonymous Authentication
SSL Terminated at Reverse Proxy and Anonymous Authentication
Example Configurations with Screenshots
1. SSL Terminated at Nexus and Basic Authentication
Prerequisites:
- Nexus configured to serve SSL
- Docker client configured to trust the Nexus certificate
Repository Connector steps:
- Configure the Repository Connector to use an HTTPS port for SSL served by Nexus. The example below uses port 18080.
- Make sure Force basic authentication is checked to require credentials.
Docker Client:
In this example port 18080 is being used with hostname centos7. Following the Docker documentation, the certificate file was placed in a directory named with the host and port:
/etc/docker/certs.d/centos7:18080/centos7.crt
The following commands can be used:
docker login centos7:18080
docker pull centos7:18080/postgres:9.4
The docker client configuration looks similar to this:
[root@centos7 .docker]# cat config.json
{
"auths": {
"centos7:18080": {
"auth": "YWRtaW46YWRtaW4xMjM="
}
},
"HttpHeaders": {
"User-Agent": "Docker-Client/17.09.0-ce (linux)"
}
}
2. SSL Terminated at Nexus and Anonymous Authentication
Prerequisites:
- Nexus configured to serve SSL
- Docker client configured to trust the Nexus certificate
Repository Connector:
- Configure the Repository Connector to use an HTTPS port. The example below uses port 18080.
- Make sure Force basic authentication is unchecked
- Make sure the Docker Bearer Token Realm is listed as Active in Nexus administration Realms
- Make sure the Anonymous Access is enabled and granted Role based access to the docker repositories.
Docker Client:
In this example port 18080 is being used with hostname centos7. Following the Docker documentation, the certificate file was placed in a directory named with the host and port:
/etc/docker/certs.d/centos7:18080/centos7.crt
Execute a docker logout command to ensure that any credentials which may have been used previously are removed from the client configuration. Docker client requests do not need to pass credentials.
docker logout centos7:18080
docker pull centos7:18080/postgres:9.4
The docker client configuration should not contain a host:port entry for the Nexus Docker repository if Anonymous is being used.
3. SSL Terminated at Reverse Proxy and Anonymous Authentication
Prerequisites:
- Configure reverse proxy to accept SSL requests and forward to the Nexus Docker repository
- Docker client configured to trust the reverse proxy certificate
For this example, we are using an Apache reverse proxy to accept requests on SSL port 18095 and forward to HTTP port 18090.
Example Apache HTTPd Config:
ProxyRequests Off ProxyPreserveHost On Listen 18095 # Docker <VirtualHost *:18095> ServerName centos7 ServerAdmin admin@example.com SSLEngine on SSLCertificateFile "/opt/Nexus/nexus/etc/ssl/centos7.cert" SSLCertificateKeyFile "/opt/Nexus/nexus/etc/ssl/centos7.key" ProxyPass / http://localhost:8081/repository/docker-group ProxyPassReverse / http://localhost:8081/repository/docker-group RequestHeader set X-Forwarded-Proto "https" </VirtualHost>
Repository Connector:
- Configure the Repository Connector to use an HTTP port. The example below uses port 18090, which matches the ProxyPass settings in the reverse proxy configuration.
- If anonymous access is needed be sure to uncheck “Force basic authentication” in the docker repository’s configurtion
- Make sure the Docker Bearer Token Realm is listed as Active in Nexus administration Realms
- If anonymous access is needed make sure the Anonymous Access is enabled and granted Role based access to the docker repositories.
Docker Client:
In this example we are connecting to SSL port 18095 on the reverse proxy. In this case the reverse proxy happens to be colocated with the Nexus server, so the proxy server hostname is the same as the Nexus hostname. Following the Docker documentation, the certificate file was placed in a directory named with the proxy server hostname and proxy server SSL port:
/etc/docker/certs.d/centos7:18095/centos7.crt
Execute a docker logout command to ensure that any credentials which may have been used previously are removed from the client configuration. Docker client requests do not need to pass credentials.
docker logout centos7:18095
docker pull centos7:18095/postgres:9.4
The docker client configuration should not contain a host:port entry for the Nexus Docker repository if Anonymous is being used.