diff --git a/_data/toc.yaml b/_data/toc.yaml index 7edfe6aef4..dd03e05676 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -1685,12 +1685,16 @@ manuals: title: SLSA definitions - path: /build/attestations/attestation-storage/ title: Attestation storage + - sectiontitle: Dockerfile + section: + - path: /build/dockerfile/frontend/ + title: Custom Dockerfile syntax + - path: /build/dockerfile/release-notes/ + title: Release notes - sectiontitle: BuildKit section: - path: /build/buildkit/ title: Overview - - path: /build/buildkit/dockerfile-frontend/ - title: Custom Dockerfile syntax - path: /build/buildkit/configure/ title: Configure - path: /build/buildkit/toml-configuration/ diff --git a/_includes/dockerfile-labs-channel.md b/_includes/dockerfile-labs-channel.md new file mode 100644 index 0000000000..df9686341b --- /dev/null +++ b/_includes/dockerfile-labs-channel.md @@ -0,0 +1,5 @@ +> Experimental +> +> The "labs" channel provides early access to Dockerfile features that are not +> yet available in the stable channel. +{: .experimental } diff --git a/build/building/packaging.md b/build/building/packaging.md index e39cbc19b5..36584d2577 100644 --- a/build/building/packaging.md +++ b/build/building/packaging.md @@ -98,8 +98,8 @@ CMD flask run --host 0.0.0.0 --port 8000 The first line to add to a Dockerfile is a [`# syntax` parser directive](../../engine/reference/builder.md#syntax). While optional, this directive instructs the Docker builder what syntax to use when parsing the Dockerfile, and allows older Docker versions with [BuildKit enabled](../buildkit/index.md#getting-started) -to use a specific [Dockerfile frontend](../buildkit/dockerfile-frontend.md) -before starting the build. [Parser directives](../../engine/reference/builder.md/#parser-directives) +to use a specific [Dockerfile frontend](../dockerfile/frontend.md) before +starting the build. [Parser directives](../../engine/reference/builder.md/#parser-directives) must appear before any other comment, whitespace, or Dockerfile instruction in your Dockerfile, and should be the first line in Dockerfiles. diff --git a/build/buildkit/index.md b/build/buildkit/index.md index 9083583412..5a75b6a95a 100644 --- a/build/buildkit/index.md +++ b/build/buildkit/index.md @@ -19,7 +19,7 @@ It also introduces support for handling more complex scenarios: [build context](../building/context.md) between builds - Detect and skip transferring unused files in your [build context](../building/context.md) -- Use [Dockerfile frontend](dockerfile-frontend.md) implementations with many +- Use [Dockerfile frontend](../dockerfile/frontend.md) implementations with many new features - Avoid side effects with rest of the API (intermediate images and containers) - Prioritize your build cache for automatic pruning @@ -70,7 +70,7 @@ work for the features used by their definition. For example, to build a [Dockerfile](../../engine/reference/builder.md) with BuildKit, you would -[use an external Dockerfile frontend](dockerfile-frontend.md). +[use an external Dockerfile frontend](../dockerfile/frontend.md). ## Getting started diff --git a/build/buildkit/dockerfile-frontend.md b/build/dockerfile/frontend.md similarity index 98% rename from build/buildkit/dockerfile-frontend.md rename to build/dockerfile/frontend.md index 17ffe7baf8..6b9e5e74e3 100644 --- a/build/buildkit/dockerfile-frontend.md +++ b/build/dockerfile/frontend.md @@ -1,6 +1,8 @@ --- title: Custom Dockerfile syntax keywords: build, buildkit, dockerfile, frontend +redirect_from: + - /build/buildkit/dockerfile-frontend/ --- ## Dockerfile frontend diff --git a/build/dockerfile/release-notes.md b/build/dockerfile/release-notes.md new file mode 100644 index 0000000000..63873c898b --- /dev/null +++ b/build/dockerfile/release-notes.md @@ -0,0 +1,254 @@ +--- +title: Dockerfile release notes +description: Release notes for Dockerfile frontend +keywords: build, dockerfile, frontend, release notes +toc_max: 2 +--- + +This page contains information about the new features, improvements, known +issues, and bug fixes in [Dockerfile reference](../../engine/reference/builder.md). + +For usage, see the [Dockerfile frontend syntax](frontend.md) page. + +## 1.5.2 + +{% include release-date.html date="2023-02-14" %} + +### Bug fixes and enhancements + +* Fix building from Git reference that is missing branch name but contains a + subdir +* 386 platform image is now included in the release + +## 1.5.1 + +{% include release-date.html date="2023-01-18" %} + +### Bug fixes and enhancements + +* Fix possible panic when warning conditions appear in multi-platform builds + +## 1.5.0 (labs) + +{% include release-date.html date="2023-01-10" %} + +{% include dockerfile-labs-channel.md %} + +### New + +* `ADD` command now supports [`--checksum` flag](../../engine/reference/builder.md#verifying-a-remote-file-checksum-add---checksumchecksum-http-src-dest) + to validate the contents of the remote URL contents + +## 1.5.0 + +{% include release-date.html date="2023-01-10" %} + +### New + +* `ADD` command can now [import files directly from Git URLs](../../engine/reference/builder.md#adding-a-git-repository-add-git-ref-dir) + +### Bug fixes and enhancements + +* Named contexts now support `oci-layout://` protocol for including images from + local OCI layout structure +* Dockerfile now supports secondary requests for listing all build targets or + printing outline of accepted parameters for a specific build target +* Dockerfile `#syntax` directive that redirects to an external frontend image + now allows the directive to be also set with `//` comments or JSON. The file + may also contain a shebang header +* Named context can now be initialized with an empty scratch image +* Named contexts can now be initialized with an SSH Git URL +* Fix handling of `ONBUILD` when importing Schema1 images + +## 1.4.3 + +{% include release-date.html date="2022-08-23" %} + +### Bug fixes and enhancements + +* Fix creation timestamp not getting reset when building image from + `docker-image://` named context +* Fix passing `--platform` flag of `FROM` command when loading + `docker-image://` named context + +## 1.4.2 + +{% include release-date.html date="2022-05-06" %} + +### Bug fixes and enhancements + +* Fix loading certain environment variables from an image passed with built + context + +## 1.4.1 + +{% include release-date.html date="2022-04-08" %} + +### Bug fixes and enhancements + +* Fix named context resolution for cross-compilation cases from input when input + is built for a different platform + +## 1.4.0 + +{% include release-date.html date="2022-03-09" %} + +### New + +* [`COPY --link` and `ADD --link`](../../engine/reference/builder.md#copy---link) + allow copying files with increased cache efficiency and rebase images without + requiring them to be rebuilt. `--link` copies files to a separate layer and + then uses new LLB MergeOp implementation to chain independent layers together +* [Heredocs](../../engine/reference/builder.md#here-documents) support have + been promoted from labs channel to stable. This feature allows writing + multiline inline scripts and files +* Additional [named build contexts](../../engine/reference/commandline/buildx_build.md#build-context) + can be passed to build to add or overwrite a stage or an image inside the + build. A source for the context can be a local source, image, Git, or HTTP URL +* [`BUILDKIT_SANDBOX_HOSTNAME` build-arg](../../engine/reference/builder.md#buildkit-built-in-build-args) + can be used to set the default hostname for the `RUN` steps + +### Bug fixes and enhancements + +* When using a cross-compilation stage, the target platform for a step is now + seen on progress output +* Fix some cases where Heredocs incorrectly removed quotes from content + +## 1.3.1 + +{% include release-date.html date="2021-10-04" %} + +### Bug fixes and enhancements + +* Fix parsing "required" mount key without a value + +## 1.3.0 (labs) + +{% include release-date.html date="2021-07-16" %} + +{% include dockerfile-labs-channel.md %} + +### New + +* `RUN` and `COPY` commands now support [Here-document syntax](../../engine/reference/builder.md#here-documents) + allowing writing multiline inline scripts and files + +## 1.3.0 + +{% include release-date.html date="2021-07-16" %} + +### New + +* `RUN` command allows [`--network` flag](../../engine/reference/builder.md#run---network) + for requesting a specific type of network conditions. `--network=host` + requires allowing `network.host` entitlement. This feature was previously + only available on labs channel + +### Bug fixes and enhancements + +* `ADD` command with a remote URL input now correctly handles the `--chmod` flag +* Values for [`RUN --mount` flag](../../engine/reference/builder.md#run---mount) + now support variable expansion, except for the `from` field +* Allow [`BUILDKIT_MULTI_PLATFORM` build arg](../../engine/reference/builder.md#buildkit-built-in-build-args) + to force always creating multi-platform image, even if only contains single + platform + +## 1.2.1 (labs) + +{% include release-date.html date="2020-12-12" %} + +{% include dockerfile-labs-channel.md %} + +### Bug fixes and enhancements + +* `RUN` command allows [`--network` flag](../../engine/reference/builder.md#run---network) + for requesting a specific type of network conditions. `--network=host` + requires allowing `network.host` entitlement + +## 1.2.1 + +{% include release-date.html date="2020-12-12" %} + +### Bug fixes and enhancements + +* Revert "Ensure ENTRYPOINT command has at least one argument" +* Optimize processing `COPY` calls on multi-platform cross-compilation builds + +## 1.2.0 (labs) + +{% include release-date.html date="2020-12-03" %} + +{% include dockerfile-labs-channel.md %} + +### Bug fixes and enhancements + +* Experimental channel has been renamed to *labs* + +## 1.2.0 + +{% include release-date.html date="2020-12-03" %} + +### New + +* [`RUN --mount` syntax](../../engine/reference/builder.md#run---mount) for + creating secret, ssh, bind, and cache mounts have been moved to mainline + channel +* [`ARG` command](../../engine/reference/builder.md#arg) now supports defining + multiple build args on the same line similarly to `ENV` + +### Bug fixes and enhancements + +* Metadata load errors are now handled as fatal to avoid incorrect build results +* Allow lowercase Dockerfile name +* `--chown` flag in `ADD` now allows parameter expansion +* `ENTRYPOINT` requires at least one argument to avoid creating broken images + +## 1.1.7 + +{% include release-date.html date="2020-04-18" %} + +### Bug fixes and enhancements + +* Forward `FrontendInputs` to the gateway + +## 1.1.2 (experimental) + +{% include release-date.html date="2019-07-31" %} + +{% include dockerfile-labs-channel.md %} + +### Bug fixes and enhancements + +* Allow setting security mode for a process with `RUN --security=sandbox|insecure` +* Allow setting uid/gid for [cache mounts](../../engine/reference/builder.md#run---mounttypecache) +* Avoid requesting internally linked paths to be pulled to build context +* Ensure missing cache IDs default to target paths +* Allow setting namespace for cache mounts with [`BUILDKIT_CACHE_MOUNT_NS` build arg](../../engine/reference/builder.md#buildkit-built-in-build-args) + +## 1.1.2 + +{% include release-date.html date="2019-07-31" %} + +### Bug fixes and enhancements + +* Fix workdir creation with correct user and don't reset custom ownership +* Fix handling empty build args also used as `ENV` +* Detect circular dependencies + +## 1.1.0 + +{% include release-date.html date="2019-04-27" %} + +### New + +* `ADD/COPY` commands now support implementation based on `llb.FileOp` and do + not require helper image if builtin file operations support is available +* `--chown` flag for `COPY` command now supports variable expansion + +### Bug fixes and enhancements + +* To find the files ignored from the build context Dockerfile frontend will + first look for a file `.dockerignore` and if it is not + found `.dockerignore` file will be looked up from the root of the build + context. This allows projects with multiple Dockerfiles to use different + `.dockerignore` definitions diff --git a/build/index.md b/build/index.md index 47f4fc4a13..950931f9ca 100644 --- a/build/index.md +++ b/build/index.md @@ -153,11 +153,11 @@ advanced scenarios.
-

Dockerfile frontend

+

Dockerfile frontend

Learn about the Dockerfile frontend for BuildKit.