kache 0.14.0

Zero-copy, content-addressed build cache for Rust, C/C++ and more, with S3 and shared-filesystem remotes.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178

---
title: S3 setup
description: Configure an S3-compatible remote cache and connect kache to it.
---

# S3 setup

kache supports AWS S3 and common S3-compatible storage such as Cloudflare R2,
Ceph, and MinIO. The configuration is the same across providers; adjust the
endpoint and credentials.

For a shared mounted directory instead, see [Filesystem setup](/docs/remote-cache/filesystem-setup).
The kache binary currently compiles only these `s3` and `filesystem` remote
types.

## Minimal configuration

```toml title="~/.config/kache/config.toml"
[cache.remote]
type = "s3"
bucket = "my-build-cache"
```

With just a bucket name and no endpoint, kache uses AWS S3 with the default credential chain (environment variables, `~/.aws/credentials`, IAM role).

<Callout type="warn">
  If you omit `region`, kache defaults to `us-east-1` rather than your bucket's actual region. Set `region` to your bucket's region for AWS S3, and to whatever value your provider expects (or `auto`) for S3-compatible endpoints.
</Callout>

## Provider examples

<Tabs items={["AWS S3", "Cloudflare R2", "Ceph / MinIO"]}>
  <Tab value="AWS S3">
    ```toml
    [cache.remote]
    type = "s3"
    bucket = "my-build-cache"
    region = "eu-west-1"
    profile = "my-aws-profile"   # omit to use default profile
    ```

    For CI, prefer IAM roles or environment variables over a stored profile.
  </Tab>
  <Tab value="Cloudflare R2">
    ```toml
    [cache.remote]
    type = "s3"
    bucket = "my-build-cache"
    endpoint = "https://<account-id>.r2.cloudflarestorage.com"
    region = "auto"
    ```

    Set credentials via `KACHE_S3_ACCESS_KEY` and `KACHE_S3_SECRET_KEY` or an AWS profile pointing to R2 API tokens.
  </Tab>
  <Tab value="Ceph / MinIO">
    ```toml
    [cache.remote]
    type = "s3"
    bucket = "build-cache"
    endpoint = "https://s3.internal.example.com"
    profile = "ceph"
    ```

    The `profile` field refers to a named profile in `~/.aws/credentials` or `~/.aws/config`. Region is optional for Ceph but you can set it to any non-empty string if your setup requires it.

    kache always uses path-style addressing (`https://endpoint/bucket/key`) for every provider, so self-hosted S3 works without virtual-hosted/bucket-subdomain DNS. This also makes dotted bucket names safe on custom endpoints.
  </Tab>
</Tabs>

## Credential resolution order

When kache needs S3 credentials, it checks these sources in order:

1. `KACHE_S3_ACCESS_KEY` + `KACHE_S3_SECRET_KEY` (explicit env var override)
2. Standard `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` environment credentials
3. The selected shared profile (`KACHE_S3_PROFILE`, `profile`, `AWS_PROFILE`, then `default`)
4. Legacy inline SSO for that profile
5. `credential_process` for that profile
6. Environment-based web identity (`AWS_ROLE_ARN` + `AWS_WEB_IDENTITY_TOKEN_FILE`)
7. ECS/task credentials, then EC2 instance credentials

For CI, explicit environment credentials or IAM roles are the most common. For
local setups with multiple AWS accounts, a named profile keeps credentials
organized.

<Callout type="warn">
  Both halves of the explicit pair are required. If only `KACHE_S3_ACCESS_KEY` or only `KACHE_S3_SECRET_KEY` is set, kache logs a warning and falls back to the AWS chain rather than erroring — so a missing half surfaces as confusing "wrong credentials" behavior, not a clear failure.
</Callout>

### Environment overrides

Every remote config field has a matching `KACHE_S3_*` env var, which takes precedence over the config file. This is handy in CI, where setting env vars is easier than shipping a config file:

| Env var | Overrides config field |
| --- | --- |
| `KACHE_S3_BUCKET` | `bucket` |
| `KACHE_S3_ENDPOINT` | `endpoint` |
| `KACHE_S3_REGION` | `region` |
| `KACHE_S3_PREFIX` | `prefix` |
| `KACHE_S3_PROFILE` | `profile` |
| `KACHE_S3_ACCESS_KEY` / `KACHE_S3_SECRET_KEY` | (explicit credentials) |

Existing Kache S3 config keys and defaults remain accepted. A legacy
`[cache.remote]` table without a `type` field and an environment-only setup
rooted in `KACHE_S3_BUCKET` still select S3; the other `KACHE_S3_*` overrides
remain available. `type = "s3"` is the recommended explicit form for new
config files. The AWS SDK-specific migration boundaries below still apply.

## OpenDAL migration boundaries

The config-file and `KACHE_S3_*` interfaces are retained. Static shared
profiles, legacy inline SSO profiles, `credential_process`, environment-based
web identity, ECS/task credentials, and EC2 instance credentials remain
available. Web identity uses `cache.remote.region` when choosing its STS
endpoint.

<Callout type="warn">
  OpenDAL currently signs with SigV4 only. SigV4a / Multi-Region Access Points,
  assume-role profiles that rely on `role_arn` with `source_profile` or
  `credential_source`, and modern profiles that refer to a separate
  `[sso-session ...]` section are not yet compatible. Profile-based web
  identity (`role_arn` + `web_identity_token_file` in the profile) is also not
  loaded; use its standard environment variables instead. Resolve unsupported
  profile credentials before launching kache (standard AWS credential env vars
  work), or use `credential_process`. AWS China, ISO, FIPS, and dual-stack
  endpoints should also set `endpoint` explicitly.
</Callout>

OpenDAL normalizes object paths, so kache stores objects under a canonical
prefix. A non-canonical `prefix` is normalized rather than rejected: a leading or
trailing slash, surrounding whitespace and `//` are collapsed, and kache logs a
warning when that happens. An empty prefix is valid and stores objects at the
bucket root.

Normalization changes where objects live. `prefix = "team/"` previously wrote
`team//v3/...` and now writes `team/v3/...`, so objects written by an older
kache are no longer found and the remote cache repopulates once. Copy those
objects first if you want to keep them.

Backslashes and `.` / `..` segments are still rejected: there is no safe
normalization for them. A rejected prefix does not fail your build — kache logs
the reason, continues without a remote cache, and reports it in `kache status`.

`AWS_ENDPOINT_URL_S3` remains supported when `endpoint` / `KACHE_S3_ENDPOINT`
is unset. An `endpoint_url` stored only inside an AWS shared profile is not
loaded by OpenDAL; copy it to `cache.remote.endpoint` or
`KACHE_S3_ENDPOINT` during migration.

## S3 bucket layout

Each cached entry is two objects — a packed tarball plus a small JSON manifest used for existence checks and listing:

```
{prefix}/v3/packs/{crate_name}/{cache_key}.tar.zst      # the packed artifacts (zstd-compressed tar)
{prefix}/v3/manifests/{crate_name}/{cache_key}.json     # small manifest for existence/listing
```

The default prefix is `artifacts`. Organizing by crate name makes filtered listing efficient — `kache sync --pull` issues one `ListObjectsV2` per crate against `{prefix}/v3/manifests/{crate_name}/`, so it only enumerates manifests for crates in your `Cargo.lock` rather than scanning the whole `v3/manifests/` tree. Use `kache sync --pull --all` to list everything.

`kache save-manifest` also writes build manifests under a separate `{prefix}/_manifests/` namespace (and, when a namespace and `Cargo.lock` are present, content-addressed shards under `{prefix}/_manifests/v3/{namespace}/shards/{hash}.json`). Bucket policies that scope by prefix must grant access to `_manifests/` as well as `v3/`.

## Bucket policies

kache needs `s3:GetObject`, `s3:PutObject`, and `s3:ListBucket` on the bucket. For read-only CI runners that pull but don't push, `s3:GetObject` and `s3:ListBucket` are sufficient. If you restrict the policy by prefix, cover both `{prefix}/v3/*` and `{prefix}/_manifests/*` (see [S3 bucket layout](#s3-bucket-layout)).

## Compression

zstd compression applies to the remote `.tar.zst` packs only; the local blob store is kept uncompressed. The default level is `3` — fast to compress and decompress, with reasonable size reduction. Lower levels (1–2) cut compression overhead when network bandwidth matters less than CPU time; higher levels (up to 22) are available but rarely worth it for build artifacts. Values are clamped to the `1`–`22` range.

`KACHE_COMPRESSION_LEVEL` is read when the process that does the compressing starts, so set it on the uploader rather than on a plain `cargo build`:

```sh
KACHE_COMPRESSION_LEVEL=1 kache sync --push   # fastest, larger packs
```

<Callout>
  The daemon loads its config once at startup, so changing `KACHE_COMPRESSION_LEVEL` for a single `cargo build` does not reconfigure an already-running daemon. Stop and start a manually managed daemon from the intended environment. For an installed service, put the setting in the watched config or service definition; `kache daemon restart` retains the service environment.
</Callout>