Merge branch 'docs/cross-link-kaniko' into 'master'

Improve GitLab and Docker configuration docs

Closes #31379

See merge request gitlab-org/gitlab-ce!30498

doc/ci/docker/using_docker_build.md

@@ -6,7 +6,6 @@ type: concepts, howto
 
 GitLab CI/CD allows you to use Docker Engine to build and test docker-based projects.
 
-
 One of the new trends in Continuous Integration/Deployment is to:
 
 1. Create an application image.
@@ -29,7 +28,16 @@ during jobs.
 
 ## Runner Configuration
 
-There are three methods to enable the use of `docker build` and `docker run` during jobs; each with their own tradeoffs.
+There are three methods to enable the use of `docker build` and `docker run`
+during jobs; each with their own tradeoffs.
+
+An alternative to using `docker build` is to [use kaniko](using_kaniko.md).
+This avoids having to execute Runner in privileged mode.
+
+TIP: **Tip:**
+To see how Docker and Runner are configured for shared Runners on
+GitLab.com, see [GitLab.com Shared
+Runners](../../user/gitlab_com/index.md#shared-runners).
 
 ### Use shell executor
 
@@ -115,6 +123,13 @@ In order to do that, follow the steps:
     want to use [docker-in-docker] mode, you always have to use `privileged = true`
     in your Docker containers.
 
+    DANGER: **Danger:**
+    By enabling `--docker-privileged`, you are effectively disabling all of
+    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].
+
     The above command will create a `config.toml` entry similar to this:
 
     ```toml
@@ -173,11 +188,6 @@ In order to do that, follow the steps:
 Docker-in-Docker works well, and is the recommended configuration, but it is
 not without its own challenges:
 
-- By enabling `--docker-privileged`, you are effectively disabling all of
-  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].
 - When using docker-in-docker, each job is in a clean environment without the past
   history. Concurrent jobs work fine because every build gets it's own
   instance of Docker engine so they won't conflict with each other. But this

doc/user/group/clusters/index.md

@@ -137,6 +137,13 @@ The result will then be:
 - The Staging cluster will be used for the `deploy to staging` job.
 - The Production cluster will be used for the `deploy to production` job.
 
+## Security of Runners
+
+For important information about securely configuring GitLab Runners, see
+[Security of
+Runners](../../project/clusters/index.md#security-of-gitlab-runners)
+documentation for project-level clusters.
+
 <!-- ## Troubleshooting
 
 Include any troubleshooting steps that you can foresee. If you know beforehand what issues

doc/user/project/clusters/index.md

@@ -343,10 +343,15 @@ turn can do almost everything that the host can do. Be aware of the
 inherent security risk associated with performing `docker run` operations on
 arbitrary images as they effectively have root access.
 
-If you don't want to use GitLab Runner in privileged mode, first make sure that
-you don't have it installed via the applications, and then use the
-[Runner's Helm chart](../../../install/kubernetes/gitlab_runner_chart.md) to
-install it manually.
+If you don't want to use GitLab Runner in privileged mode, either:
+
+- Use shared Runners on GitLab.com. They don't have this security issue.
+- Set up your own Runners using configuration described at
+  [Shared Runners](../../gitlab_com/index.md#shared-runners). This involves:
+  1. Making sure that you don't have it installed via
+     [the applications](#installing-applications).
+  1. Installing a Runner
+     [using `docker+machine`](https://docs.gitlab.com/runner/executors/docker_machine.html).
 
 ## Installing applications