Merge pull request #424 from jnidzwetzki/documentation-private-registries
Added section about private registries to documentationpull/436/head
Simon Aronsson
5 years ago
committed by
GitHub
commit
42343e70d1
@ -1,66 +0,0 @@
|
|||||||
Some private docker registries (the most prominent probably being AWS ECR) use non-standard ways of authentication.
|
|
||||||
To be able to use this together with watchtower, we need to use a credential helper.
|
|
||||||
|
|
||||||
To keep the image size small we've decided to not include any helpers in the watchtower image, instead we'll put the
|
|
||||||
helper in a separate container and mount it using volumes.
|
|
||||||
|
|
||||||
### Example
|
|
||||||
Example implementation for use with [amazon-ecr-credential-helper](https://github.com/awslabs/amazon-ecr-credential-helper):
|
|
||||||
|
|
||||||
```Dockerfile
|
|
||||||
FROM golang:latest
|
|
||||||
|
|
||||||
ENV CGO_ENABLED 0
|
|
||||||
ENV REPO github.com/awslabs/amazon-ecr-credential-helper/ecr-login/cli/docker-credential-ecr-login
|
|
||||||
|
|
||||||
RUN go get -u $REPO
|
|
||||||
|
|
||||||
RUN rm /go/bin/docker-credential-ecr-login
|
|
||||||
|
|
||||||
RUN go build \
|
|
||||||
-o /go/bin/docker-credential-ecr-login \
|
|
||||||
/go/src/$REPO
|
|
||||||
|
|
||||||
WORKDIR /go/bin/
|
|
||||||
```
|
|
||||||
|
|
||||||
and the docker-compose definition:
|
|
||||||
```yaml
|
|
||||||
version: "3"
|
|
||||||
|
|
||||||
services:
|
|
||||||
watchtower:
|
|
||||||
image: index.docker.io/containrrr/watchtower:latest
|
|
||||||
volumes:
|
|
||||||
- /var/run/docker.sock:/var/run/docker.sock
|
|
||||||
- <PATH_TO_HOME_DIR>/.docker/config.json:/config.json
|
|
||||||
- helper:/go/bin
|
|
||||||
environment:
|
|
||||||
- HOME=/
|
|
||||||
- PATH=$PATH:/go/bin
|
|
||||||
- AWS_REGION=<AWS_REGION>
|
|
||||||
- AWS_ACCESS_KEY_ID=<AWS_ACCESS_KEY>
|
|
||||||
- AWS_SECRET_ACCESS_KEY=<AWS_SECRET_ACCESS_KEY>
|
|
||||||
volumes:
|
|
||||||
helper: {}
|
|
||||||
```
|
|
||||||
|
|
||||||
and for `<PATH_TO_HOME_DIR>/.docker/config.json`:
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"HttpHeaders" : {
|
|
||||||
"User-Agent" : "Docker-Client/19.03.1 (XXXXXX)"
|
|
||||||
},
|
|
||||||
"credsStore" : "osxkeychain",
|
|
||||||
"auths" : {
|
|
||||||
"xyzxyzxyz.dkr.ecr.eu-north-1.amazonaws.com" : {},
|
|
||||||
"https://index.docker.io/v1/": {}
|
|
||||||
},
|
|
||||||
"credHelpers": {
|
|
||||||
"xyzxyzxyz.dkr.ecr.eu-north-1.amazonaws.com" : "ecr-login",
|
|
||||||
"index.docker.io": "osxkeychain"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
*Note:* `osxkeychain` can be changed to your prefered credentials helper.
|
|
||||||
@ -0,0 +1,118 @@
|
|||||||
|
Watchtower supports private Docker image registries. In many cases, accessing a private registry requires a valid username and password (i.e., _credentials_). In order to operate in such an environment, watchtower needs to know the credentials to access the registry.
|
||||||
|
|
||||||
|
The credentials can be provided to watchtower in a configuration file called `config.json`. There are two ways to generate this configuration file:
|
||||||
|
|
||||||
|
* The configuration file can be created manually.
|
||||||
|
* Call `docker login <REGISTRY_NAME>` and share the resulting configuration file.
|
||||||
|
|
||||||
|
### Create the configuration file manually
|
||||||
|
Create a new configuration file with the following syntax and a base64 encoded username and password `auth` string:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"auths": {
|
||||||
|
"<REGISTRY_NAME>": {
|
||||||
|
"auth": "XXXXXXX"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
`<REGISTRY_NAME>` needs to be replaced by the name of your private registry (e.g., `my-private-registry.example.org`)
|
||||||
|
|
||||||
|
The required `auth` string can be generated as follows:
|
||||||
|
```bash
|
||||||
|
echo -n 'username:password' | base64
|
||||||
|
```
|
||||||
|
|
||||||
|
When the watchtower Docker container is started, the created configuration file (`<PATH>/config.json` in this example) needs to be passed to the container:
|
||||||
|
```bash
|
||||||
|
docker run [...] -v <PATH>/config.json:/config.json containrrr/watchtower
|
||||||
|
```
|
||||||
|
|
||||||
|
### Share the Docker configuration file
|
||||||
|
To pull an image from a private registry, `docker login` needs to be called first, to get access to the registry. The provided credentials are stored in a configuration file called `<PATH_TO_HOME_DIR>/.docker/config.json`. This configuration file can be directly used by watchtower. In this case, the creation of an additional configuration file is not necessary.
|
||||||
|
|
||||||
|
When the Docker container is started, pass the configuration file to watchtower:
|
||||||
|
```bash
|
||||||
|
docker run [...] -v <PATH_TO_HOME_DIR>/.docker/config.json:/config.json containrrr/watchtower
|
||||||
|
```
|
||||||
|
|
||||||
|
When creating the watchtower container via docker-compose, use the following lines:
|
||||||
|
```yaml
|
||||||
|
version: "3"
|
||||||
|
[...]
|
||||||
|
watchtower:
|
||||||
|
image: index.docker.io/containrrr/watchtower:latest
|
||||||
|
volumes:
|
||||||
|
- /var/run/docker.sock:/var/run/docker.sock
|
||||||
|
- <PATH_TO_HOME_DIR>/.docker/config.json:/config.json
|
||||||
|
[...]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Credential helpers
|
||||||
|
Some private Docker registries (the most prominent probably being AWS ECR) use non-standard ways of authentication.
|
||||||
|
To be able to use this together with watchtower, we need to use a credential helper.
|
||||||
|
|
||||||
|
To keep the image size small we've decided to not include any helpers in the watchtower image, instead we'll put the
|
||||||
|
helper in a separate container and mount it using volumes.
|
||||||
|
|
||||||
|
### Example
|
||||||
|
Example implementation for use with [amazon-ecr-credential-helper](https://github.com/awslabs/amazon-ecr-credential-helper):
|
||||||
|
|
||||||
|
```Dockerfile
|
||||||
|
FROM golang:latest
|
||||||
|
|
||||||
|
ENV CGO_ENABLED 0
|
||||||
|
ENV REPO github.com/awslabs/amazon-ecr-credential-helper/ecr-login/cli/docker-credential-ecr-login
|
||||||
|
|
||||||
|
RUN go get -u $REPO
|
||||||
|
|
||||||
|
RUN rm /go/bin/docker-credential-ecr-login
|
||||||
|
|
||||||
|
RUN go build \
|
||||||
|
-o /go/bin/docker-credential-ecr-login \
|
||||||
|
/go/src/$REPO
|
||||||
|
|
||||||
|
WORKDIR /go/bin/
|
||||||
|
```
|
||||||
|
|
||||||
|
and the docker-compose definition:
|
||||||
|
```yaml
|
||||||
|
version: "3"
|
||||||
|
|
||||||
|
services:
|
||||||
|
watchtower:
|
||||||
|
image: index.docker.io/containrrr/watchtower:latest
|
||||||
|
volumes:
|
||||||
|
- /var/run/docker.sock:/var/run/docker.sock
|
||||||
|
- <PATH_TO_HOME_DIR>/.docker/config.json:/config.json
|
||||||
|
- helper:/go/bin
|
||||||
|
environment:
|
||||||
|
- HOME=/
|
||||||
|
- PATH=$PATH:/go/bin
|
||||||
|
- AWS_REGION=<AWS_REGION>
|
||||||
|
- AWS_ACCESS_KEY_ID=<AWS_ACCESS_KEY>
|
||||||
|
- AWS_SECRET_ACCESS_KEY=<AWS_SECRET_ACCESS_KEY>
|
||||||
|
volumes:
|
||||||
|
helper: {}
|
||||||
|
```
|
||||||
|
|
||||||
|
and for `<PATH_TO_HOME_DIR>/.docker/config.json`:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"HttpHeaders" : {
|
||||||
|
"User-Agent" : "Docker-Client/19.03.1 (XXXXXX)"
|
||||||
|
},
|
||||||
|
"credsStore" : "osxkeychain",
|
||||||
|
"auths" : {
|
||||||
|
"xyzxyzxyz.dkr.ecr.eu-north-1.amazonaws.com" : {},
|
||||||
|
"https://index.docker.io/v1/": {}
|
||||||
|
},
|
||||||
|
"credHelpers": {
|
||||||
|
"xyzxyzxyz.dkr.ecr.eu-north-1.amazonaws.com" : "ecr-login",
|
||||||
|
"index.docker.io": "osxkeychain"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
*Note:* `osxkeychain` can be changed to your prefered credentials helper.
|
||||||
Loading…
Reference in New Issue