From 83aeb219f0c790d8b8ec7a5c3f6d25212f05b6a4 Mon Sep 17 00:00:00 2001 From: Tonis Tiigi Date: Wed, 31 Oct 2018 16:16:14 -0700 Subject: [PATCH] buildkit reference docs Signed-off-by: Tonis Tiigi Signed-off-by: Tibor Vass Signed-off-by: Sebastiaan van Stijn --- docs/reference/builder.md | 118 +++++++++++++++++++++++++++++++++++++- 1 file changed, 117 insertions(+), 1 deletion(-) diff --git a/docs/reference/builder.md b/docs/reference/builder.md index 644ad91f5e..6b55151fb7 100644 --- a/docs/reference/builder.md +++ b/docs/reference/builder.md @@ -121,6 +121,28 @@ registries. When you're done with your build, you're ready to look into [*Pushing a repository to its registry*](https://docs.docker.com/engine/tutorials/dockerrepos/#/contributing-to-docker-hub). + +## BuildKit + +Starting with version 18.09, Docker supports a new backend for executing your +builds that is provided by the [moby/buildkit](https://github.com/moby/buildkit) +project. The BuildKit backend provides many benefits compared to the old +implementation. For example, BuildKit can: + +* Detect and skip executing unused build stages +* Parallelize building independent build stages +* Incrementally transfer only the changed files in your build context between builds +* Detect and skip transferring unused files in your build context +* Use external Dockerfile implementations with many new features +* Avoid side-effects with rest of the API (intermediate images and containers) +* Prioritize your build cache for automatic pruning + +To use the BuildKit backend, you need to set an environment variable +`DOCKER_BUILDKIT=1` on the CLI before invoking `docker build`. + +To learn about the experimental Dockerfile syntax available to BuildKit-based +builds [refer to the documentation in the BuildKit repository](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/experimental.md). + ## Format Here is the format of the `Dockerfile`: @@ -224,10 +246,64 @@ following lines are all treated identically: # dIrEcTiVe=value ``` -The following parser directive is supported: +The following parser directives are supported: +* `syntax` * `escape` +## syntax + + # syntax=[remote image reference] + +For example: + + # syntax=docker/dockerfile + # syntax=docker/dockerfile:1.0 + # syntax=docker.io/docker/dockerfile:1 + # syntax=docker/dockerfile:1.0.0-experimental + # syntax=example.com/user/repo:tag@sha256:abcdef... + +This feature is only enabled if the [BuildKit](#buildkit) backend is used. + +The syntax directive defines the location of the Dockerfile builder that is used for +building the current Dockerfile. The BuildKit backend allows to seamlessly use +external implementations of builders that are distributed as Docker images and +execute inside a container sandbox environment. + +Custom Dockerfile implementation allows you to: + - Automatically get bugfixes without updating the daemon + - Make sure all users are using the same implementation to build your Dockerfile + - Use the latest features without updating the daemon + - Try out new experimental or third-party features + +### Official releases + +Docker distributes official versions of the images that can be used for building +Dockerfiles under `docker/dockerfile` repository on Docker Hub. There are two +channels where new images are released: stable and experimental. + +Stable channel follows semantic versioning. For example: + + - docker/dockerfile:1.0.0 - only allow immutable version 1.0.0 + - docker/dockerfile:1.0 - allow versions 1.0.* + - docker/dockerfile:1 - allow versions 1.*.* + - docker/dockerfile:latest - latest release on stable channel + +The experimental channel uses incremental versioning with the major and minor +component from the stable channel on the time of the release. For example: + + - docker/dockerfile:1.0.1-experimental - only allow immutable version 1.0.1-experimental + - docker/dockerfile:1.0-experimental - latest experimental releases after 1.0 + - docker/dockerfile:experimental - latest release on experimental channel + +You should choose a channel that best fits your needs. If you only want +bugfixes, you should use `docker/dockerfile:1.0`. If you want to benefit from +experimental features, you should use the experimental channel. If you are using +the experimental channel, newer releases may not be backwards compatible, so it +is recommended to use an immutable full version variant. + +For master builds and nightly feature releases refer to the description in [the source repository](https://github.com/moby/buildkit/blob/master/README.md). + ## escape # escape=\ (backslash) @@ -1627,6 +1703,38 @@ RUN echo "Hello World" When building this Dockerfile, the `HTTP_PROXY` is preserved in the `docker history`, and changing its value invalidates the build cache. +### Automatic platform ARGs in the global scope + +This feature is only available when using the [BuildKit](#buildkit) backend. + +Docker predefines a set of `ARG` variables with information on the platform of +the node performing the build (build platform) and on the platform of the +resulting image (target platform). The target platform can be specified with +the `--platform` flag on `docker build`. + +The following `ARG` variables are set automatically: + +* `TARGETPLATFORM` - platform of the build result. Eg `linux/amd64`, `linux/arm/v7`, `windows/amd64`. +* `TARGETOS` - OS component of TARGETPLATFORM +* `TARGETARCH` - architecture component of TARGETPLATFORM +* `TARGETVARIANT` - variant component of TARGETPLATFORM +* `BUILDPLATFORM` - platform of the node performing the build. +* `BUILDOS` - OS component of BUILDPLATFORM +* `BUILDARCH` - OS component of BUILDPLATFORM +* `BUILDVARIANT` - OS component of BUILDPLATFORM + +These arguments are defined in the global scope so are not automatically +available inside build stages or for your `RUN` commands. To expose one of +these arguments inside the build stage redefine it without value. + +For example: + +```Dockerfile +FROM alpine +ARG TARGETPLATFORM +RUN echo "I'm building for $TARGETPLATFORM" +``` + ### Impact on build caching `ARG` variables are not persisted into the built image as `ENV` variables are. @@ -1935,6 +2043,14 @@ required such as `zsh`, `csh`, `tcsh` and others. The `SHELL` feature was added in Docker 1.12. +## External implementation features + +This feature is only available when using the [BuildKit](#buildkit) backend. + +Docker build supports experimental features like cache mounts, build secrets and +ssh forwarding that are enabled by using an external implementation of the +builder with a syntax directive. To learn about these features, [refer to the documentation in BuildKit repository](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/experimental.md). + ## Dockerfile examples Below you can see some examples of Dockerfile syntax. If you're interested in