centersl/docker-docs
1
0
Fork 0
mirror of https://github.com/docker/docs.git synced 2026-03-27 14:28:47 +07:00
Code Issues Packages Projects Releases Wiki Activity

Update s3 cache options (#23758)

Browse Source 
## Description

Add missing S3 `prefix` option, and update existing options which lacked
current defaults.

A link regarding authentication pointed to an old, EOL API which was
also updated; an equivalent link should be fixed in buildkit docs as
well (https://github.com/moby/buildkit/pull/6379).

The description I added for `prefix` is a little vague. The buildkit
docs for that option in particular is also vague, but makes sense in the
context of the documentation for other options. I opted to stay
consistent with the language and brevity of the surrounding docs,
leaving it to buildkit docs to clarify how it works.

## Reviews


<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->

- [ ] Technical review
- [ ] Editorial review
- [ ] Product review
This commit is contained in:
David Karlsson
2025-11-24 10:47:19 +01:00
committed by GitHub
parent 3be86cb044 0e18ebc32d
commit 4a3603b992
1 changed files with 18 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
content/manuals/build/cache/backends/s3.md vendored
View File

@@ -27,22 +27,23 @@ $ docker buildx build --push -t <user>/<image> \
The following table describes the available CSV parameters that you can pass to
`--cache-to` and `--cache-from`.
| Name | Option | Type | Default | Description |
| -------------------- | ----------------------- | ----------- | ------- | -------------------------------------------------------------- |
| `region` | `cache-to`,`cache-from` | String | | Required. Geographic location. |
| `bucket` | `cache-to`,`cache-from` | String | | Required. Name of the S3 bucket. |
| `name` | `cache-to`,`cache-from` | String | | Name of the cache image. |
| `endpoint_url` | `cache-to`,`cache-from` | String | | Endpoint of the S3 bucket. |
| `blobs_prefix` | `cache-to`,`cache-from` | String | | Prefix to prepend to blob filenames. |
| `upload_parallelism` | `cache-to` | Integer | `4` | Number of parallel layer uploads. |
| `touch_refresh` | `cache-to` | Time | `24h` | Interval for updating the timestamp of unchanged cache layers. |
| `manifests_prefix` | `cache-to`,`cache-from` | String | | Prefix to prepend on manifest filenames. |
| `use_path_style` | `cache-to`,`cache-from` | Boolean | `false` | When `true`, uses `bucket` in the URL instead of hostname. |
| `access_key_id` | `cache-to`,`cache-from` | String | | See [authentication][1]. |
| `secret_access_key` | `cache-to`,`cache-from` | String | | See [authentication][1]. |
| `session_token` | `cache-to`,`cache-from` | String | | See [authentication][1]. |
| `mode` | `cache-to` | `min`,`max` | `min` | Cache layers to export, see [cache mode][2]. |
| `ignore-error` | `cache-to` | Boolean | `false` | Ignore errors caused by failed cache exports. |
| Name | Option | Type | Default | Description |
|----------------------| ----------------------- | ----------- |--------------|----------------------------------------------------------------|
| `region` | `cache-to`,`cache-from` | String | | Required. Geographic location. |
| `bucket` | `cache-to`,`cache-from` | String | | Required. Name of the S3 bucket. |
| `name` | `cache-to`,`cache-from` | String | `buildkit` | Name of the cache image. |
| `endpoint_url` | `cache-to`,`cache-from` | String | | Endpoint of the S3 bucket. |
| `prefix` | `cache-to`,`cache-from` | String | | Prefix to prepend to all filenames. |
| `blobs_prefix` | `cache-to`,`cache-from` | String | `blobs/` | Prefix to prepend to blob filenames. |
| `upload_parallelism` | `cache-to` | Integer | `4` | Number of parallel layer uploads. |
| `touch_refresh` | `cache-to` | Time | `24h` | Interval for updating the timestamp of unchanged cache layers. |
| `manifests_prefix` | `cache-to`,`cache-from` | String | `manifests/` | Prefix to prepend to manifest filenames. |
| `use_path_style` | `cache-to`,`cache-from` | Boolean | `false` | When `true`, uses `bucket` in the URL instead of hostname. |
| `access_key_id` | `cache-to`,`cache-from` | String | | See [authentication][1]. |
| `secret_access_key` | `cache-to`,`cache-from` | String | | See [authentication][1]. |
| `session_token` | `cache-to`,`cache-from` | String | | See [authentication][1]. |
| `mode` | `cache-to` | `min`,`max` | `min` | Cache layers to export, see [cache mode][2]. |
| `ignore-error` | `cache-to` | Boolean | `false` | Ignore errors caused by failed cache exports. |
[1]: #authentication
[2]: _index.md#cache-mode
@@ -57,7 +58,7 @@ Alternatively, you can use the `access_key_id`, `secret_access_key`, and
Refer to [AWS Go SDK, Specifying Credentials][3] for details about
authentication using environment variables and credentials file.
[3]: https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials
[3]: https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/configure-gosdk.html#specifying-credentials
## Further reading