better/compute
API

pools

A pool groups the nodes of one site under one GPU model, one sharing mode and one policy, and every reservation and quota belongs to exactly one pool. The tenant that creates a pool owns it; other tenants see it only once the owner offers it to them with a quota. Only the owner can offer, unoffer, update or archive a pool; anyone else gets `NOT_FOUND`. See [Pools](/docs/guides/capacity/pools).

A pool groups the nodes of one site under one GPU model, one sharing mode and one policy, and every reservation and quota belongs to exactly one pool. The tenant that creates a pool owns it; other tenants see it only once the owner offers it to them with a quota. Only the owner can offer, unoffer, update or archive a pool; anyone else gets NOT_FOUND. See Pools.

All 8 methods are served by this release.

MethodKindAuthorizationPhaseStatus
listreadcompute:pools:read @ compute-tenant + itemsv0.1registered
getreadcompute:pools:read @ compute-poolv0.1registered
createmutationcompute:pools:create @ compute-fleet or compute:pools:create @ compute-tenantv0.1registered
capacityreadcompute:capacity:read @ compute-poolv0.1registered
offermutationcompute:pools:share @ compute-poolv0.1registered
unoffermutationcompute:pools:share @ compute-poolv0.1registered
updatemutationcompute:pools:manage @ compute-poolv0.2registered
archivemutationcompute:pools:manage @ compute-poolv0.2registered

list

POST /api/compute/pools/list

Returns the pools the tenant owns or is offered, each with owned, archived and the tenant's own quota rows.

Archived pools appear only for their owner. After the coarse decision on the tenant, each pool is checked as compute:pools:read on the pool, and only the allowed ones are returned.

  • Kind: read
  • Authorization: compute:pools:read @ compute-tenant + items
  • Module: capacity
  • Phase: v0.1 (registered)

Input

FieldTypeRequiredConstraints
tenantIdstringyesat most 128 characters; matches ^[A-Za-z0-9._:-]{1,128}$

get

POST /api/compute/pools/get

Returns one pool as the tenant sees it, with owned, archived and the tenant's own quota rows.

The call is NOT_FOUND when the pool is not owned by or offered to the tenant, or is archived and the tenant is not its owner.

  • Kind: read
  • Authorization: compute:pools:read @ compute-pool
  • Module: capacity
  • Phase: v0.1 (registered)

Input

FieldTypeRequiredConstraints
tenantIdstringyesat most 128 characters; matches ^[A-Za-z0-9._:-]{1,128}$
poolIdstringyesat most 57 characters; matches ^pool_[0-9a-hjkmnp-tv-z]{26,52}$

create

POST /api/compute/pools/create

Creates a pool on a site the tenant owns, with the owner's quota rows and an empty rollup; returns the pool at version 1.

  • It is decided as compute:pools:create on the tenant (compute-tenant), the alternative its catalog row lists next to compute-fleet.
  • sharing defaults to exclusive and agent to bcd (none for provider pools). A provider pool needs providerAccountId and agent: 'none', and other classes refuse providerAccountId; both are INVALID_INPUT.
  • ownerQuota defaults to gpu at 2,147,483,647. Owners of mig, timeslice or mps pools add gpu.mig or gpu.slot rows themselves, because a missing row grants 0.
  • The policy is checked as the nodes will get it (v1.1). Each module's pool-policy validator runs, e.g. provision's host units: hugepages, kernel modules, a kubernetes join set given all together or not at all, and sharing replicas up to 48. A policy nodes can't take is INVALID_INPUT.
  • On a platform (non-custom) site, a kubernetes join set also needs platformOperated: true: the cluster's admins get root on the machines, which keep their platform trust.
  • With idempotencyKey, the pool id is derived from the tenant, the caller and the key. A retry returns the stored pool without a second IAM decision; the same key with a different site, class, sharing mode, agent or provider account is CONFLICT.
  • A site the tenant does not own is NOT_FOUND.

Emits pool.created.

  • Kind: mutation
  • Authorization: compute:pools:create @ compute-fleet or compute:pools:create @ compute-tenant
  • Module: capacity
  • Phase: v0.1 (registered)

Input

FieldTypeRequiredConstraints
tenantIdstringyesat most 128 characters; matches ^[A-Za-z0-9._:-]{1,128}$
siteIdstringyesat most 57 characters; matches ^site_[0-9a-hjkmnp-tv-z]{26,52}$
classone of metal-host, metal-dedicated, vps-host, provideryes
gpuModelstringat most 32 characters; matches ^[A-Za-z0-9-]{1,32}$
sharingone of exclusive, mig, timeslice, mpsdefault "exclusive"
agentone of bcd, none
policyobject
ownerQuotamap of integerkeys match ^[A-Za-z][A-Za-z0-9._-]{0,63}$
providerAccountIdstringat most 58 characters; matches ^pacct_[0-9a-hjkmnp-tv-z]{26,52}$
idempotencyKeystringat most 128 characters; matches ^[A-Za-z0-9._~:/+=-]{1,128}$

capacity

POST /api/compute/pools/capacity

Returns one pool's rollup rows, one per resource; the same answer as capacity.byPool.

The call is NOT_FOUND when the pool is not visible to the tenant.

  • Kind: read
  • Authorization: compute:capacity:read @ compute-pool
  • Module: capacity
  • Phase: v0.1 (registered)

Input

