Merge branch 'fix/docker-in-docker-ci-documentation' into 'master'

Update using_docker_build.md, clarify the 'privileged' mode requirement

Related to #15428

Fixes gitlab-org/gitlab-ci-multi-runner#1261

See merge request !3909

doc/ci/docker/using_docker_build.md

@@ -75,37 +75,80 @@ For more information please checkout [On Docker security: `docker` group conside
 
 ## 2. Use docker-in-docker executor
 
-Second approach is to use special Docker image with all tools installed (`docker` and `docker-compose`) and run build script in context of that image in privileged mode.
+The second approach is to use the special Docker image with all tools installed
+(`docker` and `docker-compose`) and run the build script in context of that
+image in privileged mode.
+
 In order to do that follow the steps:
 
 1. Install [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/#installation).
 
-1. Register GitLab Runner from command line to use `docker` and `privileged` mode:
+1. Register GitLab Runner from the command line to use `docker` and `privileged`
+   mode:
 
     ```bash
-    $ sudo gitlab-runner register -n \
+    sudo gitlab-runner register -n \
       --url https://gitlab.com/ci \
       --token RUNNER_TOKEN \
       --executor docker \
       --description "My Docker Runner" \
-      --docker-image "gitlab/dind:latest" \
+      --docker-image "docker:latest" \
       --docker-privileged
     ```
 
-    The above command will register new Runner to use special [gitlab/dind](https://registry.hub.docker.com/u/gitlab/dind/) image which is provided by GitLab Inc.
-    The image at the start runs Docker daemon in [docker-in-docker](https://blog.docker.com/2013/09/docker-can-now-run-within-docker/) mode.
+    The above command will register a new Runner to use the special
+    `docker:latest` image which is provided by Docker. **Notice that it's using
+    the `privileged` mode to start the build and service containers.** If you
+    want to use [docker-in-docker] mode, you always have to use `privileged = true`
+    in your Docker containers.
+
+    The above command will create a `config.toml` entry similar to this:
+
+    ```
+    [[runners]]
+      url = "https://gitlab.com/ci"
+      token = TOKEN
+      executor = "docker"
+      [runners.docker]
+        tls_verify = false
+        image = "docker:latest"
+        privileged = true
+        disable_cache = false
+        volumes = ["/cache"]
+      [runners.cache]
+        Insecure = false
+    ```
+
+    If you want to use the Shared Runners available on your GitLab CE/EE
+    installation in order to build Docker images, then make sure that your
+    Shared Runners configuration has the `privileged` mode set to `true`.
 
 1. You can now use `docker` from build script:
 
     ```yaml
+    image: docker:latest
+
+    services:
+    - docker:dind
+
     before_script:
     - docker info
 
-    build_image:
+    build:
+      stage: build
       script:
       - docker build -t my-docker-image .
       - docker run my-docker-image /script/to/run/tests
     ```
 
-1. However, by enabling `--docker-privileged` you are effectively disables all security mechanisms of containers and exposing your host to privilege escalation which can lead to container breakout.
-For more information, check out [Runtime privilege](https://docs.docker.com/reference/run/#runtime-privilege-linux-capabilities-and-lxc-configuration).
\ No newline at end of file
+1. However, by enabling `--docker-privileged` you are effectively disabling all
+   the security mechanisms of containers and exposing your host to privilege
+   escalation which can lead to container breakout.
+
+   For more information, check out the official Docker documentation on
+   [Runtime privilege and Linux capabilities][docker-cap].
+
+An example project using this approach can be found here: https://gitlab.com/gitlab-examples/docker.
+
+[docker-in-docker]: https://blog.docker.com/2013/09/docker-can-now-run-within-docker/
+[docker-cap]: https://docs.docker.com/reference/run/#runtime-privilege-and-linux-capabilities