Skip to content

G
gitlab-ce
Commit 7fbf90c8 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis Committed by Evan Read
Browse files
Options

Use a stable version of Docker and remove overlay variable 

This updates the documentation to use a specific Docker version.
Suggesting users to use docker:stable and docker:dind is fairly
dangerous, since it will keep being updated to a new version without
them knowing.

Ports https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/31323
parent b7e51d1c
Hide whitespace changes
Inline Side-by-side
Showing with 51 additions and 58 deletions
doc/ci/docker/using_docker_build.md
View file @ 7fbf90c8
...@@ -117,10 +117,10 @@ not without its own challenges: ...@@ -117,10 +117,10 @@ not without its own challenges:
history. Concurrent jobs work fine because every build gets it's own 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 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. also means jobs can be slower because there's no caching of layers.
- By default, `docker:dind` uses `--storage-driver vfs` which is the slowest - By default, Docker 17.09 and higher uses `--storage-driver overlay2` which is
form offered. To use a different driver, see the recommended storage driver. See [Using the overlayfs driver](#using-the-overlayfs-driver)
[Using the overlayfs driver](#using-the-overlayfs-driver). for details.
- Since the `docker:dind` container and the runner container don't share their - Since the `docker:19.03.1-dind` container and the Runner container don't share their
root filesystem, the job's working directory can be used as a mount point for root filesystem, the job's working directory can be used as a mount point for
child containers. For example, if you have files you want to share with a child containers. For example, if you have files you want to share with a
child container, you may create a subdirectory under `/builds/$CI_PROJECT_PATH` child container, you may create a subdirectory under `/builds/$CI_PROJECT_PATH`
...@@ -156,7 +156,6 @@ docker-in-docker service and ...@@ -156,7 +156,6 @@ docker-in-docker service and
support this. support this.
1. Install [GitLab Runner](https://docs.gitlab.com/runner/install). 1. Install [GitLab Runner](https://docs.gitlab.com/runner/install).
1. Register GitLab Runner from the command line to use `docker` and `privileged` 1. Register GitLab Runner from the command line to use `docker` and `privileged`
mode: mode:
...@@ -218,13 +217,10 @@ support this. ...@@ -218,13 +217,10 @@ support this.
# https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#accessing-the-services. # https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#accessing-the-services.
# #
# Note that if you're using the Kubernetes executor, the variable # Note that if you're using the Kubernetes executor, the variable
# should be set to tcp://localhost:2376/ because of how the # should be set to tcp://localhost:2376 because of how the
# Kubernetes executor connects services to the job container # Kubernetes executor connects services to the job container
# DOCKER_HOST: tcp://localhost:2376/ # DOCKER_HOST: tcp://localhost:2376
# #
# When using dind, it's wise to use the overlayfs driver for
# improved performance.
DOCKER_DRIVER: overlay2
# Specify to Docker where to create the certificates, Docker will # Specify to Docker where to create the certificates, Docker will
# create them automatically on boot, and will create # create them automatically on boot, and will create
# `/certs/client` that will be shared between the service and job # `/certs/client` that will be shared between the service and job
...@@ -283,15 +279,12 @@ variables: ...@@ -283,15 +279,12 @@ variables:
# https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#accessing-the-services # https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#accessing-the-services
# #
# Note that if you're using the Kubernetes executor, the variable should be set to # Note that if you're using the Kubernetes executor, the variable should be set to
# tcp://localhost:2375/ because of how the Kubernetes executor connects services # tcp://localhost:2375 because of how the Kubernetes executor connects services
# to the job container # to the job container
# DOCKER_HOST: tcp://localhost:2375/ # DOCKER_HOST: tcp://localhost:2375
# #
# For non-Kubernetes executors, we use tcp://docker:2375/ # For non-Kubernetes executors, we use tcp://docker:2375
DOCKER_HOST: tcp://docker:2375/ DOCKER_HOST: tcp://docker:2375
# When using dind, it's wise to use the overlayfs driver for
# improved performance.
DOCKER_DRIVER: overlay2
# #
# This will instruct Docker not to start over TLS. # This will instruct Docker not to start over TLS.
DOCKER_TLS_CERTDIR: "" DOCKER_TLS_CERTDIR: ""
...@@ -317,13 +310,12 @@ container so that Docker is available in the context of that image. ...@@ -317,13 +310,12 @@ container so that Docker is available in the context of that image.
NOTE: **Note:** NOTE: **Note:**
If you bind the Docker socket [when using GitLab Runner 11.11 or If you bind the Docker socket [when using GitLab Runner 11.11 or
newer](https://gitlab.com/gitlab-org/gitlab-runner/merge_requests/1261), newer](https://gitlab.com/gitlab-org/gitlab-runner/merge_requests/1261),
you can no longer use `docker:dind` as a service because volume bindings you can no longer use `docker:19.03.1-dind` as a service because volume bindings
are done to the services as well, making these incompatible. are done to the services as well, making these incompatible.
In order to do that, follow the steps: In order to do that, follow the steps:
1. Install [GitLab Runner](https://docs.gitlab.com/runner/install). 1. Install [GitLab Runner](https://docs.gitlab.com/runner/install).
1. Register GitLab Runner from the command line to use `docker` and share `/var/run/docker.sock`: 1. Register GitLab Runner from the command line to use `docker` and share `/var/run/docker.sock`:
```bash ```bash
...@@ -332,14 +324,14 @@ In order to do that, follow the steps: ...@@ -332,14 +324,14 @@ In order to do that, follow the steps:
--registration-token REGISTRATION_TOKEN \ --registration-token REGISTRATION_TOKEN \
--executor docker \ --executor docker \
--description "My Docker Runner" \ --description "My Docker Runner" \
--docker-image "docker:stable" \ --docker-image "docker:19.03.1" \
--docker-volumes /var/run/docker.sock:/var/run/docker.sock --docker-volumes /var/run/docker.sock:/var/run/docker.sock
``` ```
The above command will register a new Runner to use the special The above command will register a new Runner to use the special
`docker:stable` image which is provided by Docker. **Notice that it's using `docker:19.03.1` image which is provided by Docker. **Notice that it's using
the Docker daemon of the Runner itself, and any containers spawned by docker the Docker daemon of the Runner itself, and any containers spawned by Docker
commands will be siblings of the Runner rather than children of the runner.** commands will be siblings of the Runner rather than children of the Runner.**
This may have complications and limitations that are unsuitable for your workflow. This may have complications and limitations that are unsuitable for your workflow.
The above command will create a `config.toml` entry similar to this: The above command will create a `config.toml` entry similar to this:
...@@ -351,7 +343,7 @@ In order to do that, follow the steps: ...@@ -351,7 +343,7 @@ In order to do that, follow the steps:
executor = "docker" executor = "docker"
[runners.docker] [runners.docker]
tls_verify = false tls_verify = false
image = "docker:stable" image = "docker:19.03.1"
privileged = false privileged = false
disable_cache = false disable_cache = false
volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"] volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"]
...@@ -360,10 +352,11 @@ In order to do that, follow the steps: ...@@ -360,10 +352,11 @@ In order to do that, follow the steps:
``` ```
1. You can now use `docker` in the build script (note that you don't need to 1. You can now use `docker` in the build script (note that you don't need to
include the `docker:dind` service as when using the Docker in Docker executor): include the `docker:19.03.1-dind` service as when using the Docker in Docker
executor):
```yaml ```yaml
image: docker:stable image: docker:19.03.1
before_script: before_script:
- docker info - docker info
...@@ -417,14 +410,15 @@ any image that's used with the `--cache-from` argument must first be pulled ...@@ -417,14 +410,15 @@ any image that's used with the `--cache-from` argument must first be pulled
Here's a simple `.gitlab-ci.yml` file showing how Docker caching can be utilized: Here's a simple `.gitlab-ci.yml` file showing how Docker caching can be utilized:
```yaml ```yaml
image: docker:stable image: docker:19.03.1
services: services:
- docker:dind - docker:19.03.1-dind
variables: variables:
DOCKER_HOST: tcp://docker:2375 # Use TLS https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#tls-enabled
DOCKER_DRIVER: overlay2 DOCKER_HOST: tcp://docker:2376
DOCKER_TLS_CERTDIR: "/certs"
before_script: before_script:
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
...@@ -597,7 +591,6 @@ assuming you have it configured with [TLS enabled](#tls-enabled): ...@@ -597,7 +591,6 @@ assuming you have it configured with [TLS enabled](#tls-enabled):
# `/certs/client` that will be shared between the service and # `/certs/client` that will be shared between the service and
# build container. # build container.
DOCKER_TLS_CERTDIR: "/certs" DOCKER_TLS_CERTDIR: "/certs"
DOCKER_DRIVER: overlay2
stage: build stage: build
script: script:
- docker build -t my-docker-image . - docker build -t my-docker-image .
...@@ -618,37 +611,36 @@ If you're using docker-in-docker on your Runners, this is how your `.gitlab-ci.y ...@@ -618,37 +611,36 @@ If you're using docker-in-docker on your Runners, this is how your `.gitlab-ci.y
could look like: could look like:
```yaml ```yaml
build: build:
image: docker:stable image: docker:19.03.1
services: stage: build
- docker:dind services:
variables: - docker:19.03.1-dind
DOCKER_HOST: tcp://docker:2375 variables:
DOCKER_DRIVER: overlay2 # Use TLS https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#tls-enabled
stage: build DOCKER_HOST: tcp://docker:2376
script: DOCKER_TLS_CERTDIR: "/certs"
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY script:
- docker build -t $CI_REGISTRY/group/project/image:latest . - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
- docker push $CI_REGISTRY/group/project/image:latest - docker build -t $CI_REGISTRY/group/project/image:latest .
- docker push $CI_REGISTRY/group/project/image:latest
``` ```
You can also make use of [other variables](../variables/README.md) to avoid hardcoding: You can also make use of [other variables](../variables/README.md) to avoid hardcoding:
```yaml ```yaml
services:
- docker:dind
variables:
DOCKER_HOST: tcp://docker:2375
DOCKER_DRIVER: overlay2
IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG
before_script:
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
build: build:
image: docker:19.03.1
stage: build stage: build
services:
- docker:19.03.1-dind
variables:
# Use TLS https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#tls-enabled
DOCKER_HOST: tcp://docker:2376
DOCKER_TLS_CERTDIR: "/certs"
IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG
script: script:
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
- docker build -t $IMAGE_TAG . - docker build -t $IMAGE_TAG .
- docker push $IMAGE_TAG - docker push $IMAGE_TAG
``` ```
...@@ -667,9 +659,9 @@ when needed. Changes to `master` also get tagged as `latest` and deployed using ...@@ -667,9 +659,9 @@ when needed. Changes to `master` also get tagged as `latest` and deployed using
an application-specific deploy script: an application-specific deploy script:
```yaml ```yaml
image: docker:stable image: docker:19.03.1
services: services:
- docker:dind - docker:19.03.1-dind
stages: stages:
- build - build
...@@ -678,8 +670,9 @@ stages: ...@@ -678,8 +670,9 @@ stages:
- deploy - deploy
variables: variables:
DOCKER_HOST: tcp://docker:2375 # Use TLS https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#tls-enabled
DOCKER_DRIVER: overlay2 DOCKER_HOST: tcp://docker:2376
DOCKER_TLS_CERTDIR: "/certs"
CONTAINER_TEST_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG CONTAINER_TEST_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG
CONTAINER_RELEASE_IMAGE: $CI_REGISTRY_IMAGE:latest CONTAINER_RELEASE_IMAGE: $CI_REGISTRY_IMAGE:latest
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7