docker/buildx
1
0
Fork 0
mirror of https://gitea.com/Lydanne/buildx.git synced 2025-07-13 23:17: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

105
docs/guides/cache/local.md vendored
View File

@ -1,40 +1,63 @@
# Local cache storage
The `local` cache store is a simple cache option that stores your cache as
files in a local directory on your filesystem (using an [OCI image layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md)
for the underlying directory structure). It's a good choice if you're just
testing locally, or want the flexibility to manage a shared storage option
yourself, by manually uploading it to a file server, or mounting it over an
NFS volume.
The `local` cache store is a simple cache option that stores your cache as files
in a directory on your filesystem, using an
[OCI image layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md)
for the underlying directory structure. Local cache is a good choice if you're
just testing, or if you want the flexibility to self-manage a shared storage
solution.
> **Note**
>
> The `local` 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 `local` storage backend we use the
`--cache-to` and `--cache-from` flags and point it to our desired local
directory using the `dest` and `src` parameters respectively:
## Synopsis
```console
$ docker buildx build --push -t <user>/<image> \
--cache-to type=local,dest=path/to/local/dir \
--cache-from type=local,src=path/to/local/dir .
$ docker buildx build . --push -t <registry>/<image> \
--cache-to type=local,dest=path/to/local/dir[,parameters...] \
--cache-from type=local,src=path/to/local/dir,
```
If the cache does not exist, then the cache import step will fail, but the
build will continue.
Parameters for `--cache-to`:
- `dest`: absolute or relative path to the local directory where you want to
export the cache to.
- `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
Parameters for `--cache-from`:
- `src`: absolute or relative path to the local directory where you want to
import cache from.
- `digest`: specify explicit digest of the manifest list to import, see
[cache versioning](#cache-versioning)
If the `src` cache doesn't exist, then the cache import step will fail, but
the build will continue.
## Cache versioning
If you inspect the cache directory manually, you can see the resulting OCI
image layout:
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.
If you inspect the cache directory manually, you can see the resulting OCI image
layout:
```console
$ ls cache
@ -55,40 +78,26 @@ $ cat cache/index.json | jq
}
```
Similarly to the other cache exporters, the cache is replaced on export, by
replacing the contents of the `index.json` file - however, previous caches will
still be available if the hash of the previous cache image index is known.
These old caches will be kept indefinitely, so the local directory will
continue to grow: see [moby/buildkit#1896](https://github.com/moby/buildkit/issues/1896)
for more information.
Like other cache types, local cache gets replaced on export, by replacing the
contents of the `index.json` file. However, previous caches will still be
available in the `blobs` directory. These old caches are addressable by digest,
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 importing cache using `--cache-to`, you can additionally specify the
`digest` parameter to force loading an older version of the cache, for example:
When importing cache using `--cache-to`, you can specify the `digest` parameter
to force loading an older version of the cache, for example:
```console
$ docker buildx build --push -t <user>/<image> \
$ docker buildx build . --push -t <registry>/<image> \
--cache-to type=local,dest=path/to/local/dir \
--cache-from type=local,ref=path/to/local/dir,digest=sha256:6982c70595cb91769f61cd1e064cf5f41d5357387bab6b18c0164c5f98c1f707 .
--cache-from type=local,ref=path/to/local/dir,digest=sha256:6982c70595cb91769f61cd1e064cf5f41d5357387bab6b18c0164c5f98c1f707
```
## Cache options
The `local` cache has lots of parameters to adjust its behavior.
### Cache mode
See [Registry - Cache mode](./registry.md#cache-mode) for more information.
### Cache compression
See [Registry - Cache compression](./registry.md#cache-compression) for more information.
### OCI media types
See [Registry - OCI Media Types](./registry.md#oci-media-types) for more information.
## 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 `local` cache backend, see the [BuildKit README](https://github.com/moby/buildkit#local-directory-1).
For more information on the `local` cache backend, see the
[BuildKit README](https://github.com/moby/buildkit#local-directory-1).