Menu
Platform
AI
App store purchases
Database
Flags
Jobs and cron
Localization
Monitoring
Notifications
Payments
Queues
Sandboxes
Webhooks
Getting Started
Authentication
KV Store
Deploy & Infrastructure
Reference
Build caches
The cache a build reads and writes, and why it can never change a result.
Today this runs on the management API
Builds use the project's layer cache automatically, and there is no cache call to make. The build_caches commands below are in the CLI's command list, but api.sylphx.com does not serve the collection.
A BuildCache is a per-project layer cache. A build that reads it does less work than the build that filled it, which is the whole of what it is for.
It makes builds faster and never changes their result. That is the property worth knowing: a build whose cache is missing or unreachable produces the same image and the same digests, only slower. Nothing about a build's correctness depends on a cache being there.
#What a build does with it
A build names the cache it reads and writes, and unset means the project's default cache:
| Field | Type | What it is |
|---|---|---|
cache | string | The BuildCache to read and write; the project’s default cache by default. |
Because the cache belongs to the project rather than to one build, every build of that project reads and writes the same cache. That is what makes the second build of the same work cheap: the first one already paid for it.
#The one field you set, and the four you read
| Field | Type | What it is |
|---|---|---|
retention | duration | Entries unused this long are evicted. |
retention is the whole of the spec. It bounds how long an entry survives
without being read, which is why eviction under it costs time and never
correctness — the build that finds an entry gone rebuilds it. The reference
carries the default on the update page.
What the platform reports about a cache is read-only:
| Field | Type | What it is |
|---|---|---|
size_bytes | int64 | Bytes stored. |
last_use_time | timestamp | When a build last read the cache. |
conditions | Condition[] | Ready, Reconciling, Stalled. |
observed_generation | int64 | The generation this status was computed from. |
last_use_time answers whether a cache is earning its keep: it is when a
build last read the cache, and an entry nothing reads is evicted once
retention runs out.
#Reading, changing and deleting one
A cache is read by name under its project, and the project's caches are one list:
sylphx build build-caches get orgs/acme/projects/shop/build_caches/build-cachesylphx build build-caches list orgs/acme/projects/shopupdate changes the spec, with update_mask naming the fields to write and
allow_missing creating the cache when it does not exist:
sylphx build build-caches update orgs/acme/projects/shop/build_caches/build-cachedelete is destructive, so the CLI asks before it runs and takes --yes:
sylphx build build-caches delete orgs/acme/projects/shop/build_caches/build-cache --yesDeleting a cache does not delete a build and does not change one: the next build finds no entries and makes them again. The cost of a delete is the work the cache was saving, and nothing else.
Reading a cache needs build:read; changing or deleting one needs
build:write. The collection, method by method, is in
the build_caches reference.