docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

build: merge build enhancements page in build section 

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>
This commit is contained in:
CrazyMax 2022-10-24 21:12:12 +02:00
parent 71a537d3da
commit 271f8c3de5
No known key found for this signature in database
GPG Key ID: 3248E46B6BB8C7F7
13 changed files with 63 additions and 336 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
_data/toc.yaml
View File

@ -125,8 +125,6 @@ guides:
section: section:
- path: /develop/develop-images/dockerfile_best-practices/ - path: /develop/develop-images/dockerfile_best-practices/
title: Dockerfile best practices title: Dockerfile best practices
- path: /develop/develop-images/build_enhancements/
title: Build images with BuildKit
- path: /develop/develop-images/image_management/ - path: /develop/develop-images/image_management/
title: Manage images title: Manage images
- path: /develop/develop-images/baseimages/ - path: /develop/develop-images/baseimages/

30
_includes/guides/enable-buildkit.md
View File

@ -1,30 +0,0 @@
<!-- This text will be included in Build images topic in the Get started guides -->
### Enable BuildKit
Before we start building images, ensure you have enabled BuildKit on your machine.
BuildKit allows you to build Docker images efficiently. For more information,
see [Building images with BuildKit](/develop/develop-images/build_enhancements/).
BuildKit is enabled by default for all users on Docker Desktop. If you have
installed Docker Desktop, you don't have to manually enable BuildKit. If you are
running Docker on Linux, you can enable BuildKit either by using an environment
variable or by making BuildKit the default setting.
To set the BuildKit environment variable when running the `docker build` command,
run:
```console
$ DOCKER_BUILDKIT=1 docker build .
```
To enable docker BuildKit by default, set daemon configuration in `/etc/docker/daemon.json` feature to `true` and restart the daemon.
If the `daemon.json` file doesn't exist, create new file called `daemon.json` and then add the following to the file.
```json
{
"features":{"buildkit" : true}
}
```
Restart the Docker daemon.

47
build/buildkit/index.md
View File