FieldTypeRequiredConstraints
tenantIdstringyesat most 128 characters; matches ^[A-Za-z0-9._:-]{1,128}$
poolIdstringyesat most 57 characters; matches ^pool_[0-9a-hjkmnp-tv-z]{26,52}$

offer

POST /api/compute/pools/offer

Offers a pool the tenant owns to another tenant with a quota, or updates an existing offer and its quota; returns the pool as that tenant sees it.

  • quota creates or resizes the offered tenant's quota rows. A new maximum below what is in use is raised to the amount in use.
  • includeDescendants and priority (default 0) are stored with the offer.
  • INVALID_STATE when the pool is archived, when a timeslice or mps pool or a pool holding tenant-owned nodes is offered to anyone but its owner, or when a policy.singleTenant pool is offered with includeDescendants or is already offered to another tenant.
  • The pool's IAM authz row is written for the offered tenant, with the attributes gpuModel, class, sharing, region and owned.

Emits pool.offered.

  • Kind: mutation
  • Authorization: compute:pools:share @ compute-pool
  • Module: capacity
  • Phase: v0.1 (registered)

Input

FieldTypeRequiredConstraints
tenantIdstringyesat most 128 characters; matches ^[A-Za-z0-9._:-]{1,128}$
poolIdstringyesat most 57 characters; matches ^pool_[0-9a-hjkmnp-tv-z]{26,52}$
toTenantIdstringyesat most 128 characters; matches ^[A-Za-z0-9._:-]{1,128}$
quotamap of integeryeskeys match ^[A-Za-z][A-Za-z0-9._-]{0,63}$
includeDescendantsbooleandefault false
priorityinteger-1000-1000

unoffer

POST /api/compute/pools/unoffer

Withdraws a pool's offer from a tenant and returns whether an offer was removed.

That tenant's quota rows on the pool drop to what is in use, so live reservations keep their bookings while nothing new fits, and its authz row for the pool is removed. A pool cannot be unoffered from its owner (INVALID_INPUT). Calling it again answers removed: false. Emits pool.unoffered only when an offer was removed.

  • Kind: mutation
  • Authorization: compute:pools:share @ compute-pool
  • Module: capacity
  • Phase: v0.1 (registered)

Input

FieldTypeRequiredConstraints
tenantIdstringyesat most 128 characters; matches ^[A-Za-z0-9._:-]{1,128}$
poolIdstringyesat most 57 characters; matches ^pool_[0-9a-hjkmnp-tv-z]{26,52}$
toTenantIdstringyesat most 128 characters; matches ^[A-Za-z0-9._:-]{1,128}$

update

POST /api/compute/pools/update

Replaces the policy, the GPU model, or both, of a pool the tenant owns, and returns the pool with its version incremented.

  • The new policy replaces the old one as a whole, and is checked as on create: the pool-policy validators, and platformOperated for a platform site's Kubernetes join. A request with neither field is INVALID_INPUT. Class, site, sharing mode and agent cannot change.
  • Turning policy.singleTenant on is INVALID_STATE while more than one tenant, or any tenant with includeDescendants, holds an offer.
  • A new migLayout in a mig pool never repartitions booked GPUs; each node takes the new layout once its GPUs are idle. A change to prewarmImages refreshes the desired state of the site's agents.
  • The pool's authz rows are refreshed for the owner and every offered tenant.

Emits pool.updated.

  • Kind: mutation
  • Authorization: compute:pools:manage @ compute-pool
  • Module: capacity
  • Phase: v0.2 (registered)

Input

FieldTypeRequiredConstraints
tenantIdstringyesat most 128 characters; matches ^[A-Za-z0-9._:-]{1,128}$
poolIdstringyesat most 57 characters; matches ^pool_[0-9a-hjkmnp-tv-z]{26,52}$
policyobject
gpuModelstringat most 32 characters; matches ^[A-Za-z0-9-]{1,32}$

archive

POST /api/compute/pools/archive

Retires a pool the tenant owns: it removes every offer and stops new work, while live reservations keep their bookings until they end.

Each offered tenant's quota rows drop to what is in use and its authz row for the pool is removed. After archiving, only the owner sees the pool, with archived: true. Archiving an archived pool returns it unchanged. Emits pool.archived with the list of tenants whose offers were removed.

  • Kind: mutation
  • Authorization: compute:pools:manage @ compute-pool
  • Module: capacity
  • Phase: v0.2 (registered)

Input

FieldTypeRequiredConstraints
tenantIdstringyesat most 128 characters; matches ^[A-Za-z0-9._:-]{1,128}$
poolIdstringyesat most 57 characters; matches ^pool_[0-9a-hjkmnp-tv-z]{26,52}$

Was this page helpful?

Better Compute is created by Sean Filimon

Last updated

nodes

Nodes are machines that joined the control plane, as their tenant sees them: a tenant sees the nodes the authorization projection holds for it. Every method except `list` is decided on `compute-node/{nodeId}`. Mutations take an optional `version`; when the node has moved past it, the call is `CONFLICT`. See [Operating nodes](/docs/guides/nodes/operating-nodes).

profiles

The profiles group stores and checks the versioned recipes that provisioning workflows run: steps, drivers, an image, user data and host config. A version becomes immutable the first time a workflow uses it. Lookups see the tenant's own profiles, public ones, and the read-only profiles that modules ship under the tenant `builtin`. See [Profiles and images](/docs/guides/bare-metal/profiles-and-images).

On this page

listgetcreatecapacityofferunofferupdatearchive
Edit this page Report an issue