Skip to content

docs: clarify tag param description in local cache docs #25169

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Se3do wants to merge 1 commit into
base: main
Choose a base branch
from
+34 −14
Open

docs: clarify tag param description in local cache docs #25169

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 34 additions & 14 deletions content/manuals/build/cache/backends/local.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,18 +24,19 @@ $ docker buildx build --push -t <registry>/<image> \
The following table describes the available CSV parameters that you can pass to
`--cache-to` and `--cache-from`.

| Name | Option | Type | Default | Description |
|---------------------|--------------|-------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------|
| `src` | `cache-from` | String | | Path of the local directory where cache gets imported from. |
| `digest` | `cache-from` | String | | Digest of manifest to import, see [cache versioning][4]. |
| `dest` | `cache-to` | String | | Path of the local directory where cache gets exported to. |
| `mode` | `cache-to` | `min`,`max` | `min` | Cache layers to export, see [cache mode][1]. |
| `oci-mediatypes` | `cache-to` | `true`,`false` | `true` | Use OCI media types in exported manifests, see [OCI media types][2]. |
| `image-manifest` | `cache-to` | `true`,`false` | `true` | When using OCI media types, generate an image manifest instead of an image index for the cache image, see [OCI media types][2]. |
| `compression` | `cache-to` | `gzip`,`estargz`,`zstd` | `gzip` | Compression type, see [cache compression][3]. |
| `compression-level` | `cache-to` | `0..22` | | Compression level, see [cache compression][3]. |
| `force-compression` | `cache-to` | `true`,`false` | `false` | Forcibly apply compression, see [cache compression][3]. |
| `ignore-error` | `cache-to` | Boolean | `false` | Ignore errors caused by failed cache exports. |
| Name | Option | Type | Default | Description |
| ------------------- | ----------------------- | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `src` | `cache-from` | String | | Path of the local directory where cache gets imported from. |
| `digest` | `cache-from` | String | | Digest of manifest to import, see [cache versioning][4]. |
| `tag` | `cache-to`, `cache-from` | String | `latest` | Custom tag for the cache image in the local index, see [cache versioning][4]. |
| `dest` | `cache-to` | String | | Path of the local directory where cache gets exported to. |
| `mode` | `cache-to` | `min`,`max` | `min` | Cache layers to export, see [cache mode][1]. |
| `oci-mediatypes` | `cache-to` | `true`,`false` | `true` | Use OCI media types in exported manifests, see [OCI media types][2]. |
| `image-manifest` | `cache-to` | `true`,`false` | `true` | When using OCI media types, generate an image manifest instead of an image index for the cache image, see [OCI media types][2]. |
| `compression` | `cache-to` | `gzip`,`estargz`,`zstd` | `gzip` | Compression type, see [cache compression][3]. |
| `compression-level` | `cache-to` | `0..22` | | Compression level, see [cache compression][3]. |
| `force-compression` | `cache-to` | `true`,`false` | `false` | Forcibly apply compression, see [cache compression][3]. |
| `ignore-error` | `cache-to` | Boolean | `false` | Ignore errors caused by failed cache exports. |
Comment thread
Se3do marked this conversation as resolved.

[1]: _index.md#cache-mode
[2]: _index.md#oci-media-types
Expand All @@ -47,8 +48,6 @@ build continues.

## Cache versioning

<!-- FIXME: update once https://github.com/moby/buildkit/pull/3111 is released -->

This section describes how versioning works for caches on a local filesystem,
and how you can use the `digest` parameter to use older versions of cache.

Expand Down Expand Up @@ -81,6 +80,27 @@ and kept indefinitely. Therefore, the size of the local cache will continue to
grow (see [`moby/buildkit#1896`](https://github.com/moby/buildkit/issues/1896)
for more information).

When using the local cache backend with `--cache-to`, you can use the `tag`
parameter to name the cache reference recorded in the local OCI layout's
`index.json` (via `org.opencontainers.image.ref.name`), not the built image
tag. This lets you store multiple cache outputs in the same directory by
using different cache reference names; reusing the same `tag` will update that
reference in `index.json`.

Comment thread
Se3do marked this conversation as resolved.
```console
$ docker buildx build --push -t <registry>/<image> \
--cache-to type=local,dest=path/to/local/dir,tag=cache-v1 \
--cache-to type=local,dest=path/to/local/dir,tag=cache-v2
```

To import a cache with a specific tag, pass the `tag` parameter to
`--cache-from`:

```console
$ docker buildx build --push -t <registry>/<image> \
--cache-from type=local,src=path/to/local/dir,tag=cache-v1
```

When importing cache using `--cache-from`, you can specify the `digest` parameter
to force loading an older version of the cache, for example:

Expand Down