@ -56,10 +56,49 @@ a prepared set of build steps.
## Frontend ## Frontend
A frontend is a component that takes a human-readable A frontend is a component that takes a human-readable build format and converts
build format and converts it to LLB so BuildKit can execute it. Frontends can it to LLB so BuildKit can execute it. Frontends can be distributed as images,
be distributed as images, and the user can target a specific version of a and the user can target a specific version of a frontend that is guaranteed to
frontend that is guaranteed to work for the features used by their definition. work for the features used by their definition.
For example, to build a [Dockerfile](../../engine/reference/builder.md) with For example, to build a [Dockerfile](../../engine/reference/builder.md) with
BuildKit, you would [use an external Dockerfile frontend](dockerfile-frontend.md). BuildKit, you would [use an external Dockerfile frontend](dockerfile-frontend.md).
## Getting started
BuildKit is enabled by default for all users on [Docker Desktop](../../desktop/index.md).
If you have installed Docker Desktop, you don't have to manually enable
BuildKit. If you are running Docker on Linux, you can enable BuildKit either by
using an environment variable or by making BuildKit the default setting.
To set the BuildKit environment variable when running the `docker build`
command, run:
```console
$ DOCKER_BUILDKIT=1 docker build .
```
>**Note**
>
> Buildx always enables BuildKit.
To enable docker BuildKit by default, set daemon configuration in `/etc/docker/daemon.json`
feature to `true` and restart the daemon. If the `daemon.json` file doesn't
exist, create new file called `daemon.json` and then add the following to the
file.
```json
{
"features": {
"buildkit" : true
}
}
```
And restart the Docker daemon.
> **Warning**
>
> BuildKit only supports building Linux containers. Windows support is tracked
> in [`moby/buildkit#616`](https://github.com/moby/buildkit/issues/616){:target="_blank" rel="noopener" class="_"}
{: .warning}

1
build/index.md
View File

@ -5,6 +5,7 @@ keywords: build, buildx, buildkit
redirect_from: redirect_from:
- /build/buildx/ - /build/buildx/
- /buildx/working-with-buildx/ - /buildx/working-with-buildx/
- /develop/develop-images/build_enhancements/
--- ---
## Overview ## Overview

4
desktop/faqs/general.md
View File

@ -56,8 +56,8 @@ This includes:
- [Vulnerability scanning](../../docker-hub/vulnerability-scanning.md) - [Vulnerability scanning](../../docker-hub/vulnerability-scanning.md)
- Viewing remote images in the Docker Dashboard - Viewing remote images in the Docker Dashboard
- Settting up [Dev Environments](../dev-environments/index.md) - Settting up [Dev Environments](../dev-environments/index.md)
- Docker build when using [Buildkit](../../develop/develop-images/build_enhancements.md). You can work around this by disabling - Docker build when using [BuildKit](../../build/buildkit/index.md#getting-started).
BuildKit. Run `DOCKER_BUILDKIT=0 docker build .` to disable BuildKit. You can work around this by disabling BuildKit. Run `DOCKER_BUILDKIT=0 docker build .` to disable BuildKit.
- Deploying an app to the cloud through Compose - Deploying an app to the cloud through Compose
[ACI](../../cloud/aci-integration.md) and [ECS](../../cloud/ecs-integration.md) [ACI](../../cloud/aci-integration.md) and [ECS](../../cloud/ecs-integration.md)
integrations integrations

284
develop/develop-images/build_enhancements.md
View File

@ -1,284 +0,0 @@
---
title: Build images with BuildKit
description: Learn the new features of Docker Build with BuildKit
keywords: build, security, engine, secret, BuildKit
---
Docker Build is one of the most used features of the Docker Engine - users
ranging from developers, build teams, and release teams all use Docker Build.
Docker Build enhancements for 18.09 release introduces a much-needed overhaul of
the build architecture. By integrating BuildKit, users should see an improvement
on performance, storage management, feature functionality, and security.
* Docker images created with BuildKit can be pushed to Docker Hub just like
Docker images created with legacy build
* the Dockerfile format that works on legacy build will also work with BuildKit
builds
* The new `--secret` command line option allows the user to pass secret
information for building new images with a specified Dockerfile
For more information on build options, see the reference guide on the
[command line build options](../../engine/reference/commandline/build.md) and
the [Dockerfile reference](/engine/reference/builder/) page.
## Requirements
* A current version of Docker (18.09 or higher)
* Network connection required for downloading images of custom frontends
## Limitations
* Only supported for building Linux containers
## To enable BuildKit builds
Easiest way from a fresh install of docker is to set the `DOCKER_BUILDKIT=1`
environment variable when invoking the `docker build` command, such as:
```console
$ DOCKER_BUILDKIT=1 docker build .
```
To enable docker BuildKit by default, set daemon configuration in
`/etc/docker/daemon.json` feature to true and restart the daemon:
```json
{ "features": { "buildkit": true } }
```
## New Docker Build command line build output
New docker build BuildKit TTY output (default):
```console
$ docker build .
[+] Building 70.9s (34/59)
=> [runc 1/4] COPY hack/dockerfile/install/install.sh ./install.sh 14.0s
=> [frozen-images 3/4] RUN /download-frozen-image-v2.sh /build buildpa 24.9s
=> [containerd 4/5] RUN PREFIX=/build/ ./install.sh containerd 37.1s
=> [tini 2/5] COPY hack/dockerfile/install/install.sh ./install.sh 4.9s
=> [vndr 2/4] COPY hack/dockerfile/install/vndr.installer ./ 1.6s
=> [dockercli 2/4] COPY hack/dockerfile/install/dockercli.installer ./ 5.9s
=> [proxy 2/4] COPY hack/dockerfile/install/proxy.installer ./ 15.7s
=> [tomlv 2/4] COPY hack/dockerfile/install/tomlv.installer ./ 12.4s
=> [gometalinter 2/4] COPY hack/dockerfile/install/gometalinter.install 25.5s
=> [vndr 3/4] RUN PREFIX=/build/ ./install.sh vndr 33.2s
=> [tini 3/5] COPY hack/dockerfile/install/tini.installer ./ 6.1s
=> [dockercli 3/4] RUN PREFIX=/build/ ./install.sh dockercli 18.0s
=> [runc 2/4] COPY hack/dockerfile/install/runc.installer ./ 2.4s
=> [tini 4/5] RUN PREFIX=/build/ ./install.sh tini 11.6s
=> [runc 3/4] RUN PREFIX=/build/ ./install.sh runc 23.4s
=> [tomlv 3/4] RUN PREFIX=/build/ ./install.sh tomlv 9.7s
=> [proxy 3/4] RUN PREFIX=/build/ ./install.sh proxy 14.6s
=> [dev 2/23] RUN useradd --create-home --gid docker unprivilegeduser 5.1s
=> [gometalinter 3/4] RUN PREFIX=/build/ ./install.sh gometalinter 9.4s
=> [dev 3/23] RUN ln -sfv /go/src/github.com/docker/docker/.bashrc ~/.ba 4.3s
=> [dev 4/23] RUN echo source /usr/share/bash-completion/bash_completion 2.5s
=> [dev 5/23] RUN ln -s /usr/local/completion/bash/docker /etc/bash_comp 2.1s
```
New docker build BuildKit plain output:
```console
$ docker build --progress=plain .
#1 [internal] load .dockerignore
#1 digest: sha256:d0b5f1b2d994bfdacee98198b07119b61cf2442e548a41cf4cd6d0471a627414
#1 name: "[internal] load .dockerignore"
#1 started: 2018-08-31 19:07:09.246319297 +0000 UTC
#1 completed: 2018-08-31 19:07:09.246386115 +0000 UTC
#1 duration: 66.818µs
#1 started: 2018-08-31 19:07:09.246547272 +0000 UTC
#1 completed: 2018-08-31 19:07:09.260979324 +0000 UTC
#1 duration: 14.432052ms
#1 transferring context: 142B done
#2 [internal] load Dockerfile
#2 digest: sha256:2f10ef7338b6eebaf1b072752d0d936c3d38c4383476a3985824ff70398569fa
#2 name: "[internal] load Dockerfile"
#2 started: 2018-08-31 19:07:09.246331352 +0000 UTC
#2 completed: 2018-08-31 19:07:09.246386021 +0000 UTC
#2 duration: 54.669µs
#2 started: 2018-08-31 19:07:09.246720773 +0000 UTC
#2 completed: 2018-08-31 19:07:09.270231987 +0000 UTC
#2 duration: 23.511214ms
#2 transferring dockerfile: 9.26kB done
```
## Overriding default frontends
The new syntax features in `Dockerfile` are available if you override the default
frontend. To override the default frontend, set the first line of the
`Dockerfile` as a comment with a specific frontend image:
```dockerfile
# syntax=<frontend image>, e.g. # syntax=docker/dockerfile:1.2
```
The examples on this page use features that are available in `docker/dockerfile`
version 1.2.0 and up. We recommend using `docker/dockerfile:1`, which always
points to the latest release of the version 1 syntax. BuildKit automatically
checks for updates of the syntax before building, making sure you are using the
most current version. Learn more about the `syntax` directive in the
[Dockerfile reference](/engine/reference/builder/#syntax).
## New Docker Build secret information
The new `--secret` flag for docker build allows the user to pass secret
information to be used in the Dockerfile for building docker images in a safe
way that will not end up stored in the final image.
`id` is the identifier to pass into the `docker build --secret`. This identifier
is associated with the `RUN --mount` identifier to use in the Dockerfile. Docker
does not use the filename of where the secret is kept outside of the Dockerfile,
since this may be sensitive information.
`dst` renames the secret file to a specific file in the Dockerfile `RUN` command
to use.
For example, with a secret piece of information stored in a text file:
```console
$ echo 'WARMACHINEROX' > mysecret.txt
```
And with a Dockerfile that specifies use of a BuildKit frontend
`docker/dockerfile:1.2`, the secret can be accessed when performing a `RUN`:
```dockerfile
# syntax=docker/dockerfile:1.2
FROM alpine
# shows secret from default secret location:
RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret
# shows secret from custom secret location:
RUN --mount=type=secret,id=mysecret,dst=/foobar cat /foobar
```
The secret needs to be passed to the build using the `--secret` flag.
This Dockerfile is only to demonstrate that the secret can be accessed. As you
can see the secret printed in the build output. The final image built will not
have the secret file:
```console
$ docker build --no-cache --progress=plain --secret id=mysecret,src=mysecret.txt .
...
#8 [2/3] RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret
#8 digest: sha256:5d8cbaeb66183993700828632bfbde246cae8feded11aad40e524f54ce7438d6
#8 name: "[2/3] RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret"
#8 started: 2018-08-31 21:03:30.703550864 +0000 UTC
#8 1.081 WARMACHINEROX
#8 completed: 2018-08-31 21:03:32.051053831 +0000 UTC
#8 duration: 1.347502967s
#9 [3/3] RUN --mount=type=secret,id=mysecret,dst=/foobar cat /foobar
#9 digest: sha256:6c7ebda4599ec6acb40358017e51ccb4c5471dc434573b9b7188143757459efa
#9 name: "[3/3] RUN --mount=type=secret,id=mysecret,dst=/foobar cat /foobar"
#9 started: 2018-08-31 21:03:32.052880985 +0000 UTC
#9 1.216 WARMACHINEROX
#9 completed: 2018-08-31 21:03:33.523282118 +0000 UTC
#9 duration: 1.470401133s
...
```
## Using SSH to access private data in builds
> **Acknowledgment**
>
> Please see [Build secrets and SSH forwarding in Docker 18.09](https://medium.com/@tonistiigi/build-secrets-and-ssh-forwarding-in-docker-18-09-ae8161d066)
> for more information and examples.
Some commands in a `Dockerfile` may need specific SSH authentication - for example, to clone a private repository.
Rather than copying private keys into the image, which runs the risk of exposing them publicly, `docker build` provides a way to use the host system's ssh access while building the image.
There are three steps to this process.
First, run `ssh-add` to add private key identities to the authentication agent.
If you have more than one SSH key and your default `id_rsa` is not the one you use for accessing the resources in question, you'll need to add that key by path: `ssh-add ~/.ssh/<some other key>`.
(For more information on SSH agent, see the [OpenSSH man page](https://man.openbsd.org/ssh-agent).)
Second, when running `docker build`, use the `--ssh` option to pass in an existing SSH agent connection socket.
For example, `--ssh default=$SSH_AUTH_SOCK`, or the shorter equivalent, `--ssh default`.
Third, to make use of that SSH access in a `RUN` command in the `Dockerfile`, define a mount with type `ssh`.
This will set the `SSH_AUTH_SOCK` environment variable for that command to the value provided by the host to `docker build`, which will cause any programs in the `RUN` command which rely on SSH to automatically use that socket.
Only the commands in the `Dockerfile` that have explicitly requested SSH access by defining `type=ssh` mount will have access to SSH agent connections.
The other commands will have no knowledge of any SSH agent being available.
Here is an example `Dockerfile` using SSH in the container:
```dockerfile
# syntax=docker/dockerfile:1
FROM alpine
# Install ssh client and git
RUN apk add --no-cache openssh-client git
# Download public key for github.com
RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan github.com >> ~/.ssh/known_hosts
# Clone private repository
RUN --mount=type=ssh git clone git@github.com:myorg/myproject.git myproject
```
The image could be built as follows:
```console
$ docker build --ssh default .
```
As with `--mount=type=secret`, you can specify an `id` if you want to use multiple sockets per build and want to differentiate them.
For example, you could run `docker build --ssh main=$SSH_AUTH_SOCK --ssh other=$OTHER_SSH_AUTH_SOCK`.
In your `Dockerfile`, you could then have a `RUN --mount=type=ssh,id=main` and a `RUN --mount=type=ssh,id=other` to use those two sockets.
If a `--mount=type=ssh` doesn't specify an `id`, `default` is assumed.
## Troubleshooting : issues with private registries
#### x509: certificate signed by unknown authority
If you are fetching images from insecure registry (with self-signed certificates)
and/or using such a registry as a mirror, you are facing a known issue in
Docker 18.09 :
```console
[+] Building 0.4s (3/3) FINISHED
=> [internal] load build definition from Dockerfile
=> => transferring dockerfile: 169B
=> [internal] load .dockerignore
=> => transferring context: 2B
=> ERROR resolve image config for docker.io/docker/dockerfile:experimental
------
> resolve image config for docker.io/docker/dockerfile:experimental:
------
failed to do request: Head https://repo.mycompany.com/v2/docker/dockerfile/manifests/experimental: x509: certificate signed by unknown authority
```
Solution: secure your registry properly. You can get SSL certificates from
Let's Encrypt for free. See [Deploy a registry server](../../registry/deploying.md).
#### image not found when the private registry is running on Sonatype Nexus version < 3.15
If you are running a private registry using Sonatype Nexus version < 3.15, and
receive an error similar to the following :
```console
------
> [internal] load metadata for docker.io/library/maven:3.5.3-alpine:
------
------
> [1/4] FROM docker.io/library/maven:3.5.3-alpine:
------
rpc error: code = Unknown desc = docker.io/library/maven:3.5.3-alpine not found
```
you may be facing the bug below : [NEXUS-12684](https://issues.sonatype.org/browse/NEXUS-12684)
Solution is to upgrade your Nexus to version 3.15 or above.

2
docker-hub/builds/index.md
View File

@ -317,7 +317,7 @@ sources. For example, you might have
Autobuilds use the BuildKit build system by default. If you want to use the legacy Autobuilds use the BuildKit build system by default. If you want to use the legacy
Docker build system, add the [environment variable](index.md#environment-variables-for-builds){: target="_blank" rel="noopener" class="_"} Docker build system, add the [environment variable](index.md#environment-variables-for-builds){: target="_blank" rel="noopener" class="_"}
`DOCKER_BUILDKIT=0`. Refer to the [build images with BuildKit](../../develop/develop-images/build_enhancements.md) `DOCKER_BUILDKIT=0`. Refer to the [BuildKit](../../build/buildkit/index.md)
page for more information on BuildKit. page for more information on BuildKit.
## Build repositories with linked private submodules ## Build repositories with linked private submodules

4
go/buildkit.md
View File

@ -1,6 +1,6 @@
--- ---
title: How to enable BuildKit title: How to enable BuildKit
description: Instructions on enabling BuildKit description: Instructions on enabling BuildKit
keywords: BuildKit, docker build, configuration keywords: build, buildkit, configuration
redirect_to: /develop/develop-images/build_enhancements/#to-enable-buildkit-builds redirect_to: /build/buildkit/#getting-started
--- ---

2
language/index.md
View File

@ -14,7 +14,7 @@ For more information, refer to the following topics:
* [Best practices for writing Dockerfiles](../develop/develop-images/dockerfile_best-practices.md) * [Best practices for writing Dockerfiles](../develop/develop-images/dockerfile_best-practices.md)
* [Docker development best practices](../develop/dev-best-practices.md) * [Docker development best practices](../develop/dev-best-practices.md)
* [Build images with BuildKit](../develop/develop-images/build_enhancements.md) * [Build images with BuildKit](../build/buildkit/index.md#getting-started)
* [Manage images](../develop/develop-images/image_management.md) * [Manage images](../develop/develop-images/image_management.md)
## Language-specific getting started guides ## Language-specific getting started guides

7
language/java/build-images.md
View File

@ -8,9 +8,10 @@ description: Learn how to build your first Docker image by writing a Dockerfile
## Prerequisites ## Prerequisites
Work through the orientation and setup in Get started [Part 1](../../get-started/index.md){:target="_blank" rel="noopener" class="_"} to understand Docker concepts. Refer to the following section for Java prerequisites. * Some awareness of basic Docker concepts. If unsure, work through the orientation
and setup in Get started [Part 1](../../get-started/index.md).
{% include guides/enable-buildkit.md %} * Ensure you have [enabled BuildKit](../../build/buildkit/index.md#getting-started)
on your machine.
## Overview ## Overview

7
language/nodejs/build-images.md
View File

@ -10,9 +10,10 @@ redirect_from:
## Prerequisites ## Prerequisites
Work through the orientation and setup in Get started [Part 1](../../get-started/index.md) to understand Docker concepts. * Some awareness of basic Docker concepts. If unsure, work through the orientation
and setup in Get started [Part 1](../../get-started/index.md).
{% include guides/enable-buildkit.md %} * Ensure you have [enabled BuildKit](../../build/buildkit/index.md#getting-started)
on your machine.
## Overview ## Overview

7
language/python/build-images.md
View File

@ -8,9 +8,10 @@ description: Learn how to build your first Docker image by writing a Dockerfile
## Prerequisites ## Prerequisites
Work through the orientation and setup in Get started [Part 1](../../get-started/index.md) to understand Docker concepts. * Some awareness of basic Docker concepts. If unsure, work through the orientation
and setup in Get started [Part 1](../../get-started/index.md).
{% include guides/enable-buildkit.md %} * Ensure you have [enabled BuildKit](../../build/buildkit/index.md#getting-started)
on your machine.
## Overview ## Overview

2
storage/storagedriver/index.md
View File

@ -328,7 +328,7 @@ layers are the same.
> image for each step for caching purposes, and the `IMAGE` column would show > image for each step for caching purposes, and the `IMAGE` column would show
> the ID of that image. > the ID of that image.
> BuildKit uses its own caching mechanism, and no longer requires intermediate > BuildKit uses its own caching mechanism, and no longer requires intermediate
> images for caching. Refer to [build images with BuildKit](../../develop/develop-images/build_enhancements.md) > images for caching. Refer to [BuildKit](../../build/buildkit/index.md)
> to learn more about other enhancements made in BuildKit. > to learn more about other enhancements made in BuildKit.