kubernetesNodePools
Node pools are the groups of worker nodes of a `standard` Kubernetes cluster ([kubernetesClusters](/docs/reference/api/kubernetes-clusters)); an `autopilot` cluster has none, because the provider runs its nodes. A cluster's first node pools are created with it; these calls add, resize and remove pools later. Every call records what the tenant wants and returns at once: the node pool shows `pending`, `ready`, `updating`, `deleting`, `deleted` or `error` (with a `message`), and its cluster goes `updating` until the reconciler has converged the change, then `ready` again. A node pool the provider refuses is `error`, and so is its cluster, with the pool named in its `message`, until the pool is changed or deleted. The reconciler publishes `kubernetes.nodepool.ready`, `kubernetes.nodepool.error` and `kubernetes.nodepool.deleted` on the cluster's subject. A node pool's name is also its provider-side name.
Node pools are the groups of worker nodes of a standard Kubernetes cluster (kubernetesClusters); an autopilot cluster has none, because the provider runs its nodes. A cluster's first node pools are created with it; these calls add, resize and remove pools later. Every call records what the tenant wants and returns at once: the node pool shows pending, ready, updating, deleting, deleted or error (with a message), and its cluster goes updating until the reconciler has converged the change, then ready again. A node pool the provider refuses is error, and so is its cluster, with the pool named in its message, until the pool is changed or deleted. The reconciler publishes kubernetes.nodepool.ready, kubernetes.nodepool.error and kubernetes.nodepool.deleted on the cluster's subject. A node pool's name is also its provider-side name.
All 4 methods are served by @better-compute/server 0.3.0.
| Method | Kind | Authorization | Phase | Status |
|---|---|---|---|---|
create | mutation | compute:kubernetes:update @ compute-kubernetes-cluster | v1.0 | registered |
list | read | compute:kubernetes:read @ compute-kubernetes-cluster | v1.0 | registered |
update | mutation | compute:kubernetes:update @ compute-kubernetes-cluster | v1.0 | registered |
delete | mutation | compute:kubernetes:update @ compute-kubernetes-cluster | v1.0 | registered |
create
POST /api/compute/kubernetesNodePools/create
Adds a node pool to a standard cluster that is not being deleted and returns it pending (INVALID_STATE for an autopilot cluster or one being deleted).
nameis 1 to 40 characters,[a-z]([-a-z0-9]*[a-z0-9])?, unique among the cluster's node pools that are not deleted (CONFLICT); a deleted pool's name is free again.machineTypeis the provider's machine type (e2-standard-4).nodeCount(0 to 1000) is nodes per zone of the pool; withautoscaling(minNodes0 to 1000 not abovemaxNodes1 to 1000) it is the initial count.- Optional:
diskGiB(10 to 65536) anddiskType(pd-balanced),spot,accelerators({ type: 'nvidia-l4', count }, 1 to 16 per node),zones(at most 10, zones of the cluster's region and of the account), Kuberneteslabels(at most 32) andtaints(at most 32, effectNoSchedule,PreferNoScheduleorNoExecute). - A cluster has at most 10 node pools that are not deleted (
QUOTA_EXCEEDED). - With an
idempotencyKey(scoped to the tenant, the caller and the cluster) a retry returns the same node pool; the same key with another request isCONFLICT.
Publishes kubernetes.nodepool.created. Decided as compute:kubernetes:update on the cluster.
- Kind: mutation
- Authorization:
compute:kubernetes:update@compute-kubernetes-cluster - Module:
kubernetes - Phase: v1.0 (registered)
Input
| Field | Type | Required | Constraints |
|---|---|---|---|
tenantId | string | yes | at most 128 characters; matches ^[A-Za-z0-9._:-]{1,128}$ |
clusterId | string | yes | at most 56 characters; matches ^kcl_[0-9a-hjkmnp-tv-z]{26,52}$ |
name | string | yes | at most 40 characters; matches ^[a-z]([-a-z0-9]{0,38}[a-z0-9])?$ |
machineType | string | yes | at most 63 characters; matches ^[a-z0-9][a-z0-9.-]{0,62}$ |
nodeCount | integer | yes | 0-1000 |
autoscaling | object | ||
autoscaling.minNodes | integer | yes | 0-1000 |
autoscaling.maxNodes | integer | yes | 1-1000 |
diskGiB | integer | 10-65536 | |
diskType | string | matches ^[a-z][a-z0-9-]{1,40}$ | |
spot | boolean | default false | |
accelerators | object | ||
accelerators.type | string | yes | matches ^[a-z0-9][a-z0-9-]{0,62}$ |
accelerators.count | integer | yes | 1-16 |
zones | list of string | 0-10 items | |
labels | map of string | ||
taints | list of object | 0-32 items | |
taints[].key | string | yes | |
taints[].value | string | at most 63 characters | |
taints[].effect | one of NoSchedule, PreferNoSchedule, NoExecute | yes | |
idempotencyKey | string | at most 128 characters; matches ^[A-Za-z0-9._:-]{1,128}$ |
list
POST /api/compute/kubernetesNodePools/list
Returns the cluster's node pools that are not deleted. Decided as compute:kubernetes:read on the cluster.
- Kind: read
- Authorization:
compute:kubernetes:read@compute-kubernetes-cluster - Module:
kubernetes - Phase: v1.0 (registered)
Input
| Field | Type | Required | Constraints |
|---|---|---|---|
tenantId | string | yes | at most 128 characters; matches ^[A-Za-z0-9._:-]{1,128}$ |
clusterId | string | yes | at most 56 characters; matches ^kcl_[0-9a-hjkmnp-tv-z]{26,52}$ |
update
POST /api/compute/kubernetesNodePools/update
Resizes a node pool in place: nodeCount, and autoscaling (null turns it off); name at least one. A nodeCount outside the pool's autoscaling bounds is INVALID_INPUT. The machine type, disks, accelerators, zones, labels and taints never change: delete the pool and create another. The pool goes updating (bumping its version) until the provider has resized it. A pool or cluster being deleted is INVALID_STATE. Decided as compute:kubernetes:update on the cluster.
- Kind: mutation
- Authorization:
compute:kubernetes:update@compute-kubernetes-cluster - Module:
kubernetes - Phase: v1.0 (registered)
Input
| Field | Type | Required | Constraints |
|---|---|---|---|
tenantId | string | yes | at most 128 characters; matches ^[A-Za-z0-9._:-]{1,128}$ |
clusterId | string | yes | at most 56 characters; matches ^kcl_[0-9a-hjkmnp-tv-z]{26,52}$ |
nodePoolId | string | yes | at most 56 characters; matches ^knp_[0-9a-hjkmnp-tv-z]{26,52}$ |
nodeCount | integer | 0-1000 | |
autoscaling | object,null |
delete
POST /api/compute/kubernetesNodePools/delete
Marks the node pool for deletion and returns it deleting; the reconciler deletes it at the provider, and it is then deleted and gone from list. Deleting a pool that is being deleted returns it unchanged. Decided as compute:kubernetes:update on the cluster.
- Kind: mutation
- Authorization:
compute:kubernetes:update@compute-kubernetes-cluster - Module:
kubernetes - Phase: v1.0 (registered)
Input
| Field | Type | Required | Constraints |
|---|---|---|---|
tenantId | string | yes | at most 128 characters; matches ^[A-Za-z0-9._:-]{1,128}$ |
clusterId | string | yes | at most 56 characters; matches ^kcl_[0-9a-hjkmnp-tv-z]{26,52}$ |
nodePoolId | string | yes | at most 56 characters; matches ^knp_[0-9a-hjkmnp-tv-z]{26,52}$ |
Better Compute is created by Sean Filimon
Last updated
kubernetesClusters
Kubernetes clusters are managed Kubernetes clusters (Google Kubernetes Engine, Standard and Autopilot) on a provider account, served by the `@better-compute/kubernetes` module. The provider runs the control plane; better-compute never runs one itself. A cluster belongs to one provider pool, so to that pool's account, and the account's provider must provide managed Kubernetes (a provider that does not is `UNSUPPORTED`). Two hosting models use the same calls: a platform account's pool offered to the tenant (the cluster lives in the platform's cloud project), or a pool on the tenant's own account (the cluster lives in the tenant's project). The calls record what the tenant wants and return at once; the `kubernetes.clusters` reconciler then creates the cluster at the provider, its node pools once the control plane is up, applies changes in place and deletes what the tenant deleted. `state` shows where it is: `pending`, `provisioning`, `ready` (the control plane and every node pool are ready), `updating`, `deleting`, `deleted` or `error` (with a `message`). The reconciler publishes `kubernetes.cluster.ready` the first time, `kubernetes.cluster.updated` when it is ready again after a change or the provider moved it to another version (a release-channel upgrade), `kubernetes.cluster.error` and `kubernetes.cluster.deleted`. Clusters still converging are looked at every 30 seconds; ready and failed ones are refreshed every five minutes, which retries an error and picks up what changed at the provider.
kubernetesSubstrates
A pool substrate is the managed Kubernetes cluster behind a pool whose policy has a `substrate` (`kind: 'kubernetes'`, an `account`, and `cluster: { create }` or `cluster: { adopt }`). The `kubernetes.substrates` reconciler records it here: it creates the cluster with one node pool per flavor (or adopts an existing cluster and adds the flavors' node pools to it, named `bc-<pool>-<flavor>` so they never collide with the tenant's own pools), server-side applies bcd's DaemonSet with a hosted join token, and the cluster's Nodes join the pool. Every object it applies carries the label `better-compute.dev/substrate-pool=<pool id>`; on an adopted cluster an object of the same name it did not create is never taken over or deleted. There is nothing to call to create or delete a substrate: change the pool's policy, or archive the pool to tear it down.