rollouts
Rollouts take a registered bcd release to the nodes of the tenant's pools in waves, within each pool's disruption budget. A controller settles nodes as they report the new version, pauses the rollout when a wave's failure ratio exceeds its limit, and soaks between waves. Every method decides `compute:fleet:admin` on the fleet scope. See [Rollouts](/docs/guides/rollouts).
Rollouts take a registered bcd release to the nodes of the tenant's pools in waves, within each pool's disruption budget. A controller settles nodes as they report the new version, pauses the rollout when a wave's failure ratio exceeds its limit, and soaks between waves. Every method decides compute:fleet:admin on the fleet scope. See Rollouts.
All 6 methods are served by this release.
| Method | Kind | Authorization | Phase | Status |
|---|---|---|---|---|
create | mutation | compute:fleet:admin @ compute-fleet | v0.4 | registered |
list | read | compute:fleet:admin @ compute-fleet | v0.4 | registered |
get | read | compute:fleet:admin @ compute-fleet | v0.4 | registered |
pause | mutation | compute:fleet:admin @ compute-fleet | v0.4 | registered |
resume | mutation | compute:fleet:admin @ compute-fleet | v0.4 | registered |
abort | mutation | compute:fleet:admin @ compute-fleet | v0.4 | registered |
create
POST /api/compute/rollouts/create
Plans a rollout of a registered release to every node that runs bcd in the tenant's pools, or in poolIds, and starts it; returns the rollout in running.
-
Plan. Nodes are shuffled by a hash of the rollout id and assigned to
waves, cumulative percentages that must increase and end at 100 (default 1, 10, 50, 100). The other gates default tomaxFailureRatio0.05,soakSeconds600 andupgradeTimeoutSeconds900. Nodes that already report the version start assucceeded. -
Idempotency.
idempotencyKeyis optional. With a key, the rollout id derives from the tenant, the caller and the key: a repeat for the same version returns the existing rollout, and another version under the key isCONFLICT. -
Errors.
NOT_FOUNDwhen the version is not registered or a listed pool is not an unarchived pool of the tenant.INVALID_STATEwhen no node in scope runs bcd yet.CONFLICTwithdetails.rolloutIdwhen a node in scope is in another running or paused rollout.INVALID_INPUTfor gates out of range. -
Events.
rollout.started; the controller later publishesrollout.wave,rollout.pausedandrollout.completed. -
Kind: mutation
-
Authorization:
compute:fleet:admin@compute-fleet -
Module:
rollout -
Phase: v0.4 (registered)
Input
| Field | Type | Required | Constraints |
|---|---|---|---|
tenantId | string | yes | at most 128 characters; matches ^[A-Za-z0-9._:-]{1,128}$ |
version | string | yes | matches ^v?\d+\.\d+\.\d+([-+][0-9A-Za-z.-]+)?$ |
poolIds | list of string | 1-1000 items | |
waves | list of number | 1-10 items; default [1,10,50,100] | |
maxFailureRatio | number | 0-1; default 0.05 | |
soakSeconds | number | 0-604800; default 600 | |
upgradeTimeoutSeconds | number | 60-86400; default 900 | |
idempotencyKey | string | at most 128 characters; matches ^[A-Za-z0-9._~:/+=-]{1,128}$ |
list
POST /api/compute/rollouts/list
Returns the tenant's 100 most recent rollouts, newest first, each with its node counts by state.
- Kind: read
- Authorization:
compute:fleet:admin@compute-fleet - Module:
rollout - Phase: v0.4 (registered)
Input
| Field | Type | Required | Constraints |
|---|---|---|---|
tenantId | string | yes | at most 128 characters; matches ^[A-Za-z0-9._:-]{1,128}$ |
get
POST /api/compute/rollouts/get
Returns one rollout of the tenant with nodeList, each node's wave, state, previous version, timings and error, in rollout order.
A rollout of another tenant, or none, is NOT_FOUND.
- Kind: read
- Authorization:
compute:fleet:admin@compute-fleet - Module:
rollout - Phase: v0.4 (registered)
Input
| Field | Type | Required | Constraints |
|---|---|---|---|
tenantId | string | yes | at most 128 characters; matches ^[A-Za-z0-9._:-]{1,128}$ |
rolloutId | string | yes | at most 60 characters; matches ^rollout_[0-9a-hjkmnp-tv-z]{26,52}$ |
pause
POST /api/compute/rollouts/pause
Stops a running or paused rollout from starting more nodes and records reason (default "paused by an operator"); returns the rollout in paused.
Nodes already upgrading still settle. A completed or aborted rollout is INVALID_STATE. Publishes rollout.paused.
- Kind: mutation
- Authorization:
compute:fleet:admin@compute-fleet - Module:
rollout - Phase: v0.4 (registered)
Input
| Field | Type | Required | Constraints |
|---|---|---|---|
tenantId | string | yes | at most 128 characters; matches ^[A-Za-z0-9._:-]{1,128}$ |
rolloutId | string | yes | at most 60 characters; matches ^rollout_[0-9a-hjkmnp-tv-z]{26,52}$ |
reason | string | at most 500 characters |
resume
POST /api/compute/rollouts/resume
Sets a running or paused rollout back to running, clears its reason and wakes the controller; returns the rollout.
A rollout paused by the failure gate resumes the same way. A completed or aborted rollout is INVALID_STATE. Publishes rollout.resumed.
- Kind: mutation
- Authorization:
compute:fleet:admin@compute-fleet - Module:
rollout - Phase: v0.4 (registered)
Input
| Field | Type | Required | Constraints |
|---|---|---|---|
tenantId | string | yes | at most 128 characters; matches ^[A-Za-z0-9._:-]{1,128}$ |
rolloutId | string | yes | at most 60 characters; matches ^rollout_[0-9a-hjkmnp-tv-z]{26,52}$ |
abort
POST /api/compute/rollouts/abort
Ends a running or paused rollout: nodes not yet started are skipped, and with rollback: true upgrades not yet confirmed go back to the version they ran before; returns the rollout in aborted.
-
With
rollback, nodes stillupgradingwhose previous version is a registered release move torolling-back, and the controller settles them. Nodes thatsucceededkeep the release: once a node confirmed it, bcd refuses every older binary, the one in its other slot included. Undo a bad release by publishing a newer one (a higher sequence) and rolling it out. Withoutrollback, nodes still upgrading are markedfailed. -
reasondefaults to "aborted by an operator". A completed or aborted rollout isINVALID_STATE. Publishesrollout.aborted. -
Kind: mutation
-
Authorization:
compute:fleet:admin@compute-fleet -
Module:
rollout -
Phase: v0.4 (registered)
Input
| Field | Type | Required | Constraints |
|---|---|---|---|
tenantId | string | yes | at most 128 characters; matches ^[A-Za-z0-9._:-]{1,128}$ |
rolloutId | string | yes | at most 60 characters; matches ^rollout_[0-9a-hjkmnp-tv-z]{26,52}$ |
reason | string | at most 500 characters | |
rollback | boolean | default false |
Better Compute is created by Sean Filimon
Last updated
reservations
A reservation is a tenant's claim on devices of one pool for a time window. `create` first writes the request as a draft, Better IAM decides once on that draft with the request as attributes, and only an allowed draft is charged against quota and placed. A reservation holds its quota charge until it reaches a terminal state, and the `capacity.reservations` reconciler drives it through `placed`, `binding` and `active` to `released`. See [Reservations](/docs/guides/capacity/reservations).
sandboxSnapshots
Sandbox snapshots are their own resource, so a snapshot kept with `keep: true` outlives the sandbox it came from. `sandboxes.snapshot` takes them and `sandboxes.create` restores from them with `fromSnapshot`. These methods list, read and delete them. Snapshots stay private to their tenant and are never promoted to shared images. See [Sandboxes](/docs/guides/vps/sandboxes).