Documentation: update Docker-in-Docker best practices and the suggested workflow
Hey @markpundsack and @ayufan!
Today I read https://docs.gitlab.com/ce/ci/docker/using_docker_build.html and I have mixed feelings. All the executor=docker solutions by GitLab staff essentially bypass great features GitLab CI offers - like caching, artifacts, and so on, since the actual "build" runs in a container not managed by gitlab-runner. (And I'm deliberately ignoring the executor=shell solution because it's not something feasible for most, plus it's not part of GitLab.com's free offering)
Then I found this ticket: https://gitlab.com/gitlab-org/gitlab-ce/issues/20383. Allow predefined variables for keyword 'image:' in .gitlab-ci.yml, tl;dr - perform var substitution in image: registry.example.com:443/mygroup/myproject:"${CI_PIPELINE_ID}" syntax.
I think this is undoubtedly the easiest and the most flexible solution. Build an image, push to GitLab registry, then pull it "natively" in the next stage! It's an improvement of DIND approach as described in https://docs.gitlab.com/ce/ci/docker/using_docker_build.html#use-docker-in-docker-executor - this caveat no longer applies:
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 also means jobs can be slower because there's no caching of layers.
(By the way, this is quite inaccurate... This suggests a "native" CI build doesn't get a clean environment. Well, when one doesn't enable cache, they do get clean environment in each build.)
Therefore, I propose that the image: myimage:${CI_PIPELINE_ID} flow be described in the docs and considered the preferred solution. Your thoughts, guys? That also includes changing the examples from https://docs.gitlab.com/ce/ci/docker/using_docker_build.html#using-the-gitlab-container-registry to use that approach rather than docker run.
Context: We (EE customers: DreamHost, LLC) lost several hours today trying to figure out how exactly we should tackle Docker in Docker topic without losing GitLab CI native capabilities like artifacts and cache, before coming across image: myimage:${CI_...} solution quite randomly.
Additionally, the mentioned documentation should mention which options are available on GitLab.com. It's not clear what these tags stand for. For example: will DIND work only on runners tagged as docker? If so, this should be documented. If not, what is the purpose of that tag?
