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

Develop with Docker: remove nesting, and some restructuring 

- Remove the "Develop your apps on Docker" section, as there
  was only a single section.
- Shorten titles in the navigation: the page itself still
  has the full title. Some titles also didn't match the
  title on the page.
- Changed "Docker build enhancements for 18.09" to
  "Build images with BuildKit" to help discovery of the
  BuildKit back-end.
- Some minor (Markdown) touch-ups of the BuildKit topic.
- Moved "Create a base image" lower in the navigation,
  because it's an advanced topic that most users won't
  be using (generally, using the official base images
  from Docker Hub would be recommended).

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn 2020-03-18 14:42:34 +01:00
parent d34430b425
commit 43bba8317c
No known key found for this signature in database
GPG Key ID: 76698F39D527CE8C
2 changed files with 101 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
_data/toc.yaml
View File

@ -32,24 +32,22 @@ guides:
title: "Educational resources"
- sectiontitle: Develop with Docker
section:
- sectiontitle: Develop your apps on Docker
section:
- path: /develop/
title: App development overview
- path: /develop/dev-best-practices/
title: App development best practices
- sectiontitle: Develop images
section:
- path: /develop/develop-images/dockerfile_best-practices/
title: Best practices for writing Dockerfiles
- path: /develop/develop-images/baseimages/
title: Create a base image
- path: /develop/develop-images/build_enhancements/
title: Docker build enhancements for 18.09
- path: /develop/develop-images/multistage-build/
title: Use multi-stage builds
- path: /develop/develop-images/image_management/
title: Manage images
- path: /develop/
title: Overview
- path: /develop/dev-best-practices/
title: Best practices
- sectiontitle: Build images
section:
- path: /develop/develop-images/dockerfile_best-practices/
title: Dockerfile best practices
- path: /develop/develop-images/build_enhancements/
title: Build images with BuildKit
- path: /develop/develop-images/multistage-build/
title: Use multi-stage builds
- path: /develop/develop-images/image_management/
title: Manage images
- path: /develop/develop-images/baseimages/
title: Create your own base image (advanced)
- sectiontitle: Configure networking
section:
- path: /network/

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

@ -1,50 +1,61 @@
---
title: Build Enhancements for Docker
description: Learn the new features of Docker Build
keywords: build, security, engine, secret, buildkit
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 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 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 and DTR 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
* 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/).
For more information on build options, see the reference guide on the
[command line build options](/engine/reference/commandline/build/).
## Requirements
* System requirements are docker-ce x86_64, ppc64le, s390x, aarch64, armhf; or docker-ee x86_64 only
* System requirements are docker-ce x86_64, ppc64le, s390x, aarch64, armhf; or
docker-ee x86_64 only
* Network connection required for downloading images of custom frontends
## Limitations
* Only supported for building Linux containers
* BuildKit mode is compatible with UCP 3.2 or newer
* BuildKit mode is incompatible with Swarm Classic
## To enable buildkit builds
## 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:
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:
```
```bash
$ 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:
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
@ -71,7 +82,8 @@ $ docker build .
```
New docker build BuildKit plain output:
```
```console
$ docker build --progress=plain .
#1 [internal] load .dockerignore
@ -100,39 +112,55 @@ $ docker build --progress=plain .
## 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:
```
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.0-experimental
```
## 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.
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.
`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.
`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.0-experimental`, the secret can be accessed.
And with a Dockerfile that specifies use of a BuildKit frontend
`docker/dockerfile:1.0-experimental`, the secret can be accessed.
For example:
```
```dockerfile
# syntax = docker/dockerfile:1.0-experimental
FROM alpine
RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret # shows secret from default secret location
RUN --mount=type=secret,id=mysecret,dst=/foobar cat /foobar # shows secret from custom secret location
# 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
```
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:
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
@ -160,14 +188,17 @@ $ docker build --no-cache --progress=plain --secret id=mysecret,src=mysecret.txt
> 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.
The `docker build` has a `--ssh` option to allow the Docker Engine to forward SSH agent connections. For more information
on SSH agent, see the [OpenSSH man page](https://man.openbsd.org/ssh-agent).
The `docker build` has a `--ssh` option to allow the Docker Engine to forward
SSH agent connections. For more information on SSH agent, see the
[OpenSSH man page](https://man.openbsd.org/ssh-agent).
Only the commands in the `Dockerfile` that have explicitly requested the SSH access by defining `type=ssh` mount have
access to SSH agent connections. The other commands have no knowledge of any SSH agent being available.
Only the commands in the `Dockerfile` that have explicitly requested the SSH
access by defining `type=ssh` mount have access to SSH agent connections. The
other commands have no knowledge of any SSH agent being available.
To request SSH access for a `RUN` command in the `Dockerfile`, define a mount with type `ssh`. This will set up the
`SSH_AUTH_SOCK` environment variable to make programs relying on SSH automatically use that socket.
To request SSH access for a `RUN` command in the `Dockerfile`, define a mount
with type `ssh`. This will set up the `SSH_AUTH_SOCK` environment variable to
make programs relying on SSH automatically use that socket.
Here is an example Dockerfile using SSH in the container:
@ -185,7 +216,8 @@ RUN mkdir -p -m 0600 ~/.ssh && ssh-keyscan github.com >> ~/.ssh/known_hosts
RUN --mount=type=ssh git clone git@github.com:myorg/myproject.git myproject
```
Once the `Dockerfile` is created, use the `--ssh` option for connectivity with the SSH agent.
Once the `Dockerfile` is created, use the `--ssh` option for connectivity with
the SSH agent.
```bash
$ docker build --ssh default .
@ -194,8 +226,12 @@ $ docker build --ssh default .
## 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 :
```
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
@ -207,13 +243,17 @@ If you are fetching images from insecure registry (with self-signed certificates
------
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 https://docs.docker.com/registry/deploying/
Solution : secure your registry properly. You can get SSL certificates from
Let's Encrypt for free. See /registry/deploying/
#### 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 :
```
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:
------
@ -222,7 +262,7 @@ If you are running a private registry using Sonatype Nexus version < 3.15, and r
------
rpc error: code = Unknown desc = docker.io/library/maven:3.5.3-alpine not found
```
you may be facing the bug below : https://issues.sonatype.org/browse/NEXUS-12684
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.