Docker Repository Configuration and Client Connection

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

rep_conn_SSL_port.png

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.

Run Behind a Reverse Proxy

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.

rep_conn_HTTP_port.png

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.

force_basic_auth.png

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.

 SSLNexusBasic.png 

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

SSLNexusAnon.png

  • Make sure the Docker Bearer Token Realm is listed as Active in Nexus administration Realms

realm.png

  • Make sure the Anonymous Access is enabled and granted Role based access to the docker repositories.

anon.png

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

realm.png

  • If anonymous access is needed make sure the Anonymous Access is enabled and granted Role based access to the docker repositories.

anon.png

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.

Have more questions? Submit a request

0 Comments

Article is closed for comments.