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

docs/reference/builder: update "syntax" section 

- rename "experimental" to "labs"
- rephrase recommendation for picking a version
- clarify that the "labs" channel provides a superset of the "stable" channel.
- remove "External implementation features" section, because it overlapped
  with the "syntax" section.
- removed `:latest` from the "stable" channel (generally not recommended)

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn 2021-04-21 22:36:16 +02:00
parent 17a9eb60e3
commit 30359cbdb7
No known key found for this signature in database
GPG Key ID: 76698F39D527CE8C
1 changed files with 51 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
docs/reference/builder.md
View File

@ -128,10 +128,10 @@ $ docker build -t svendowideit/ambassador .
=> exporting to image 0.0s => exporting to image 0.0s
=> => exporting layers 0.0s => => exporting layers 0.0s
=> => writing image sha256:1affb80ca37018ac12067fa2af38cc5bcc2a8f09963de 0.0s => => writing image sha256:1affb80ca37018ac12067fa2af38cc5bcc2a8f09963de 0.0s
=> => naming to docker.io/library/mysocatimage 0.0s => => naming to docker.io/svendowideit/ambassador 0.0s
``` ```
By default, the build cache is based results from previous builds on the machine By default, the build cache is based on results from previous builds on the machine
on which you are building. The `--cache-from` option also allows you to use a on which you are building. The `--cache-from` option also allows you to use a
build-cache that's distributed through an image registry refer to the build-cache that's distributed through an image registry refer to the
[specifying external cache sources](commandline/build.md#specifying-external-cache-sources) [specifying external cache sources](commandline/build.md#specifying-external-cache-sources)
@ -318,6 +318,8 @@ The following parser directives are supported:
## syntax ## syntax
<a name="external-implementation-features"><!-- included for deep-links to old section --></a>
```dockerfile ```dockerfile
# syntax=[remote image reference] # syntax=[remote image reference]
``` ```
@ -325,55 +327,73 @@ The following parser directives are supported:
For example: For example:
```dockerfile ```dockerfile
# syntax=docker/dockerfile # syntax=docker/dockerfile:1
# syntax=docker/dockerfile:1.0
# syntax=docker.io/docker/dockerfile:1 # syntax=docker.io/docker/dockerfile:1
# syntax=docker/dockerfile:1.0.0-experimental
# syntax=example.com/user/repo:tag@sha256:abcdef... # syntax=example.com/user/repo:tag@sha256:abcdef...
``` ```
This feature is only enabled if the [BuildKit](#buildkit) backend is used. This feature is only available when using the [BuildKit](#buildkit) backend, and
is ignored when using the classic builder backend.
The syntax directive defines the location of the Dockerfile builder that is used for The syntax directive defines the location of the Dockerfile syntax that is used
building the current Dockerfile. The BuildKit backend allows to seamlessly use to build the Dockerfile. The BuildKit backend allows to seamlessly use external
external implementations of builders that are distributed as Docker images and implementations that are distributed as Docker images and execute inside a
execute inside a container sandbox environment. container sandbox environment.
Custom Dockerfile implementation allows you to: Custom Dockerfile implementations allows you to:
- Automatically get bugfixes without updating the daemon - Automatically get bugfixes without updating the Docker daemon
- Make sure all users are using the same implementation to build your Dockerfile - Make sure all users are using the same implementation to build your Dockerfile
- Use the latest features without updating the daemon - Use the latest features without updating the Docker daemon
- Try out new experimental or third-party features - Try out new features or third-party features before they are integrated in the Docker daemon
- Use [alternative build definitions, or create your own](https://github.com/moby/buildkit#exploring-llb)
### Official releases ### Official releases
Docker distributes official versions of the images that can be used for building Docker distributes official versions of the images that can be used for building
Dockerfiles under `docker/dockerfile` repository on Docker Hub. There are two Dockerfiles under `docker/dockerfile` repository on Docker Hub. There are two
channels where new images are released: stable and experimental. channels where new images are released: `stable` and `labs`.
Stable channel follows semantic versioning. For example: Stable channel follows [semantic versioning](https://semver.org). For example:
- `docker/dockerfile:1.0.0` - only allow immutable version `1.0.0` - `docker/dockerfile:1` - kept updated with the latest `1.x.x` minor _and_ patch release
- `docker/dockerfile:1.0` - allow versions `1.0.*` - `docker/dockerfile:1.2` - kept updated with the latest `1.2.x` patch release,
- `docker/dockerfile:1` - allow versions `1.*.*` and stops receiving updates once version `1.3.0` is released.
- `docker/dockerfile:latest` - latest release on stable channel - `docker/dockerfile:1.2.1` - immutable: never updated
The experimental channel uses incremental versioning with the major and minor We recommend using `docker/dockerfile:1`, which always points to the latest stable
component from the stable channel on the time of the release. For example: release of the version 1 syntax, and receives both "minor" and "patch" updates
for the version 1 release cycle. BuildKit automatically checks for updates of the
syntax when performing a build, making sure you are using the most current version.
- `docker/dockerfile:1.0.1-experimental` - only allow immutable version `1.0.1-experimental` If a specific version is used, such as `1.2` or `1.2.1`, the Dockerfile needs to
- `docker/dockerfile:1.0-experimental` - latest experimental releases after `1.0` be updated manually to continue receiving bugfixes and new features. Old versions
- `docker/dockerfile:experimental` - latest release on experimental channel of the Dockerfile remain compatible with the new versions of the builder.
You should choose a channel that best fits your needs. If you only want **labs channel**
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 "labs" channel provides early access to Dockerfile features that are not yet
the experimental channel, newer releases may not be backwards compatible, so it available in the stable channel. Labs channel images are released in conjunction
with the stable releases, and follow the same versioning with the `-labs` suffix,
for example:
- `docker/dockerfile:labs` - latest release on labs channel
- `docker/dockerfile:1-labs` - same as `dockerfile:1` in the stable channel, with labs features enabled
- `docker/dockerfile:1.2-labs` - same as `dockerfile:1.2` in the stable channel, with labs features enabled
- `docker/dockerfile:1.2.1-labs` - immutable: never updated. Same as `dockerfile:1.2.1` in the stable channel, with labs features enabled
Choose a channel that best fits your needs; if you want to benefit from
new features, use the labs channel. Images in the labs channel provide a superset
of the features in the stable channel; note that `stable` features in the labs
channel images follow [semantic versioning](https://semver.org), but "labs"
features do not, and newer releases may not be backwards compatible, so it
is recommended to use an immutable full version variant. is recommended to use an immutable full version variant.
For master builds and nightly feature releases refer to the description in For documentation on "labs" features, master builds, and nightly feature releases,
[the source repository](https://github.com/moby/buildkit/blob/master/README.md). refer to the description in [the BuildKit source repository on GitHub](https://github.com/moby/buildkit/blob/master/README.md).
For a full list of available images, visit the [image repository on Docker Hub](https://hub.docker.com/r/docker/dockerfile),
and the [docker/dockerfile-upstream image repository](https://hub.docker.com/r/docker/dockerfile-upstream)
for development builds.
## escape ## escape
@ -2347,15 +2367,6 @@ environment variable expansion semantics could be modified.
The `SHELL` instruction can also be used on Linux should an alternate shell be The `SHELL` instruction can also be used on Linux should an alternate shell be
required such as `zsh`, `csh`, `tcsh` and others. required such as `zsh`, `csh`, `tcsh` and others.
## 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 ## Dockerfile examples
For examples of Dockerfiles, refer to: For examples of Dockerfiles, refer to: