mirror of
https://gitea.com/Lydanne/buildx.git
synced 2025-07-09 21:17:09 +08:00
docs: additions from editorial review
- 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
committed by
Justin Chadwell
Justin Chadwell
parent
04b56c7331
commit
91f0ed3fc3
75
docs/guides/cache/s3.md
vendored
75
docs/guides/cache/s3.md
vendored
@ -1,64 +1,61 @@
|
||||
# AWS S3 cache storage
|
||||
# Amazon S3 cache storage
|
||||
|
||||
> **Warning**
|
||||
>
|
||||
> The `s3` cache is currently unreleased. You can use it today, by using the
|
||||
> This cache backend is unreleased. You can use it today, by using the
|
||||
> `moby/buildkit:master` image in your Buildx driver.
|
||||
|
||||
The `s3` cache store uploads your resulting build cache to [AWS's S3 file storage service](https://aws.amazon.com/s3/),
|
||||
into a bucket of your choice.
|
||||
The `s3` cache storage uploads your resulting build cache to
|
||||
[Amazon S3 file storage service](https://aws.amazon.com/s3/), into a specified
|
||||
bucket.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> The `s3` 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 `s3` storage backend we use the
|
||||
`--cache-to` and `--cache-from` flags and point it to our desired bucket using
|
||||
the required `region` and `bucket` parameters:
|
||||
## Synopsis
|
||||
|
||||
```console
|
||||
$ docker buildx build --push -t <user>/<image> \
|
||||
--cache-to type=s3,region=eu-west-1,bucket=my_bucket,name=my_image \
|
||||
--cache-from type=s3,region=eu-west-1,bucket=my_bucket,name=my_image
|
||||
$ docker buildx build . --push -t <user>/<image> \
|
||||
--cache-to type=s3,region=<region>,bucket=<bucket>,name=<cache-image>[,parameters...] \
|
||||
--cache-from type=s3,region=<region>,bucket=<bucket>,name=<cache-image>
|
||||
```
|
||||
|
||||
Common parameters:
|
||||
|
||||
- `region`: geographic location
|
||||
- `bucket`: name of the S3 bucket used for caching
|
||||
- `name`: name of the cache image
|
||||
- `access_key_id`: access key ID, see [authentication](#authentication)
|
||||
- `secret_access_key`: secret access key, see [authentication](#authentication)
|
||||
- `session_token`: session token, see [authentication](#authentication)
|
||||
|
||||
Parameters for `--cache-to`:
|
||||
|
||||
- `mode`: specify cache layers to export (default: `min`), see
|
||||
[cache mode](./index.md#cache-mode)
|
||||
|
||||
## Authentication
|
||||
|
||||
To authenticate to S3 to read from and write to the cache, the following
|
||||
parameters are required:
|
||||
|
||||
* `access_key_id`: access key ID
|
||||
* `secret_access_key`: secret access key
|
||||
* `session_token`: session token
|
||||
|
||||
While these can be manually provided, if left unspecified, then the credentials
|
||||
for S3 will be pulled from the BuildKit server's environment following the
|
||||
environment variables scheme for the [AWS Go SDK](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html).
|
||||
|
||||
> **Warning**
|
||||
>
|
||||
> These environment variables **must** be specified on the BuildKit server, not
|
||||
> the `buildx` client.
|
||||
`access_key_id`, `secret_access_key`, and `session_token`, if left unspecified,
|
||||
are read from environment variables on the BuildKit server following the scheme
|
||||
for the
|
||||
[AWS Go SDK](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html).
|
||||
The environment variables are read from the server, not the Buildx client.
|
||||
|
||||
<!-- FIXME: update once https://github.com/docker/buildx/pull/1294 is released -->
|
||||
|
||||
## Cache options
|
||||
|
||||
The `s3` cache has lots of parameters to adjust its behavior.
|
||||
|
||||
### Cache mode
|
||||
|
||||
See [Registry - Cache mode](./registry.md#cache-mode) 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 `s3` cache backend, see the [BuildKit README](https://github.com/moby/buildkit#s3-cache-experimental).
|
||||
For more information on the `s3` cache backend, see the
|
||||
[BuildKit README](https://github.com/moby/buildkit#s3-cache-experimental).
|
||||
|
||||
Reference in New Issue
Block a user