docker-library
/
docs
mirror of https://github.com/docker-library/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1538 from infosiftr/docker-revamp 

Revamp "docker" image docs, especially for TLS
This commit is contained in:
yosifkit 2019-07-19 17:03:57 -07:00 committed by GitHub
parent 1b2a2b1562 f2caf393ce
commit 56cea55297
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 116 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

163
docker/content.md
View File

@ -16,119 +16,163 @@ If you are still convinced that you need Docker-in-Docker and not just access to
[![asciicast](https://asciinema.org/a/24707.png)](https://asciinema.org/a/24707) [![asciicast](https://asciinema.org/a/24707.png)](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 ## Start a daemon instance
```console ```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). **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 ## Connect to it from a second container
```console ```console
$ docker run --rm --link some-docker:docker %%IMAGE%%:edge version $ docker run --rm --network some-network \
Client: -e DOCKER_TLS_CERTDIR=/certs \
Version: 17.05.0-ce -v some-docker-certs-client:/certs/client:ro \
API version: 1.27 (downgraded from 1.29) %%IMAGE%%:latest version
Go version: go1.7.5 Client: Docker Engine - Community
Git commit: 89658be Version: 18.09.8
Built: Fri May 5 15:36:11 2017 API version: 1.39
Go version: go1.10.8
Git commit: 0dd43dd87f
Built: Wed Jul 17 17:38:58 2019
OS/Arch: linux/amd64 OS/Arch: linux/amd64
Experimental: false
Server: Server: Docker Engine - Community
Version: 17.03.1-ce Engine:
API version: 1.27 (minimum version 1.12) Version: 18.09.8
Go version: go1.7.5 API version: 1.39 (minimum version 1.12)
Git commit: c6d412e Go version: go1.10.8
Built: Tue Mar 28 00:40:02 2017 Git commit: 0dd43dd87f
Built: Wed Jul 17 17:48:49 2019
OS/Arch: linux/amd64 OS/Arch: linux/amd64
Experimental: false Experimental: false
``` ```
```console ```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 / # docker version
Client: Client: Docker Engine - Community
Version: 17.05.0-ce Version: 18.09.8
API version: 1.27 (downgraded from 1.29) API version: 1.39
Go version: go1.7.5 Go version: go1.10.8
Git commit: 89658be Git commit: 0dd43dd87f
Built: Fri May 5 15:36:11 2017 Built: Wed Jul 17 17:38:58 2019
OS/Arch: linux/amd64 OS/Arch: linux/amd64
Experimental: false
Server: Server: Docker Engine - Community
Version: 17.03.1-ce Engine:
API version: 1.27 (minimum version 1.12) Version: 18.09.8
Go version: go1.7.5 API version: 1.39 (minimum version 1.12)
Git commit: c6d412e Go version: go1.10.8
Built: Tue Mar 28 00:40:02 2017 Git commit: 0dd43dd87f
Built: Wed Jul 17 17:48:49 2019
OS/Arch: linux/amd64 OS/Arch: linux/amd64
Experimental: false Experimental: false
``` ```
```console ```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 Containers: 0
Running: 0 Running: 0
Paused: 0 Paused: 0
Stopped: 0 Stopped: 0
Images: 0 Images: 0
Server Version: 17.03.1-ce Server Version: 18.09.8
Storage Driver: vfs Storage Driver: overlay2
Backing Filesystem: extfs
Supports d_type: true
Native Overlay Diff: true
Logging Driver: json-file Logging Driver: json-file
Cgroup Driver: cgroupfs Cgroup Driver: cgroupfs
Plugins: Plugins:
Volume: local Volume: local
Network: bridge host macvlan null overlay Network: bridge host macvlan null overlay
Log: awslogs fluentd gcplogs gelf journald json-file local logentries splunk syslog
Swarm: inactive Swarm: inactive
Runtimes: runc Runtimes: runc
Default Runtime: runc Default Runtime: runc
Init Binary: docker-init Init Binary: docker-init
containerd version: 4ab9917febca54791c5f071a9d1f404867857fcc containerd version: 894b81a4b802e4eb2a91d1ce216b8817763c29fb
runc version: 54296cf40ad8143b62dbcaa1d90e520a2136ddfe runc version: 425e105d5a03fabd737a126ad93d62a9eeede87f
init version: 949e6fa init version: fec3683
Security Options: Security Options:
apparmor
seccomp seccomp
Profile: default Profile: default
Kernel Version: 4.4.63-gentoo Kernel Version: 4.19.0-5-amd64
Operating System: Alpine Linux v3.5 (containerized) Operating System: Alpine Linux v3.10 (containerized)
OSType: linux OSType: linux
Architecture: x86_64 Architecture: x86_64
CPUs: 8 CPUs: 12
Total Memory: 31.4 GiB Total Memory: 62.79GiB
Name: 393376fdc461 Name: e174d61a4a12
ID: FDP3:4GDT:L2WP:D4CC:UAW5:RHNA:4Z4G:WQYY:YWBE:7RER:LV7E:USY5 ID: HJXG:3OT7:MGDL:Y2BL:WCYP:CKSP:CGAM:4BLH:NEI4:IURF:4COF:AH6N
Docker Root Dir: /var/lib/docker Docker Root Dir: /var/lib/docker
Debug Mode (client): false Debug Mode (client): false
Debug Mode (server): false Debug Mode (server): false
Registry: https://index.docker.io/v1/ Registry: https://index.docker.io/v1/
WARNING: bridge-nf-call-iptables is disabled Labels:
WARNING: bridge-nf-call-ip6tables is disabled
Experimental: false Experimental: false
Insecure Registries: Insecure Registries:
127.0.0.0/8 127.0.0.0/8
Live Restore Enabled: false Live Restore Enabled: false
Product License: Community Engine
WARNING: bridge-nf-call-iptables is disabled
WARNING: bridge-nf-call-ip6tables is disabled
``` ```
```console ```console
$ docker run --rm -v /var/run/docker.sock:/var/run/docker.sock %%IMAGE%% version $ docker run --rm -v /var/run/docker.sock:/var/run/docker.sock %%IMAGE%%:latest version
Client: Client: Docker Engine - Community
Version: 17.05.0-ce Version: 18.09.8
API version: 1.28 (downgraded from 1.29) API version: 1.39
Go version: go1.7.5 Go version: go1.10.8
Git commit: 89658be Git commit: 0dd43dd87f
Built: Fri May 5 15:36:11 2017 Built: Wed Jul 17 17:38:58 2019
OS/Arch: linux/amd64 OS/Arch: linux/amd64
Experimental: false
Server: Server: Docker Engine - Community
Version: 17.04.0-ce Engine:
API version: 1.28 (minimum version 1.12) Version: 18.09.7
Go version: go1.8 API version: 1.39 (minimum version 1.12)
Git commit: 4845c56 Go version: go1.10.8
Built: Thu Apr 27 07:51:43 2017 Git commit: 2d0083d
Built: Thu Jun 27 17:23:02 2019
OS/Arch: linux/amd64 OS/Arch: linux/amd64
Experimental: false Experimental: false
``` ```
@ -136,7 +180,12 @@ Server:
## Custom daemon flags ## Custom daemon flags
```console ```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 ## Where to Store Data