Merge pull request #1538 from infosiftr/docker-revamp
Revamp "docker" image docs, especially for TLS
This commit is contained in:
yosifkit
GitHub
commit
56cea55297
|
|
@ -16,119 +16,163 @@ If you are still convinced that you need Docker-in-Docker and not just access to
|
|||
|
||||
[](https://asciinema.org/a/24707)
|
||||
|
||||
## TLS
|
||||
|
||||
Starting in 18.09+, the `dind` variants of this image will automatically generate TLS certificates in the directory specified by the `DOCKER_TLS_CERTDIR` environment variable.
|
||||
|
||||
**Warning:** in 18.09, this behavior is disabled by default (for compatibility). If you use `--network=host`, shared network namespaces (as in Kubernetes pods), or otherwise have network access to the container (including containers started within the `dind` instance via their gateway interface), this is a potential security issue (which can lead to access to the host system, for example). It is recommended to enable TLS by setting the variable to an appropriate value (`-e DOCKER_TLS_CERTDIR=/certs` or similar). In 19.03+, this behavior is enabled by default.
|
||||
|
||||
When enabled, the Docker daemon will be started with `--host=tcp://0.0.0.0:2376 --tlsverify ...` (and when disabled, the Docker daemon will be started with `--host=tcp://0.0.0.0:2375`).
|
||||
|
||||
Inside the directory specified by `DOCKER_TLS_CERTDIR`, the entrypoint scripts will create/use three directories:
|
||||
|
||||
- `ca`: the certificate authority files (`cert.pem`, `key.pem`)
|
||||
- `server`: the `dockerd` (daemon) certificate files (`cert.pem`, `ca.pem`, `key.pem`)
|
||||
- `client`: the `docker` (client) certificate files (`cert.pem`, `ca.pem`, `key.pem`; suitable for `DOCKER_CERT_PATH`)
|
||||
|
||||
In order to make use of this functionality from a "client" container, at least the `client` subdirectory of the `$DOCKER_TLS_CERTDIR` directory needs to be shared (as illustrated in the following examples).
|
||||
|
||||
To disable this image behavior, simply override the container command or entrypoint to run `dockerd` directly (`... docker:dind dockerd ...` or `... --entrypoint dockerd docker:dind ...`).
|
||||
|
||||
## Start a daemon instance
|
||||
|
||||
```console
|
||||
$ docker run --privileged --name some-docker -d %%IMAGE%%:dind
|
||||
$ docker run --privileged --name some-docker -d \
|
||||
--network some-network --network-alias docker \
|
||||
-e DOCKER_TLS_CERTDIR=/certs \
|
||||
-v some-docker-certs-ca:/certs/ca \
|
||||
-v some-docker-certs-client:/certs/client \
|
||||
%%IMAGE%%:dind
|
||||
```
|
||||
|
||||
**Note:** `--privileged` is required for Docker-in-Docker to function properly, but it should be used with care as it provides full access to the host environment, as explained [in the relevant section of the Docker documentation](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities).
|
||||
|
||||
**Warning:** by default, the `dind` variants of this image add `--host=tcp://0.0.0.0:2375` (on top of the explicit default of `--host=unix:///var/run/docker.sock`) in order to allow other containers to access `dockerd` (as the following examples illustrate). If you use `--network=host`, shared network namespaces (as in Kubernetes pods), or otherwise have network access to the container (including containers started within the `dind` instance via their gateway interface), this is a potential security issue (which can lead to access to the host system, for example). To disable this image behavior, simply override the container command or entrypoint to run `dockerd` directly (`... docker:dind dockerd ...` or `... --entrypoint dockerd docker:dind ...`). It is recommended to implement TLS (`... docker:dind dockerd --host tcp://0.0.0.0:2376 --tlsverify ...`) if network access to the `dind` instance is required.
|
||||
|
||||
## Connect to it from a second container
|
||||
|
||||
```console
|
||||
$ docker run --rm --link some-docker:docker %%IMAGE%%:edge version
|
||||
Client:
|
||||
Version: 17.05.0-ce
|
||||
API version: 1.27 (downgraded from 1.29)
|
||||
Go version: go1.7.5
|
||||
Git commit: 89658be
|
||||
Built: Fri May 5 15:36:11 2017
|
||||
$ docker run --rm --network some-network \
|
||||
-e DOCKER_TLS_CERTDIR=/certs \
|
||||
-v some-docker-certs-client:/certs/client:ro \
|
||||
%%IMAGE%%:latest version
|
||||
Client: Docker Engine - Community
|
||||
Version: 18.09.8
|
||||
API version: 1.39
|
||||
Go version: go1.10.8
|
||||
Git commit: 0dd43dd87f
|
||||
Built: Wed Jul 17 17:38:58 2019
|
||||
OS/Arch: linux/amd64
|
||||
Experimental: false
|
||||
|
||||
Server:
|
||||
Version: 17.03.1-ce
|
||||
API version: 1.27 (minimum version 1.12)
|
||||
Go version: go1.7.5
|
||||
Git commit: c6d412e
|
||||
Built: Tue Mar 28 00:40:02 2017
|
||||
Server: Docker Engine - Community
|
||||
Engine:
|
||||
Version: 18.09.8
|
||||
API version: 1.39 (minimum version 1.12)
|
||||
Go version: go1.10.8
|
||||
Git commit: 0dd43dd87f
|
||||
Built: Wed Jul 17 17:48:49 2019
|
||||
OS/Arch: linux/amd64
|
||||
Experimental: false
|
||||
```
|
||||
|
||||
```console
|
||||
$ docker run -it --rm --link some-docker:docker %%IMAGE%%:edge sh
|
||||
$ docker run -it --rm --network some-network \
|
||||
-e DOCKER_TLS_CERTDIR=/certs \
|
||||
-v some-docker-certs-client:/certs/client:ro \
|
||||
%%IMAGE%%:latest sh
|
||||
/ # docker version
|
||||
Client:
|
||||
Version: 17.05.0-ce
|
||||
API version: 1.27 (downgraded from 1.29)
|
||||
Go version: go1.7.5
|
||||
Git commit: 89658be
|
||||
Built: Fri May 5 15:36:11 2017
|
||||
Client: Docker Engine - Community
|
||||
Version: 18.09.8
|
||||
API version: 1.39
|
||||
Go version: go1.10.8
|
||||
Git commit: 0dd43dd87f
|
||||
Built: Wed Jul 17 17:38:58 2019
|
||||
OS/Arch: linux/amd64
|
||||
Experimental: false
|
||||
|
||||
Server:
|
||||
Version: 17.03.1-ce
|
||||
API version: 1.27 (minimum version 1.12)
|
||||
Go version: go1.7.5
|
||||
Git commit: c6d412e
|
||||
Built: Tue Mar 28 00:40:02 2017
|
||||
Server: Docker Engine - Community
|
||||
Engine:
|
||||
Version: 18.09.8
|
||||
API version: 1.39 (minimum version 1.12)
|
||||
Go version: go1.10.8
|
||||
Git commit: 0dd43dd87f
|
||||
Built: Wed Jul 17 17:48:49 2019
|
||||
OS/Arch: linux/amd64
|
||||
Experimental: false
|
||||
```
|
||||
|
||||
```console
|
||||
$ docker run --rm --link some-docker:docker %%IMAGE%% info
|
||||
$ docker run --rm --network some-network \
|
||||
-e DOCKER_TLS_CERTDIR=/certs \
|
||||
-v some-docker-certs-client:/certs/client:ro \
|
||||
%%IMAGE%%:latest info
|
||||
Containers: 0
|
||||
Running: 0
|
||||
Paused: 0
|
||||
Stopped: 0
|
||||
Images: 0
|
||||
Server Version: 17.03.1-ce
|
||||
Storage Driver: vfs
|
||||
Server Version: 18.09.8
|
||||
Storage Driver: overlay2
|
||||
Backing Filesystem: extfs
|
||||
Supports d_type: true
|
||||
Native Overlay Diff: true
|
||||
Logging Driver: json-file
|
||||
Cgroup Driver: cgroupfs
|
||||
Plugins:
|
||||
Volume: local
|
||||
Network: bridge host macvlan null overlay
|
||||
Log: awslogs fluentd gcplogs gelf journald json-file local logentries splunk syslog
|
||||
Swarm: inactive
|
||||
Runtimes: runc
|
||||
Default Runtime: runc
|
||||
Init Binary: docker-init
|
||||
containerd version: 4ab9917febca54791c5f071a9d1f404867857fcc
|
||||
runc version: 54296cf40ad8143b62dbcaa1d90e520a2136ddfe
|
||||
init version: 949e6fa
|
||||
containerd version: 894b81a4b802e4eb2a91d1ce216b8817763c29fb
|
||||
runc version: 425e105d5a03fabd737a126ad93d62a9eeede87f
|
||||
init version: fec3683
|
||||
Security Options:
|
||||
apparmor
|
||||
seccomp
|
||||
Profile: default
|
||||
Kernel Version: 4.4.63-gentoo
|
||||
Operating System: Alpine Linux v3.5 (containerized)
|
||||
Kernel Version: 4.19.0-5-amd64
|
||||
Operating System: Alpine Linux v3.10 (containerized)
|
||||
OSType: linux
|
||||
Architecture: x86_64
|
||||
CPUs: 8
|
||||
Total Memory: 31.4 GiB
|
||||
Name: 393376fdc461
|
||||
ID: FDP3:4GDT:L2WP:D4CC:UAW5:RHNA:4Z4G:WQYY:YWBE:7RER:LV7E:USY5
|
||||
CPUs: 12
|
||||
Total Memory: 62.79GiB
|
||||
Name: e174d61a4a12
|
||||
ID: HJXG:3OT7:MGDL:Y2BL:WCYP:CKSP:CGAM:4BLH:NEI4:IURF:4COF:AH6N
|
||||
Docker Root Dir: /var/lib/docker
|
||||
Debug Mode (client): false
|
||||
Debug Mode (server): false
|
||||
Registry: https://index.docker.io/v1/
|
||||
WARNING: bridge-nf-call-iptables is disabled
|
||||
WARNING: bridge-nf-call-ip6tables is disabled
|
||||
Labels:
|
||||
Experimental: false
|
||||
Insecure Registries:
|
||||
127.0.0.0/8
|
||||
Live Restore Enabled: false
|
||||
Product License: Community Engine
|
||||
|
||||
WARNING: bridge-nf-call-iptables is disabled
|
||||
WARNING: bridge-nf-call-ip6tables is disabled
|
||||
```
|
||||
|
||||
```console
|
||||
$ docker run --rm -v /var/run/docker.sock:/var/run/docker.sock %%IMAGE%% version
|
||||
Client:
|
||||
Version: 17.05.0-ce
|
||||
API version: 1.28 (downgraded from 1.29)
|
||||
Go version: go1.7.5
|
||||
Git commit: 89658be
|
||||
Built: Fri May 5 15:36:11 2017
|
||||
$ docker run --rm -v /var/run/docker.sock:/var/run/docker.sock %%IMAGE%%:latest version
|
||||
Client: Docker Engine - Community
|
||||
Version: 18.09.8
|
||||
API version: 1.39
|
||||
Go version: go1.10.8
|
||||
Git commit: 0dd43dd87f
|
||||
Built: Wed Jul 17 17:38:58 2019
|
||||
OS/Arch: linux/amd64
|
||||
Experimental: false
|
||||
|
||||
Server:
|
||||
Version: 17.04.0-ce
|
||||
API version: 1.28 (minimum version 1.12)
|
||||
Go version: go1.8
|
||||
Git commit: 4845c56
|
||||
Built: Thu Apr 27 07:51:43 2017
|
||||
Server: Docker Engine - Community
|
||||
Engine:
|
||||
Version: 18.09.7
|
||||
API version: 1.39 (minimum version 1.12)
|
||||
Go version: go1.10.8
|
||||
Git commit: 2d0083d
|
||||
Built: Thu Jun 27 17:23:02 2019
|
||||
OS/Arch: linux/amd64
|
||||
Experimental: false
|
||||
```
|
||||
|
|
@ -136,7 +180,12 @@ Server:
|
|||
## Custom daemon flags
|
||||
|
||||
```console
|
||||
$ docker run --privileged --name some-overlay-docker -d %%IMAGE%%:dind --storage-driver=overlay
|
||||
$ docker run --privileged --name some-docker -d \
|
||||
--network some-network --network-alias docker \
|
||||
-e DOCKER_TLS_CERTDIR=/certs \
|
||||
-v some-docker-certs-ca:/certs/ca \
|
||||
-v some-docker-certs-client:/certs/client \
|
||||
%%IMAGE%%:dind --storage-driver overlay2
|
||||
```
|
||||
|
||||
## Where to Store Data
|
||||
|
|
|
|||
Loading…
Reference in New Issue