diff options
Diffstat (limited to 'doc/ci/docker/using_docker_build.md')
| -rw-r--r-- | doc/ci/docker/using_docker_build.md | 54 |
1 files changed, 46 insertions, 8 deletions
diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index df0c7b69d46..ea4ad25637b 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -14,6 +14,9 @@ test it, and publish it to a container registry. To run Docker commands in your CI/CD jobs, you must configure GitLab Runner to support `docker` commands. +If you want to build Docker images without enabling privileged mode on the runner, +you can use a [Docker alternative](#docker-alternatives). + ## Enable Docker commands in your CI/CD jobs To enable Docker commands for your CI/CD jobs, you can use: @@ -22,9 +25,6 @@ To enable Docker commands for your CI/CD jobs, you can use: - [Docker-in-Docker](#use-docker-in-docker) - [Docker socket binding](#use-docker-socket-binding) -If you don't want to execute a runner in privileged mode, -but want to use `docker build`, you can also use [`kaniko`](using_kaniko.md) or [`buildah`](https://github.com/containers/buildah). - If you are using shared runners on GitLab.com, [learn more about how these runners are configured](../runners/index.md). @@ -133,7 +133,7 @@ To use Docker-in-Docker with TLS enabled: - This command registers a new runner to use the `docker:20.10.16` image. To start the build and service containers, it uses the `privileged` mode. - If you want to use [Docker-in-Docker](https://www.docker.com/blog/docker-can-now-run-within-docker/), + If you want to use Docker-in-Docker, you must always use `privileged = true` in your Docker containers. - This command mounts `/certs/client` for the service and build container, which is needed for the Docker client to use the @@ -345,8 +345,8 @@ not without its own challenges: root file system, you can use the job's working directory as a mount point for child containers. For example, if you have files you want to share with a child container, you might create a subdirectory under `/builds/$CI_PROJECT_PATH` - and use it as your mount point. For a more detailed explanation, view [issue - #41227](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41227). + and use it as your mount point. For a more detailed explanation, view + [issue #41227](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41227). ```yaml variables: @@ -406,8 +406,8 @@ sudo gitlab-runner register -n \ ##### Enable registry mirror for `docker:dind` service When the Docker daemon starts inside of the service container, it uses -the default configuration. You may want to configure a [registry -mirror](https://docs.docker.com/registry/recipes/mirror/) for +the default configuration. You may want to configure a +[registry mirror](https://docs.docker.com/registry/recipes/mirror/) for performance improvements and to ensure you don't reach Docker Hub rate limits. ###### The service in the `.gitlab-ci.yml` file @@ -831,6 +831,44 @@ If you're running multiple runners, you have to modify all configuration files. Read more about the [runner configuration](https://docs.gitlab.com/runner/configuration/) and [using the OverlayFS storage driver](https://docs.docker.com/engine/userguide/storagedriver/overlayfs-driver/). +## Docker alternatives + +To build Docker images without enabling privileged mode on the runner, you can +use one of these alternatives: + +- [`kaniko`](using_kaniko.md). +- [`buildah`](https://github.com/containers/buildah). + +For example, with `buildah`: + +```yaml +# Some details from https://major.io/2019/05/24/build-containers-in-gitlab-ci-with-buildah/ + +build: + stage: build + image: quay.io/buildah/stable + variables: + # Use vfs with buildah. Docker offers overlayfs as a default, but buildah + # cannot stack overlayfs on top of another overlayfs filesystem. + STORAGE_DRIVER: vfs + # Write all image metadata in the docker format, not the standard OCI format. + # Newer versions of docker can handle the OCI format, but older versions, like + # the one shipped with Fedora 30, cannot handle the format. + BUILDAH_FORMAT: docker + # You may need this workaround for some errors: https://stackoverflow.com/a/70438141/1233435 + BUILDAH_ISOLATION: chroot + FQ_IMAGE_NAME: "${CI_REGISTRY_IMAGE}/test" + before_script: + # Log in to the GitLab container registry + - export REGISTRY_AUTH_FILE=${HOME}/auth.json + - echo "$CI_REGISTRY_PASSWORD" | buildah login -u "$CI_REGISTRY_USER" --password-stdin $CI_REGISTRY + script: + - buildah images + - buildah build -t $FQ_IMAGE_NAME + - buildah images + - buildah push $FQ_IMAGE_NAME +``` + ## Use the GitLab Container Registry After you've built a Docker image, you can push it up to the built-in |