docker/buildx
1
0
Fork 0
mirror of https://gitea.com/Lydanne/buildx.git synced 2025-07-12 22:47:09 +08:00
Code Issues Packages Projects Releases 1 Wiki Activity

docs: additions from editorial review

Browse Source 
- editorial review
- address review comments, rework param sections
- added a common section for parameters
- remove liquid tags for notes

Signed-off-by: David Karlsson <david.karlsson@docker.com>
Signed-off-by: Justin Chadwell <me@jedevc.com>
This commit is contained in:
David Karlsson
2022-09-21 15:38:03 +02:00
committed by Justin Chadwell
parent 04b56c7331
commit 91f0ed3fc3
7 changed files with 418 additions and 375 deletions
Download Patch File Download Diff File Expand all files Collapse all files

148
docs/guides/cache/registry.md vendored
View File

@ -1,129 +1,71 @@
# Registry cache storage
The `registry` cache store can be thought of as the natural extension to the
simple `inline` cache. Unlike the `inline` cache, the `registry` cache is
entirely separate from the image, which allows for more flexible usage -
`registry`-backed cache can do everything that the inline cache can do, and
more:
The `registry` cache storage can be thought of as an extension to the `inline`
cache. Unlike the `inline` cache, the `registry` cache is entirely separate from
the image, which allows for more flexible usage - `registry`-backed cache can do
everything that the inline cache can do, and more:
- It allows for separating the cache and resulting image artifacts so that
you can distribute your final image without the cache inside.
- It can efficiently cache multi-stage builds in `max` mode, instead of only
the final stage.
- Allows for separating the cache and resulting image artifacts so that you can
distribute your final image without the cache inside.
- It can efficiently cache multi-stage builds in `max` mode, instead of only the
final stage.
- It works with other exporters for more flexibility, instead of only the
`image` exporter.
> **Note**
>
> The `registry` cache storage backend requires using a different driver than
> the default `docker` driver - see more information on selecting a driver
> [here](../drivers/index.md). To create a new docker-container driver (which
> can act as a simple drop-in replacement):
> This cache storage backend requires using a different driver than the default
> `docker` driver - see more information on selecting a driver
> [here](../drivers/index.md). To create a new driver (which can act as a simple
> drop-in replacement):
>
> ```console
> docker buildx create --use --driver=docker-container
> ```
To import and export your cache using the `registry` storage backend we use the
`--cache-to` and `--cache-from` flags and point it to our desired image target
using the `ref` parameter:
## Synopsis
Unlike the simpler `inline` cache, the `registry` cache supports several
configuration parameters:
```console
$ docker buildx build --push -t <user>/<image> \
--cache-to type=registry,ref=<user>/<cache-image> \
--cache-from type=registry,ref=<user>/<cache-image> .
$ docker buildx build . --push -t <registry>/<image> \
--cache-to type=registry,ref=<registry>/<cache-image>[,parameters...] \
--cache-from type=registry,ref=<registry>/<cache-image>
```
You can choose any valid reference value for `ref`, as long as it's not the
same as the target location that you push your image to. You might choose
different tags (e.g. `foo/bar:latest` and `foo/bar:build-cache`), separate
image names (e.g. `foo/bar` and `foo/bar-cache`), or even different
repositories (e.g. `docker.io/foo/bar` and `ghcr.io/foo/bar`).
Common parameters:
If the cache does not exist, then the cache import step will fail, but the
build will continue.
- `ref`: full address and name of the cache image that you want to import or
export.
## Cache options
Parameters for `--cache-to`:
Unlike the simple `inline` cache, the `registry` cache has lots of parameters to
adjust its behavior.
- `mode`: specify cache layers to export (default: `min`), see
[cache mode](./index.md#cache-mode)
- `oci-mediatypes`: whether to use OCI media types in exported manifests
(default `true`, since BuildKit `v0.8`), see
[OCI media types](./index.md#oci-media-types)
- `compression`: compression type for layers newly created and cached (default:
`gzip`), see [cache compression](./index.md#cache-compression)
- `compression-level`: compression level for `gzip`, `estargz` (0-9) and `zstd`
(0-22)
- `force-compression`: forcibly apply `compression` option to all layers
### Cache mode
You can choose any valid value for `ref`, as long as it's not the same as the
target location that you push your image to. You might choose different tags
(e.g. `foo/bar:latest` and `foo/bar:build-cache`), separate image names (e.g.
`foo/bar` and `foo/bar-cache`), or even different repositories (e.g.
`docker.io/foo/bar` and `ghcr.io/foo/bar`). It's up to you to decide the
strategy that you want to use for separating your image from your cache images.
Build cache can be exported in one of two modes: `min` or `max`, with either
`mode=min` or `mode=max` respectively. For example, to build the cache with
`mode=max`:
```console
$ docker buildx build --push -t <user>/<image> \
--cache-to type=registry,ref=<user>/<cache-image>,mode=max \
--cache-from type=registry,ref=<user>/<cache-image> .
```
Note that only `--cache-to` needs to be modified, as `--cache-from` will
automatically extract the relevant parameters from the resulting output.
In `min` cache mode (the default), only layers that are exported into the
resulting image are cached, while in `max` cache mode, all layers are cached,
even those of intermediate steps.
While `min` cache is typically smaller (which speeds up import/export times,
and reduces storage costs), `max` cache is more likely to get more cache hits.
Depending on the complexity and location of your build, you should experiment
with both parameters to get the results.
### Cache compression
Since `registry` cache is exported separately from the main build result, you
can specify separate compression parameters for it (which are similar to the
options provided by the `image` exporter). While the defaults have been
selected to provide a good out-of-the-box experience, you may wish to tweak the
parameters to optimize for storage vs compute costs.
To select the compression algorithm, you can use the `compression=<uncompressed|gzip|estargz|zstd>`
option. For example, to build the cache with `compression=zstd`:
```console
$ docker buildx build --push -t <user>/<image> \
--cache-to type=registry,ref=<user>/<cache-image>,compression=zstd \
--cache-from type=registry,ref=<user>/<cache-image> .
```
The `compression-level=<value>` option can be used alongside the `compression`
parameter to choose a compression level for the algorithms which support it
(from 0-9 for `gzip` and `estargz` and 0-22 for `zstd`). As a general rule, the
higher the number, the smaller the resulting file will be, but the longer the
compression will take to run.
The `force-compression=<bool>` option can be enabled with `true` (and disabled
with `false`) to force re-compressing layers that have been imported from a
previous cache if the requested compression algorithm is different from the
previous compression algorithm.
> **Note**
>
> The `gzip` and `estargz` compression methods use the [`compress/gzip` package](https://pkg.go.dev/compress/gzip),
> while `zstd` uses the [`github.com/klauspost/compress/zstd` package](https://github.com/klauspost/compress/tree/master/zstd).
### OCI media types
Like the `image` exporter, the `registry` cache exporter supports creating
images with Docker media types or with OCI media types. To enable OCI Media
types, you can use the `oci-mediatypes` property:
```console
$ docker buildx build --push -t <user>/<image> \
--cache-to type=registry,ref=<user>/<cache-image>,oci-mediatypes=true \
--cache-from type=registry,ref=<user>/<cache-image> .
```
This property is only meaningful with the `--cache-to` flag, when fetching
cache, BuildKit will auto-detect the correct media types to use.
<!-- FIXME: link to image exporter guide when it's written -->
If the `--cache-from` target doesn't exist, then the cache import step will
fail, but the build will continue.
## Further reading
For an introduction to caching see [Optimizing builds with cache management](https://docs.docker.com/build/building/cache).
For an introduction to caching see
[Optimizing builds with cache management](https://docs.docker.com/build/building/cache).
For more information on the `registry` cache backend, see the [BuildKit README](https://github.com/moby/buildkit#registry-push-image-and-cache-separately).
For more information on the `registry` cache backend, see the
[BuildKit README](https://github.com/moby/buildkit#registry-push-image-and-cache-separately).