From dba55b17d09d4a15aa9d26884b22b230d49fce64 Mon Sep 17 00:00:00 2001 From: Matt Brown Date: Mon, 5 Jun 2017 12:57:10 -0400 Subject: [PATCH] document RegistryAuthSupplier in the user manual forgot to do this in #759 and #762 --- CHANGELOG.md | 2 +- README.md | 10 ---------- docs/user_manual.md | 30 ++++++++++++++++++++++++++++++ 3 files changed, 31 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f1f20d3d6..b2bb2d726 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## 8.7.0 (not yet released) +## 8.7.0 (released June 5, 2017) ### Expanded RegistryAuthSupplier support Add RegistryAuthSuppliers for: diff --git a/README.md b/README.md index c2a69edb5..ef4b73a90 100644 --- a/README.md +++ b/README.md @@ -47,15 +47,6 @@ final DockerClient docker = DefaultDockerClient.fromEnv().build(); // Pull an image docker.pull("busybox"); -// Pull an image from a private repository -// Server address defaults to "https://index.docker.io/v1/" -RegistryAuth registryAuth = RegistryAuth.builder().email("foo@bar.com").username("foobar") - .password("secret-password").serverAddress("https://myprivateregistry.com/v1/").build(); -docker.pull("foobar/busybox-private:latest", registryAuth); - -// You can also set the RegistryAuth for the DockerClient instead of passing everytime you call pull() -DockerClient docker = DefaultDockerClient.fromEnv().registryAuth(registryAuth).build(); - // Bind container ports to host ports final String[] ports = {"80", "22"}; final Map> portBindings = new HashMap<>(); @@ -111,7 +102,6 @@ docker.close(); If you're looking for how to use docker-client, see the [User Manual][2]. If you're looking for how to build and develop it, keep reading. - ## Prerequisites docker-client should be buildable on any platform with Docker 1.6+, JDK7+, and a recent version of diff --git a/docs/user_manual.md b/docs/user_manual.md index 06cb46eb7..c839d5c13 100644 --- a/docs/user_manual.md +++ b/docs/user_manual.md @@ -6,6 +6,7 @@ This user manual is made to correspond to Docker's [API docs][1] (e.g. [API 1.18 * [Unix socket support](#unix-socket-support) * [HTTPS support](#https-support) * [Connection pooling](#connection-pooling) +* [Authentication to private registries](#authentication-to-private-registries) * [Containers](#containers) * [List containers](#list-containers) * [Create a container](#create-a-container) @@ -114,6 +115,35 @@ Note that the connect timeout is also applied to acquiring a connection from the is exhausted and it takes too long to acquire a new connection for a request, we throw a `DockerTimeoutException` instead of just waiting forever on a connection becoming available. +## Authentication to private registries + +Authentication info when building, pushing, or pulling images, or when using +Swarm, is provided by a `RegistryAuthSupplier` class. + +Docker-client is packaged with a few implementations of this interface + +- `auth.ConfigFileRegistryAuthSupplier`, which reads authentication info from + the the config files used by docker-cli (`~/.dockercfg` or + `~/.docker/config.json`) +- `auth.NoOpRegistryAuthSupplier` which uses a fixed instance of the + `RegistryAuth` and `RegistryConfigs` POJOs +- `auth.gcr.ContainerRegistryAuthSupplier`, which programmatically fetches + access tokens for use with Google Container Registry based on given Gogole + Cloud account credentials +- `auth.MultiRegistryAuthSupplier`, which can be used to combine multiple other + implementations + +Users are encouraged to implement the `RegistryAuthSupplier` interface +themselves to support custom authentication logic, and we would be happy to +review and accept pull requests to add support in the library for additional +schemes. + +Since version 8.7.0, docker-client will automatically enable the +`ConfigFileRegistryAuthSupplier` class in `DefaultDockerClient` as long as none +of the other authentication-related methods in the +`DefaultDockerClient.Builder` class (`dockerAuth(boolean)`, +`registryAuth(RegistryAuth)`, or `registryAuthSupplier(RegistryAuthSupplier)`) +are used. ## Containers