Upgrade a cluster's Kubernetes version
const url = 'https://api.aetherplatform.cloud/api/v1/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/upgrade';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"target_version":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.aetherplatform.cloud/api/v1/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/upgrade \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "target_version": "example" }'Initiates a Kubernetes version upgrade across the control plane and worker node pools. Upgrades must be incremental: a patch bump on the same minor or a step to exactly the next minor. The cluster must be running.
target_version accepts the same two forms as cluster creation. A bare minor resolves to the latest patch Aether has verified for it; a full MAJOR.MINOR.PATCH is accepted only when its minor is offered by GET /api/v1/k8s-versions and its patch is one this platform has resolved (at or below that minor’s current patch) — otherwise 422 validation_error. When no version is offered at all (upstream release data has never been reachable) the endpoint answers 503.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Organization UUID.
Cluster UUID.
Request Bodyrequired
Section titled “Request Bodyrequired”object
The target Kubernetes version as MAJOR.MINOR (e.g. “1.37”) or full MAJOR.MINOR.PATCH. Bare minors resolve to the latest available patch; a full version is accepted only when its minor is offered by GET /api/v1/k8s-versions and its patch is one this platform has resolved (at or below that minor’s current patch) — otherwise 422 validation_error. Must also be an incremental step from the cluster’s current version: a patch bump on the same minor, or a step to exactly the next minor.
Examplegenerated
{ "target_version": "example"}Responses
Section titled “Responses”Upgrade accepted.
The updated cluster plus worker-rollout counters. When worker patching partially fails, additional fields (workers_pending, workers_error) are present.
object
object
The apiserver URL aether-operator reports for the cluster: the private control-plane proxy address, or the public hostname when public_endpoint is true (which it is on every supported cluster — a cluster without the mandatory public endpoint is an implementation gap, tracked internally as I-14, see public_endpoint). Observed, not derived — null (and omitted from the response) until the cluster has been provisioned far enough for the operator to report one.
The version aether-operator reports once a rollout settles.
Read-only. The Cluster API object name for this cluster, which is also the name of its TenantCluster and the kubeconfig context name. For clusters created after the random suffix was introduced it is <organization slug>-<name>-<6 lowercase alphanumerics>; older clusters keep <organization slug>-<name>. It is stored once at create time and never recomputed, so it does not change if the organization slug later differs.
The per-cluster worker /24 (read-only; allocated at create time).
Whether this cluster’s apiserver is exposed on a public IPv4 and DNS name in addition to the private control-plane proxy path. Every cluster is required to have one: the public API endpoint is mandatory, billed at the published monthly rate for public_ip (€4 at the time of writing; the current rate is shown in the portal and, once published, on the pricing page) as a flat month with no proration, locked the first time the billing sampler observes the address — one line per cluster per month, see SubscriptionLine.kind public_ip. Set at create time and immutable afterwards; sending a different value to updateCluster is rejected with 422 public_endpoint/immutable. A cluster reading false is an implementation gap (tracked internally as I-14), not a supported configuration: the API still accepts public_endpoint: false at create time, and the resulting cluster has no public address, no endpoint charge and no supported access path. Its apiserver answers only on the cluster’s private network — its own workers and the platform — and in production there is no supported way to reach it from a laptop or a CI pipeline; the kubectl proxy through the platform API (proxy-kubeconfig, not exposed in this reference) is a preview that is switched off in production and, where enabled, reaches private and public clusters alike. Private-network connectivity, which would make the public endpoint optional, is a future capability.
The package this cluster is billed from, as chosen at create time: one of the package slugs in the catalogue (currently dev, starter, growth, scale; a retired slug can still appear on an existing cluster). null (and omitted from the response) means the cluster is billed per resource (“custom”). Immutable — no endpoint changes it.
Example
{ "cluster": { "status": "provisioning" }}Missing or invalid credentials.
object
object
A stable, machine-readable error code.
object
The platform status page (https://status.aetherplatform.cloud). Present on 5xx answers written by the API’s error writer and on no other; absent, not null, on 4xx.
The payment provider’s decline code. Present only on 402 payment_declined; it is its own field and is never folded into message.
Present on exactly these errors of the invoice pay and pay/confirm endpoints: 402 payment_declined, 402 payment_method_required, 409 invoice_already_paid, 409 invoice_not_issued, 409 invoice_below_minimum, 409 payment_not_in_flight, and 409 invoice_void when the void invoice was replaced. It is the id of the live invoice, which after a re-issue is the replacement and not the id in the request URL (on 409 invoice_void from pay/confirm it is the replacement’s id). Absent on every other error — 400 (including discount_code_invalid), 403, 404, the discount_* 409s, 409 invoice_void with no replacement (nothing live to name), every 5xx and 503 code — and never null.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": [ { "field": "example", "code": "example", "message": "example" } ], "status_url": "https://example.com", "decline_code": "example", "invoice_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }}Refused by the organization role policy (see Authorization in the API description). error.code is forbidden when the caller is not a member of the organization (or the API token belongs to another organization), insufficient_role when the caller’s organization role is below the operation’s minimum role, and token_not_permitted when the request was authenticated with an API token on an operation API tokens may not use (the API Tokens operations; the handler-gated operations named in the API description: deleting the organization, changing a member’s role or payment_mode, paying an invoice including its confirm step, and discounts; and for a cluster-pinned machine token every operation except the loadbalancer-ips and loadbalancer-vms operations). email_unverified when a portal user’s e-mail address is not verified (see Authentication).
object
object
A stable, machine-readable error code.
object
The platform status page (https://status.aetherplatform.cloud). Present on 5xx answers written by the API’s error writer and on no other; absent, not null, on 4xx.
The payment provider’s decline code. Present only on 402 payment_declined; it is its own field and is never folded into message.
Present on exactly these errors of the invoice pay and pay/confirm endpoints: 402 payment_declined, 402 payment_method_required, 409 invoice_already_paid, 409 invoice_not_issued, 409 invoice_below_minimum, 409 payment_not_in_flight, and 409 invoice_void when the void invoice was replaced. It is the id of the live invoice, which after a re-issue is the replacement and not the id in the request URL (on 409 invoice_void from pay/confirm it is the replacement’s id). Absent on every other error — 400 (including discount_code_invalid), 403, 404, the discount_* 409s, 409 invoice_void with no replacement (nothing live to name), every 5xx and 503 code — and never null.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": [ { "field": "example", "code": "example", "message": "example" } ], "status_url": "https://example.com", "decline_code": "example", "invoice_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }}The requested resource was not found.
object
object
A stable, machine-readable error code.
object
The platform status page (https://status.aetherplatform.cloud). Present on 5xx answers written by the API’s error writer and on no other; absent, not null, on 4xx.
The payment provider’s decline code. Present only on 402 payment_declined; it is its own field and is never folded into message.
Present on exactly these errors of the invoice pay and pay/confirm endpoints: 402 payment_declined, 402 payment_method_required, 409 invoice_already_paid, 409 invoice_not_issued, 409 invoice_below_minimum, 409 payment_not_in_flight, and 409 invoice_void when the void invoice was replaced. It is the id of the live invoice, which after a re-issue is the replacement and not the id in the request URL (on 409 invoice_void from pay/confirm it is the replacement’s id). Absent on every other error — 400 (including discount_code_invalid), 403, 404, the discount_* 409s, 409 invoice_void with no replacement (nothing live to name), every 5xx and 503 code — and never null.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": [ { "field": "example", "code": "example", "message": "example" } ], "status_url": "https://example.com", "decline_code": "example", "invoice_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }}The cluster is not in a state that permits upgrade.
object
object
A stable, machine-readable error code.
object
The platform status page (https://status.aetherplatform.cloud). Present on 5xx answers written by the API’s error writer and on no other; absent, not null, on 4xx.
The payment provider’s decline code. Present only on 402 payment_declined; it is its own field and is never folded into message.
Present on exactly these errors of the invoice pay and pay/confirm endpoints: 402 payment_declined, 402 payment_method_required, 409 invoice_already_paid, 409 invoice_not_issued, 409 invoice_below_minimum, 409 payment_not_in_flight, and 409 invoice_void when the void invoice was replaced. It is the id of the live invoice, which after a re-issue is the replacement and not the id in the request URL (on 409 invoice_void from pay/confirm it is the replacement’s id). Absent on every other error — 400 (including discount_code_invalid), 403, 404, the discount_* 409s, 409 invoice_void with no replacement (nothing live to name), every 5xx and 503 code — and never null.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": [ { "field": "example", "code": "example", "message": "example" } ], "status_url": "https://example.com", "decline_code": "example", "invoice_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }}Request validation failed.
object
object
A stable, machine-readable error code.
object
The platform status page (https://status.aetherplatform.cloud). Present on 5xx answers written by the API’s error writer and on no other; absent, not null, on 4xx.
The payment provider’s decline code. Present only on 402 payment_declined; it is its own field and is never folded into message.
Present on exactly these errors of the invoice pay and pay/confirm endpoints: 402 payment_declined, 402 payment_method_required, 409 invoice_already_paid, 409 invoice_not_issued, 409 invoice_below_minimum, 409 payment_not_in_flight, and 409 invoice_void when the void invoice was replaced. It is the id of the live invoice, which after a re-issue is the replacement and not the id in the request URL (on 409 invoice_void from pay/confirm it is the replacement’s id). Absent on every other error — 400 (including discount_code_invalid), 403, 404, the discount_* 409s, 409 invoice_void with no replacement (nothing live to name), every 5xx and 503 code — and never null.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": [ { "field": "example", "code": "example", "message": "example" } ], "status_url": "https://example.com", "decline_code": "example", "invoice_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }}A required backend dependency is unavailable.
object
object
A stable, machine-readable error code.
object
The platform status page (https://status.aetherplatform.cloud). Present on 5xx answers written by the API’s error writer and on no other; absent, not null, on 4xx.
The payment provider’s decline code. Present only on 402 payment_declined; it is its own field and is never folded into message.
Present on exactly these errors of the invoice pay and pay/confirm endpoints: 402 payment_declined, 402 payment_method_required, 409 invoice_already_paid, 409 invoice_not_issued, 409 invoice_below_minimum, 409 payment_not_in_flight, and 409 invoice_void when the void invoice was replaced. It is the id of the live invoice, which after a re-issue is the replacement and not the id in the request URL (on 409 invoice_void from pay/confirm it is the replacement’s id). Absent on every other error — 400 (including discount_code_invalid), 403, 404, the discount_* 409s, 409 invoice_void with no replacement (nothing live to name), every 5xx and 503 code — and never null.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": [ { "field": "example", "code": "example", "message": "example" } ], "status_url": "https://example.com", "decline_code": "example", "invoice_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }}