AnkraDocs
Console

API reference · Managed services

Managed Kubernetes

20 operations of the Ankra Cloud API: Managed Kubernetes - clusters whose control plane is a vCluster Ankra runs on the region's host cluster, their node pools of servers in your account, kubeconfigs and OIDC tokens, etcd snapshots, and the operator's regional host clusters.

List Kubernetes clusters#

GET/v1/kubernetes-clusters
Operation
list_kubernetes_clusters
Credentials
API token, Portal session
Requires
Permission read

Newest first, without node pools; get one for those.

Parameters

Parameters
NameInTypeDescription
cursorquerystringThe next_cursor of the previous page.
limitqueryintegerPage size; the server applies its default and maximum.

Responses

200One page of clusters.application/json

200 response fields
FieldTypeDescription
itemsrequiredarray of KubernetesCluster
idrequiredstring
zonerequiredstring
regionrequiredstring
namerequiredstring
versionrequiredstringThe minor, e.g. 1.36.
kubernetes_versionrequiredstringThe patch release the control plane runs, e.g. v1.36.5.
available_upgraderequiredstring | nullThe next minor this cluster can upgrade to.
staterequiredstringOne of creating, running, upgrading, restoring, error, deleting, deleted
network_idrequiredstring
control_planerequiredstringWhat a cluster's control plane is built for. development: one API server and etcd replica, no control-plane fee, the nodes are the whole bill; an upgrade or a host node failure interrupts the API. production: three replicas with embedded etcd quorum spread across host nodes, the monthly control-plane fee. The tier is chosen at create and does not change in place.One of development, production
control_plane_replicasrequiredintegerAPI server and embedded etcd replicas the control plane runs.
control_plane_price_monthly_centsrequiredintegerThe tier's control-plane fee per month, billed per hour; 0 for development. The IPv4 endpoint add-on is on top.
production_recommendedrequiredbooleanFalse for a development control plane: no high availability, no service level.
public_ipv4requiredboolean
private_endpointrequiredboolean
endpointrequiredstring | nullThe API server URL on IPv6; null until the control plane is up.
endpoint_ipv4requiredstring | nullThe API server URL on IPv4, with the add-on.
oidc_issuer_urlrequiredstring
labelsrequiredLabelsKeys of 1-63 letters, digits, ., _, / or -, starting and ending with a letter or digit; values of at most 255 printable characters. On a server, keys under kubernetes.ankra.cloud/ and playground.ankra.cloud/ are set by the platform only.
healthrequiredKubernetesHealth
api_serverrequiredstringOne of healthy, unhealthy, unknown
etcd_members_readyrequiredinteger
etcd_members_totalrequiredinteger
has_etcd_quorumrequiredboolean
nodes_readyrequiredinteger
nodes_totalrequiredinteger
observed_atrequiredstring (date-time) | null
detailrequiredstring
addonsrequiredarray of KubernetesAddon
namerequiredstring
versionrequiredstringThe pinned Helm chart version.
etcd_snapshot_schedulerequiredstring
etcd_snapshot_retentionrequiredinteger
node_poolsarray of KubernetesNodePoolOnly on get_kubernetes_cluster.
idrequiredstring
cluster_idrequiredstring
namerequiredstring
planrequiredstring
countrequiredinteger
zonesrequiredarray of string
labelsrequiredLabelsKeys of 1-63 letters, digits, ., _, / or -, starting and ending with a letter or digit; values of at most 255 printable characters. On a server, keys under kubernetes.ankra.cloud/ and playground.ankra.cloud/ are set by the platform only.
taintsrequiredarray of KubernetesTaint
keyrequiredstring
valuestring
effectrequiredstringOne of NoSchedule, PreferNoSchedule, NoExecute
autoscalingrequiredKubernetesAutoscaling | null
minrequiredinteger
maxrequiredinteger
public_ipv4requiredboolean
versionrequiredstringThe minor its nodes run or are rolling to.
staterequiredstringOne of creating, running, scaling, upgrading, deleting, deleted, error
nodesrequiredarray of KubernetesNode
server_idrequiredstring
hostnamerequiredstring
zonerequiredstring
staterequiredstringThe server's state.
is_readyrequiredbooleanThe node reports Ready to the cluster.
kubelet_versionrequiredstringEmpty until the node joined.
public_ipv6requiredstring | null
public_ipv4requiredstring | null
active_operationrequiredOperation | null
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
created_atrequiredstring (date-time)
platformrequiredKubernetesPlatformRegistrationThe cluster's registration in the Ankra platform (ADR 0006). url is the cluster's page in the platform once registered; reason says why it is not registered otherwise (unlinked: link an Ankra organisation to the account first).
staterequiredstringOne of pending, unlinked, registered, failed, deregistered
organisation_idrequiredstring | null
cluster_idrequiredstring | nullThe platform's identifier of the cluster.
urlrequiredstring | null
reasonrequiredstring
next_attempt_atrequiredstring (date-time) | nullWhen a pending registration is tried again.
registered_atrequiredstring (date-time) | null
active_operationrequiredOperation | null
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
created_atrequiredstring (date-time)
next_cursorrequiredstring | null
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/kubernetes-clusters' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Create a managed Kubernetes cluster#

POST/v1/kubernetes-clusters
Operation
create_kubernetes_cluster
Credentials
API token, Portal session
Requires
Permission operate

The control plane is a vCluster that Ankra runs on the region's host cluster, in the tier control_plane names: production (the default) runs three API server replicas with embedded etcd spread across host nodes and zones and is billed per hour at its monthly price; development runs one replica, has no fee and is for development, test and preview clusters, where an upgrade or a host node failure interrupts the API. Both keep etcd on replicated ankra-standard volumes, snapshotted to object storage every six hours, and the tier does not change in place. A region whose host cluster is a development host (region_control_planes of list_kubernetes_versions; no Ankra Storage in its zone yet) offers development only, defaults to it and keeps its etcd on a single-node local volume; production answers 400 there. The cluster's worker nodes are servers in your account, created by its node pools (node_pools here creates them with the cluster) and billed as servers whatever the tier. The API endpoint is always served on IPv6; public_ipv4 adds an IPv4 address (a paid add-on). private_endpoint is not available yet and answers 400. The tiers and their prices are control_planes of list_kubernetes_versions. An account may hold 5 clusters. Every node joins network_id, so a node pool runs in the zones that network reaches: a regional network (see update_network) lets a pool spread across the zones of the region, and a pool whose zones name a zone the network does not reach answers 422, because pods on a node outside it would have no route to the others.

Parameters

Parameters
NameInTypeDescription
Idempotency-KeyheaderstringA key the client chooses for this create, for example a UUID. The same create sent again with the same key within 24 hours answers the first one's answer with Idempotent-Replayed: true and creates nothing. 409 with reason: idempotency_key_in_progress while the first request is still running (try again shortly), with reason: idempotency_key_outcome_unknown when the first request answered 5xx or never finished (the create may or may not exist: list the resource before creating again with a new key), or with reason: idempotency_key_answer_not_stored when the create succeeded but its answer could not be kept (read the resource). 422 with reason: idempotency_key_reused when the key was used with a different request, 400 when the key is not 1 to 255 visible ASCII characters. Only a 4xx answer frees a key before the 24 hours.

Request bodyapplication/json

Request body fields
FieldTypeDescription
zonerequiredstringThe zone the node pools default to; its region hosts the control plane.
namerequiredstringDNS label, 2 to 40 characters.
network_idrequiredstringThe private network every node joins.
versionstringA minor from list_kubernetes_versions; defaults to the newest.
control_planestringThe control-plane tier, from control_planes of list_kubernetes_versions; defaults to production. It does not change in place.One of development, production
public_ipv4booleanServe the API on IPv4 too (paid add-on). Default false: IPv6 only.
private_endpointbooleanNot available yet; true answers 400.
labelsLabelsKeys of 1-63 letters, digits, ., _, / or -, starting and ending with a letter or digit; values of at most 255 printable characters. On a server, keys under kubernetes.ankra.cloud/ and playground.ankra.cloud/ are set by the platform only.
node_poolsarray of KubernetesNodePoolRequest
namerequiredstring
planrequiredstringA server plan from list_plans.
countrequiredinteger
zonesarray of stringZones of the cluster's region to spread nodes across, each one the cluster's private network reaches (another answers 422); defaults to the cluster's zone.
labelsLabelsKeys of 1-63 letters, digits, ., _, / or -, starting and ending with a letter or digit; values of at most 255 printable characters. On a server, keys under kubernetes.ankra.cloud/ and playground.ankra.cloud/ are set by the platform only.
taintsarray of KubernetesTaint
keyrequiredstring
valuestring
effectrequiredstringOne of NoSchedule, PreferNoSchedule, NoExecute
autoscalingKubernetesAutoscaling | null
minrequiredinteger
maxrequiredinteger
public_ipv4booleanGive every node a public IPv4 too (the server add-on). Default false.

Responses

202The cluster, its kubernetes_cluster.create operation and the node pools created with it.application/json

202 response fields
FieldTypeDescription
kubernetes_clusterrequiredKubernetesCluster
idrequiredstring
zonerequiredstring
regionrequiredstring
namerequiredstring
versionrequiredstringThe minor, e.g. 1.36.
kubernetes_versionrequiredstringThe patch release the control plane runs, e.g. v1.36.5.
available_upgraderequiredstring | nullThe next minor this cluster can upgrade to.
staterequiredstringOne of creating, running, upgrading, restoring, error, deleting, deleted
network_idrequiredstring
control_planerequiredstringWhat a cluster's control plane is built for. development: one API server and etcd replica, no control-plane fee, the nodes are the whole bill; an upgrade or a host node failure interrupts the API. production: three replicas with embedded etcd quorum spread across host nodes, the monthly control-plane fee. The tier is chosen at create and does not change in place.One of development, production
control_plane_replicasrequiredintegerAPI server and embedded etcd replicas the control plane runs.
control_plane_price_monthly_centsrequiredintegerThe tier's control-plane fee per month, billed per hour; 0 for development. The IPv4 endpoint add-on is on top.
production_recommendedrequiredbooleanFalse for a development control plane: no high availability, no service level.
public_ipv4requiredboolean
private_endpointrequiredboolean
endpointrequiredstring | nullThe API server URL on IPv6; null until the control plane is up.
endpoint_ipv4requiredstring | nullThe API server URL on IPv4, with the add-on.
oidc_issuer_urlrequiredstring
labelsrequiredLabelsKeys of 1-63 letters, digits, ., _, / or -, starting and ending with a letter or digit; values of at most 255 printable characters. On a server, keys under kubernetes.ankra.cloud/ and playground.ankra.cloud/ are set by the platform only.
healthrequiredKubernetesHealth
api_serverrequiredstringOne of healthy, unhealthy, unknown
etcd_members_readyrequiredinteger
etcd_members_totalrequiredinteger
has_etcd_quorumrequiredboolean
nodes_readyrequiredinteger
nodes_totalrequiredinteger
observed_atrequiredstring (date-time) | null
detailrequiredstring
addonsrequiredarray of KubernetesAddon
namerequiredstring
versionrequiredstringThe pinned Helm chart version.
etcd_snapshot_schedulerequiredstring
etcd_snapshot_retentionrequiredinteger
node_poolsarray of KubernetesNodePoolOnly on get_kubernetes_cluster.
idrequiredstring
cluster_idrequiredstring
namerequiredstring
planrequiredstring
countrequiredinteger
zonesrequiredarray of string
labelsrequiredLabelsKeys of 1-63 letters, digits, ., _, / or -, starting and ending with a letter or digit; values of at most 255 printable characters. On a server, keys under kubernetes.ankra.cloud/ and playground.ankra.cloud/ are set by the platform only.
taintsrequiredarray of KubernetesTaint
keyrequiredstring
valuestring
effectrequiredstringOne of NoSchedule, PreferNoSchedule, NoExecute
autoscalingrequiredKubernetesAutoscaling | null
minrequiredinteger
maxrequiredinteger
public_ipv4requiredboolean
versionrequiredstringThe minor its nodes run or are rolling to.
staterequiredstringOne of creating, running, scaling, upgrading, deleting, deleted, error
nodesrequiredarray of KubernetesNode
server_idrequiredstring
hostnamerequiredstring
zonerequiredstring
staterequiredstringThe server's state.
is_readyrequiredbooleanThe node reports Ready to the cluster.
kubelet_versionrequiredstringEmpty until the node joined.
public_ipv6requiredstring | null
public_ipv4requiredstring | null
active_operationrequiredOperation | null
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
created_atrequiredstring (date-time)
platformrequiredKubernetesPlatformRegistrationThe cluster's registration in the Ankra platform (ADR 0006). url is the cluster's page in the platform once registered; reason says why it is not registered otherwise (unlinked: link an Ankra organisation to the account first).
staterequiredstringOne of pending, unlinked, registered, failed, deregistered
organisation_idrequiredstring | null
cluster_idrequiredstring | nullThe platform's identifier of the cluster.
urlrequiredstring | null
reasonrequiredstring
next_attempt_atrequiredstring (date-time) | nullWhen a pending registration is tried again.
registered_atrequiredstring (date-time) | null
active_operationrequiredOperation | null
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
created_atrequiredstring (date-time)
operationrequiredOperation
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 402The account may not create this. reason is payment_method_required while it has no default payment method and its credit does not cover the create: the credit left must cover one month, at monthly list prices, of everything the account already runs plus what the create adds (add a payment method through POST /v1/account/billing/setup-session, or free what the account no longer needs); owner_approval_required while its owner has not approved paid usage and no credit is left; or account_suspended while an invoice is overdue past the grace period (pay it) or Ankra staff suspended the account (contact support). A prepaid account (linked to an Ankra platform organisation) is refused with payment_method_required while it has no card, and with credit_required once it has one but its credit does not cover the create: Cloud never charges its card, so only a top-up on the Ankra platform lifts it, and top_up_url names that page when Cloud knows it. GET /v1/account/billing reports the same standing. For payment_method_required and credit_required, detail names what the create costs, the credit left and the committed monthly spend only to a principal that may read billing (billing.read, and for an API token a scope that includes it); anyone else is told only that the credit does not cover it.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 422A node pool names a zone its cluster's private network does not reach (detail names the pool, the zone and the network), or the account would exceed a quota (detail names the limit).
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • 503No capacity or address is free in the zone right now (reason: capacity_unavailable, with availability wording in detail), or a host did not answer; try another plan or zone, or try again later.
  • defaultAny other error, usually 500.

Example

bash
curl -X POST 'https://cloud.ankra.app/v1/kubernetes-clusters' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "zone": "string",
  "name": "string",
  "network_id": "string"
}'

Get a Kubernetes cluster with its node pools and health#

GET/v1/kubernetes-clusters/{id}
Operation
get_kubernetes_cluster
Credentials
API token, Portal session
Requires
Permission read

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

200The cluster.application/json

200 response fields
FieldTypeDescription
kubernetes_clusterrequiredKubernetesCluster
idrequiredstring
zonerequiredstring
regionrequiredstring
namerequiredstring
versionrequiredstringThe minor, e.g. 1.36.
kubernetes_versionrequiredstringThe patch release the control plane runs, e.g. v1.36.5.
available_upgraderequiredstring | nullThe next minor this cluster can upgrade to.
staterequiredstringOne of creating, running, upgrading, restoring, error, deleting, deleted
network_idrequiredstring
control_planerequiredstringWhat a cluster's control plane is built for. development: one API server and etcd replica, no control-plane fee, the nodes are the whole bill; an upgrade or a host node failure interrupts the API. production: three replicas with embedded etcd quorum spread across host nodes, the monthly control-plane fee. The tier is chosen at create and does not change in place.One of development, production
control_plane_replicasrequiredintegerAPI server and embedded etcd replicas the control plane runs.
control_plane_price_monthly_centsrequiredintegerThe tier's control-plane fee per month, billed per hour; 0 for development. The IPv4 endpoint add-on is on top.
production_recommendedrequiredbooleanFalse for a development control plane: no high availability, no service level.
public_ipv4requiredboolean
private_endpointrequiredboolean
endpointrequiredstring | nullThe API server URL on IPv6; null until the control plane is up.
endpoint_ipv4requiredstring | nullThe API server URL on IPv4, with the add-on.
oidc_issuer_urlrequiredstring
labelsrequiredLabelsKeys of 1-63 letters, digits, ., _, / or -, starting and ending with a letter or digit; values of at most 255 printable characters. On a server, keys under kubernetes.ankra.cloud/ and playground.ankra.cloud/ are set by the platform only.
healthrequiredKubernetesHealth
api_serverrequiredstringOne of healthy, unhealthy, unknown
etcd_members_readyrequiredinteger
etcd_members_totalrequiredinteger
has_etcd_quorumrequiredboolean
nodes_readyrequiredinteger
nodes_totalrequiredinteger
observed_atrequiredstring (date-time) | null
detailrequiredstring
addonsrequiredarray of KubernetesAddon
namerequiredstring
versionrequiredstringThe pinned Helm chart version.
etcd_snapshot_schedulerequiredstring
etcd_snapshot_retentionrequiredinteger
node_poolsarray of KubernetesNodePoolOnly on get_kubernetes_cluster.
idrequiredstring
cluster_idrequiredstring
namerequiredstring
planrequiredstring
countrequiredinteger
zonesrequiredarray of string
labelsrequiredLabelsKeys of 1-63 letters, digits, ., _, / or -, starting and ending with a letter or digit; values of at most 255 printable characters. On a server, keys under kubernetes.ankra.cloud/ and playground.ankra.cloud/ are set by the platform only.
taintsrequiredarray of KubernetesTaint
keyrequiredstring
valuestring
effectrequiredstringOne of NoSchedule, PreferNoSchedule, NoExecute
autoscalingrequiredKubernetesAutoscaling | null
minrequiredinteger
maxrequiredinteger
public_ipv4requiredboolean
versionrequiredstringThe minor its nodes run or are rolling to.
staterequiredstringOne of creating, running, scaling, upgrading, deleting, deleted, error
nodesrequiredarray of KubernetesNode
server_idrequiredstring
hostnamerequiredstring
zonerequiredstring
staterequiredstringThe server's state.
is_readyrequiredbooleanThe node reports Ready to the cluster.
kubelet_versionrequiredstringEmpty until the node joined.
public_ipv6requiredstring | null
public_ipv4requiredstring | null
active_operationrequiredOperation | null
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
created_atrequiredstring (date-time)
platformrequiredKubernetesPlatformRegistrationThe cluster's registration in the Ankra platform (ADR 0006). url is the cluster's page in the platform once registered; reason says why it is not registered otherwise (unlinked: link an Ankra organisation to the account first).
staterequiredstringOne of pending, unlinked, registered, failed, deregistered
organisation_idrequiredstring | null
cluster_idrequiredstring | nullThe platform's identifier of the cluster.
urlrequiredstring | null
reasonrequiredstring
next_attempt_atrequiredstring (date-time) | nullWhen a pending registration is tried again.
registered_atrequiredstring (date-time) | null
active_operationrequiredOperation | null
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
created_atrequiredstring (date-time)
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/kubernetes-clusters/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Delete a Kubernetes cluster with its nodes, volumes, load balancers and etcd snapshots#

DELETE/v1/kubernetes-clusters/{id}
Operation
delete_kubernetes_cluster
Credentials
API token, Portal session
Requires
Permission operate

Deletes the cluster's Services of type LoadBalancer and PersistentVolumeClaims first, so the cloud controller and the CSI driver remove the load balancers and storages they made, then the nodes, then the control plane and its etcd snapshots. Nothing the cluster created is left behind.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

202Accepted; poll the operation.application/json · OperationEnvelope

202 response fields
FieldTypeDescription
operationrequiredOperation
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X DELETE 'https://cloud.ankra.app/v1/kubernetes-clusters/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

The etcd snapshots of a cluster, newest first#

GET/v1/kubernetes-clusters/{id}/etcd-snapshots
Operation
list_kubernetes_cluster_etcd_snapshots
Credentials
API token, Portal session
Requires
Permission read

Taken every six hours and on request; the newest retention are kept.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

200The snapshots; at most retention are kept, so the list is never paged and next_cursor is always null.application/json

200 response fields
FieldTypeDescription
itemsrequiredarray of KubernetesEtcdSnapshot
namerequiredstring
taken_atrequiredstring (date-time)
size_bytesrequiredinteger
next_cursorrequirednull
schedulerequiredstringCron schedule, UTC.
retentionrequiredinteger
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • 503No capacity or address is free in the zone right now (reason: capacity_unavailable, with availability wording in detail), or a host did not answer; try another plan or zone, or try again later.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/kubernetes-clusters/<id>/etcd-snapshots' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Take an etcd snapshot now#

POST/v1/kubernetes-clusters/{id}/etcd-snapshots
Operation
create_kubernetes_cluster_etcd_snapshot
Credentials
API token, Portal session
Requires
Permission operate

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

202Accepted; poll the operation.application/json · OperationEnvelope

202 response fields
FieldTypeDescription
operationrequiredOperation
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X POST 'https://cloud.ankra.app/v1/kubernetes-clusters/<id>/etcd-snapshots' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

A kubeconfig with a short-lived cluster-admin credential (audited)#

GET/v1/kubernetes-clusters/{id}/kubeconfig
Operation
get_kubernetes_cluster_kubeconfig
Credentials
API token, Portal session
Requires
Permission operate
Note
Reveals a credential or a live view; read-only support sessions are refused.

The admin context holds a service account token bound to cluster-admin that expires at expires_at (8 hours). The oidc context signs you in as yourself instead: its exec credential plugin calls get_kubernetes_cluster_token, and your Ankra role decides your Kubernetes role (owner and admin: cluster-admin, member: edit, viewer: view). Every download is written to the audit log.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

200The kubeconfig.application/json

200 response fields
FieldTypeDescription
kubeconfigrequiredstringThe kubeconfig YAML.
expires_atrequiredstring (date-time)
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • 503No capacity or address is free in the zone right now (reason: capacity_unavailable, with availability wording in detail), or a host did not answer; try another plan or zone, or try again later.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/kubernetes-clusters/<id>/kubeconfig' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

List a cluster's node pools with their nodes#

GET/v1/kubernetes-clusters/{id}/node-pools
Operation
list_kubernetes_node_pools
Credentials
API token, Portal session
Requires
Permission read

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

200Every node pool of the cluster; a cluster has at most 8, so the list is never paged and next_cursor is always null.application/json

200 response fields
FieldTypeDescription
itemsrequiredarray of KubernetesNodePool
idrequiredstring
cluster_idrequiredstring
namerequiredstring
planrequiredstring
countrequiredinteger
zonesrequiredarray of string
labelsrequiredLabelsKeys of 1-63 letters, digits, ., _, / or -, starting and ending with a letter or digit; values of at most 255 printable characters. On a server, keys under kubernetes.ankra.cloud/ and playground.ankra.cloud/ are set by the platform only.
taintsrequiredarray of KubernetesTaint
keyrequiredstring
valuestring
effectrequiredstringOne of NoSchedule, PreferNoSchedule, NoExecute
autoscalingrequiredKubernetesAutoscaling | null
minrequiredinteger
maxrequiredinteger
public_ipv4requiredboolean
versionrequiredstringThe minor its nodes run or are rolling to.
staterequiredstringOne of creating, running, scaling, upgrading, deleting, deleted, error
nodesrequiredarray of KubernetesNode
server_idrequiredstring
hostnamerequiredstring
zonerequiredstring
staterequiredstringThe server's state.
is_readyrequiredbooleanThe node reports Ready to the cluster.
kubelet_versionrequiredstringEmpty until the node joined.
public_ipv6requiredstring | null
public_ipv4requiredstring | null
active_operationrequiredOperation | null
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
created_atrequiredstring (date-time)
next_cursorrequirednull
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/kubernetes-clusters/<id>/node-pools' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Add a node pool to a cluster#

POST/v1/kubernetes-clusters/{id}/node-pools
Operation
create_kubernetes_node_pool
Credentials
API token, Portal session
Requires
Permission operate

Creates count servers of plan in your account (billed as servers), spread across zones, each joining the cluster's private network and the cluster with a short-lived bootstrap token. zones may name the zones of the region that network reaches (update_network extends it): a pool that names another zone answers 422, because pods on a node outside the network would have no route to the others. Nodes are IPv6-first; public_ipv4 gives every node a public IPv4 too (the server add-on). autoscaling is stored for the cluster autoscaler, which is not running yet: the pool keeps count nodes.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring
Idempotency-KeyheaderstringA key the client chooses for this create, for example a UUID. The same create sent again with the same key within 24 hours answers the first one's answer with Idempotent-Replayed: true and creates nothing. 409 with reason: idempotency_key_in_progress while the first request is still running (try again shortly), with reason: idempotency_key_outcome_unknown when the first request answered 5xx or never finished (the create may or may not exist: list the resource before creating again with a new key), or with reason: idempotency_key_answer_not_stored when the create succeeded but its answer could not be kept (read the resource). 422 with reason: idempotency_key_reused when the key was used with a different request, 400 when the key is not 1 to 255 visible ASCII characters. Only a 4xx answer frees a key before the 24 hours.

Request bodyapplication/json · KubernetesNodePoolRequest

Request body fields
FieldTypeDescription
namerequiredstring
planrequiredstringA server plan from list_plans.
countrequiredinteger
zonesarray of stringZones of the cluster's region to spread nodes across, each one the cluster's private network reaches (another answers 422); defaults to the cluster's zone.
labelsLabelsKeys of 1-63 letters, digits, ., _, / or -, starting and ending with a letter or digit; values of at most 255 printable characters. On a server, keys under kubernetes.ankra.cloud/ and playground.ankra.cloud/ are set by the platform only.
taintsarray of KubernetesTaint
keyrequiredstring
valuestring
effectrequiredstringOne of NoSchedule, PreferNoSchedule, NoExecute
autoscalingKubernetesAutoscaling | null
minrequiredinteger
maxrequiredinteger
public_ipv4booleanGive every node a public IPv4 too (the server add-on). Default false.

Responses

202The node pool and its node_pool.sync operation.application/json

202 response fields
FieldTypeDescription
node_poolrequiredKubernetesNodePool
idrequiredstring
cluster_idrequiredstring
namerequiredstring
planrequiredstring
countrequiredinteger
zonesrequiredarray of string
labelsrequiredLabelsKeys of 1-63 letters, digits, ., _, / or -, starting and ending with a letter or digit; values of at most 255 printable characters. On a server, keys under kubernetes.ankra.cloud/ and playground.ankra.cloud/ are set by the platform only.
taintsrequiredarray of KubernetesTaint
keyrequiredstring
valuestring
effectrequiredstringOne of NoSchedule, PreferNoSchedule, NoExecute
autoscalingrequiredKubernetesAutoscaling | null
minrequiredinteger
maxrequiredinteger
public_ipv4requiredboolean
versionrequiredstringThe minor its nodes run or are rolling to.
staterequiredstringOne of creating, running, scaling, upgrading, deleting, deleted, error
nodesrequiredarray of KubernetesNode
server_idrequiredstring
hostnamerequiredstring
zonerequiredstring
staterequiredstringThe server's state.
is_readyrequiredbooleanThe node reports Ready to the cluster.
kubelet_versionrequiredstringEmpty until the node joined.
public_ipv6requiredstring | null
public_ipv4requiredstring | null
active_operationrequiredOperation | null
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
created_atrequiredstring (date-time)
operationrequiredOperation
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 402The account may not create this. reason is payment_method_required while it has no default payment method and its credit does not cover the create: the credit left must cover one month, at monthly list prices, of everything the account already runs plus what the create adds (add a payment method through POST /v1/account/billing/setup-session, or free what the account no longer needs); owner_approval_required while its owner has not approved paid usage and no credit is left; or account_suspended while an invoice is overdue past the grace period (pay it) or Ankra staff suspended the account (contact support). A prepaid account (linked to an Ankra platform organisation) is refused with payment_method_required while it has no card, and with credit_required once it has one but its credit does not cover the create: Cloud never charges its card, so only a top-up on the Ankra platform lifts it, and top_up_url names that page when Cloud knows it. GET /v1/account/billing reports the same standing. For payment_method_required and credit_required, detail names what the create costs, the credit left and the committed monthly spend only to a principal that may read billing (billing.read, and for an API token a scope that includes it); anyone else is told only that the credit does not cover it.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 422A node pool names a zone its cluster's private network does not reach (detail names the pool, the zone and the network), or the account would exceed a quota (detail names the limit).
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X POST 'https://cloud.ankra.app/v1/kubernetes-clusters/<id>/node-pools' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "plan": "string",
  "count": 0
}'

Get a node pool with its nodes#

GET/v1/kubernetes-clusters/{id}/node-pools/{pool}
Operation
get_kubernetes_node_pool
Credentials
API token, Portal session
Requires
Permission read

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring
poolrequiredpathstringThe node pool's id.

Responses

200The node pool.application/json

200 response fields
FieldTypeDescription
node_poolrequiredKubernetesNodePool
idrequiredstring
cluster_idrequiredstring
namerequiredstring
planrequiredstring
countrequiredinteger
zonesrequiredarray of string
labelsrequiredLabelsKeys of 1-63 letters, digits, ., _, / or -, starting and ending with a letter or digit; values of at most 255 printable characters. On a server, keys under kubernetes.ankra.cloud/ and playground.ankra.cloud/ are set by the platform only.
taintsrequiredarray of KubernetesTaint
keyrequiredstring
valuestring
effectrequiredstringOne of NoSchedule, PreferNoSchedule, NoExecute
autoscalingrequiredKubernetesAutoscaling | null
minrequiredinteger
maxrequiredinteger
public_ipv4requiredboolean
versionrequiredstringThe minor its nodes run or are rolling to.
staterequiredstringOne of creating, running, scaling, upgrading, deleting, deleted, error
nodesrequiredarray of KubernetesNode
server_idrequiredstring
hostnamerequiredstring
zonerequiredstring
staterequiredstringThe server's state.
is_readyrequiredbooleanThe node reports Ready to the cluster.
kubelet_versionrequiredstringEmpty until the node joined.
public_ipv6requiredstring | null
public_ipv4requiredstring | null
active_operationrequiredOperation | null
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
created_atrequiredstring (date-time)
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/kubernetes-clusters/<id>/node-pools/<pool>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Scale a node pool or change its labels, taints or autoscaling bounds#

PATCH/v1/kubernetes-clusters/{id}/node-pools/{pool}
Operation
update_kubernetes_node_pool
Credentials
API token, Portal session
Requires
Permission operate

A new count scales the pool: new nodes join, surplus nodes are cordoned, drained and deleted, newest first. New labels and taints apply to every node. The pool's plan, zones and IPv4 setting are fixed; create another pool to change them. A change that lets the pool hold more nodes (a larger count, or a larger autoscaling max) is refused with 402 while the account may not spend one month of the added nodes at the pool's plan price; a larger count inside an autoscaling maximum already paid for is refused only while the account may not spend at all. Scaling down and changing only labels, taints or a lower autoscaling bound are never refused for billing.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring
poolrequiredpathstringThe node pool's id.

Request bodyapplication/json

Request body fields
FieldTypeDescription
countinteger
labelsLabelsKeys of 1-63 letters, digits, ., _, / or -, starting and ending with a letter or digit; values of at most 255 printable characters. On a server, keys under kubernetes.ankra.cloud/ and playground.ankra.cloud/ are set by the platform only.
taintsarray of KubernetesTaint
keyrequiredstring
valuestring
effectrequiredstringOne of NoSchedule, PreferNoSchedule, NoExecute
autoscalingKubernetesAutoscaling | null
minrequiredinteger
maxrequiredinteger

Responses

202The node pool and its node_pool.sync operation.application/json

202 response fields
FieldTypeDescription
node_poolrequiredKubernetesNodePool
idrequiredstring
cluster_idrequiredstring
namerequiredstring
planrequiredstring
countrequiredinteger
zonesrequiredarray of string
labelsrequiredLabelsKeys of 1-63 letters, digits, ., _, / or -, starting and ending with a letter or digit; values of at most 255 printable characters. On a server, keys under kubernetes.ankra.cloud/ and playground.ankra.cloud/ are set by the platform only.
taintsrequiredarray of KubernetesTaint
keyrequiredstring
valuestring
effectrequiredstringOne of NoSchedule, PreferNoSchedule, NoExecute
autoscalingrequiredKubernetesAutoscaling | null
minrequiredinteger
maxrequiredinteger
public_ipv4requiredboolean
versionrequiredstringThe minor its nodes run or are rolling to.
staterequiredstringOne of creating, running, scaling, upgrading, deleting, deleted, error
nodesrequiredarray of KubernetesNode
server_idrequiredstring
hostnamerequiredstring
zonerequiredstring
staterequiredstringThe server's state.
is_readyrequiredbooleanThe node reports Ready to the cluster.
kubelet_versionrequiredstringEmpty until the node joined.
public_ipv6requiredstring | null
public_ipv4requiredstring | null
active_operationrequiredOperation | null
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
created_atrequiredstring (date-time)
operationrequiredOperation
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 402The account may not create this. reason is payment_method_required while it has no default payment method and its credit does not cover the create: the credit left must cover one month, at monthly list prices, of everything the account already runs plus what the create adds (add a payment method through POST /v1/account/billing/setup-session, or free what the account no longer needs); owner_approval_required while its owner has not approved paid usage and no credit is left; or account_suspended while an invoice is overdue past the grace period (pay it) or Ankra staff suspended the account (contact support). A prepaid account (linked to an Ankra platform organisation) is refused with payment_method_required while it has no card, and with credit_required once it has one but its credit does not cover the create: Cloud never charges its card, so only a top-up on the Ankra platform lifts it, and top_up_url names that page when Cloud knows it. GET /v1/account/billing reports the same standing. For payment_method_required and credit_required, detail names what the create costs, the credit left and the committed monthly spend only to a principal that may read billing (billing.read, and for an API token a scope that includes it); anyone else is told only that the credit does not cover it.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 422The account would exceed a quota; detail names the limit and reason is quota_exceeded.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X PATCH 'https://cloud.ankra.app/v1/kubernetes-clusters/<id>/node-pools/<pool>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "count": 0,
  "labels": {},
  "taints": [
    {
      "key": "string",
      "effect": "NoSchedule"
    }
  ],
  "autoscaling": {
    "min": 0,
    "max": 1
  }
}'

Delete a node pool#

DELETE/v1/kubernetes-clusters/{id}/node-pools/{pool}
Operation
delete_kubernetes_node_pool
Credentials
API token, Portal session
Requires
Permission operate

Every node is cordoned and drained, then its server is deleted.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring
poolrequiredpathstringThe node pool's id.

Responses

202Accepted; poll the operation.application/json · OperationEnvelope

202 response fields
FieldTypeDescription
operationrequiredOperation
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X DELETE 'https://cloud.ankra.app/v1/kubernetes-clusters/<id>/node-pools/<pool>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Remove chosen nodes from a node pool#

POST/v1/kubernetes-clusters/{id}/node-pools/{pool}/remove-nodes
Operation
remove_kubernetes_nodes
Credentials
API token, Portal session
Requires
Permission operate

Lowers the pool's count by the number of nodes named and cordons, drains and deletes exactly those nodes (where a lower count alone removes the newest). Node names are the cluster's node names. This is how the cluster autoscaler scales a pool down; it never takes a pool below its autoscaling min.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring
poolrequiredpathstringThe node pool's id.

Request bodyapplication/json

Request body fields
FieldTypeDescription
nodesrequiredarray of string

Responses

202The node pool and the node_pool.sync operation that removes the nodes.application/json

202 response fields
FieldTypeDescription
node_poolrequiredKubernetesNodePool
idrequiredstring
cluster_idrequiredstring
namerequiredstring
planrequiredstring
countrequiredinteger
zonesrequiredarray of string
labelsrequiredLabelsKeys of 1-63 letters, digits, ., _, / or -, starting and ending with a letter or digit; values of at most 255 printable characters. On a server, keys under kubernetes.ankra.cloud/ and playground.ankra.cloud/ are set by the platform only.
taintsrequiredarray of KubernetesTaint
keyrequiredstring
valuestring
effectrequiredstringOne of NoSchedule, PreferNoSchedule, NoExecute
autoscalingrequiredKubernetesAutoscaling | null
minrequiredinteger
maxrequiredinteger
public_ipv4requiredboolean
versionrequiredstringThe minor its nodes run or are rolling to.
staterequiredstringOne of creating, running, scaling, upgrading, deleting, deleted, error
nodesrequiredarray of KubernetesNode
server_idrequiredstring
hostnamerequiredstring
zonerequiredstring
staterequiredstringThe server's state.
is_readyrequiredbooleanThe node reports Ready to the cluster.
kubelet_versionrequiredstringEmpty until the node joined.
public_ipv6requiredstring | null
public_ipv4requiredstring | null
active_operationrequiredOperation | null
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
created_atrequiredstring (date-time)
operationrequiredOperation
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X POST 'https://cloud.ankra.app/v1/kubernetes-clusters/<id>/node-pools/<pool>/remove-nodes' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "nodes": [
    "string"
  ]
}'

Restore the cluster's etcd from a snapshot#

POST/v1/kubernetes-clusters/{id}/restore
Operation
restore_kubernetes_cluster
Credentials
API token, Portal session
Requires
Permission operate

Replaces the cluster's whole state (every object in etcd) with the snapshot's. The API is unavailable while the control plane restarts; nodes and their volumes are kept.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Request bodyapplication/json

Request body fields
FieldTypeDescription
snapshotrequiredstringThe name of a snapshot from list_kubernetes_cluster_etcd_snapshots.

Responses

202Accepted; poll the operation.application/json · OperationEnvelope

202 response fields
FieldTypeDescription
operationrequiredOperation
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X POST 'https://cloud.ankra.app/v1/kubernetes-clusters/<id>/restore' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "snapshot": "string"
}'

An OIDC token for the cluster's API, as a client.authentication.k8s.io ExecCredential#

GET/v1/kubernetes-clusters/{id}/token
Operation
get_kubernetes_cluster_token
Credentials
API token, Portal session
Requires
Permission read
Note
Reveals a credential or a live view; read-only support sessions are refused.

Signed by the Ankra Cloud Kubernetes issuer (oidc_issuer_url of the cluster), valid for one hour, for this cluster only (aud). groups holds ankra:<role> of the caller's role, which the cluster binds to cluster-admin (owner, admin), edit (member) or view (viewer). The answer is an ExecCredential, so a kubeconfig's exec plugin can print it as is. Audited.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

200The ExecCredential.application/json · KubernetesExecCredential

200 response fields
FieldTypeDescription
apiVersionrequiredstringOne of client.authentication.k8s.io/v1
kindrequiredstringOne of ExecCredential
statusrequiredobject
tokenrequiredstring
expirationTimestamprequiredstring (date-time)
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • 503No capacity or address is free in the zone right now (reason: capacity_unavailable, with availability wording in detail), or a host did not answer; try another plan or zone, or try again later.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/kubernetes-clusters/<id>/token' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Upgrade a Kubernetes cluster to the next minor#

POST/v1/kubernetes-clusters/{id}/upgrade
Operation
upgrade_kubernetes_cluster
Credentials
API token, Portal session
Requires
Permission operate

version must be the minor after the cluster's (one minor at a time). The control plane is upgraded first, then the add-ons, then every node pool is rolled: each node is replaced by a new one at the new version, after the old one is cordoned and drained.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Request bodyapplication/json

Request body fields
FieldTypeDescription
versionrequiredstring

Responses

202The cluster and its kubernetes_cluster.upgrade operation.application/json

202 response fields
FieldTypeDescription
kubernetes_clusterrequiredKubernetesCluster
idrequiredstring
zonerequiredstring
regionrequiredstring
namerequiredstring
versionrequiredstringThe minor, e.g. 1.36.
kubernetes_versionrequiredstringThe patch release the control plane runs, e.g. v1.36.5.
available_upgraderequiredstring | nullThe next minor this cluster can upgrade to.
staterequiredstringOne of creating, running, upgrading, restoring, error, deleting, deleted
network_idrequiredstring
control_planerequiredstringWhat a cluster's control plane is built for. development: one API server and etcd replica, no control-plane fee, the nodes are the whole bill; an upgrade or a host node failure interrupts the API. production: three replicas with embedded etcd quorum spread across host nodes, the monthly control-plane fee. The tier is chosen at create and does not change in place.One of development, production
control_plane_replicasrequiredintegerAPI server and embedded etcd replicas the control plane runs.
control_plane_price_monthly_centsrequiredintegerThe tier's control-plane fee per month, billed per hour; 0 for development. The IPv4 endpoint add-on is on top.
production_recommendedrequiredbooleanFalse for a development control plane: no high availability, no service level.
public_ipv4requiredboolean
private_endpointrequiredboolean
endpointrequiredstring | nullThe API server URL on IPv6; null until the control plane is up.
endpoint_ipv4requiredstring | nullThe API server URL on IPv4, with the add-on.
oidc_issuer_urlrequiredstring
labelsrequiredLabelsKeys of 1-63 letters, digits, ., _, / or -, starting and ending with a letter or digit; values of at most 255 printable characters. On a server, keys under kubernetes.ankra.cloud/ and playground.ankra.cloud/ are set by the platform only.
healthrequiredKubernetesHealth
api_serverrequiredstringOne of healthy, unhealthy, unknown
etcd_members_readyrequiredinteger
etcd_members_totalrequiredinteger
has_etcd_quorumrequiredboolean
nodes_readyrequiredinteger
nodes_totalrequiredinteger
observed_atrequiredstring (date-time) | null
detailrequiredstring
addonsrequiredarray of KubernetesAddon
namerequiredstring
versionrequiredstringThe pinned Helm chart version.
etcd_snapshot_schedulerequiredstring
etcd_snapshot_retentionrequiredinteger
node_poolsarray of KubernetesNodePoolOnly on get_kubernetes_cluster.
idrequiredstring
cluster_idrequiredstring
namerequiredstring
planrequiredstring
countrequiredinteger
zonesrequiredarray of string
labelsrequiredLabelsKeys of 1-63 letters, digits, ., _, / or -, starting and ending with a letter or digit; values of at most 255 printable characters. On a server, keys under kubernetes.ankra.cloud/ and playground.ankra.cloud/ are set by the platform only.
taintsrequiredarray of KubernetesTaint
keyrequiredstring
valuestring
effectrequiredstringOne of NoSchedule, PreferNoSchedule, NoExecute
autoscalingrequiredKubernetesAutoscaling | null
minrequiredinteger
maxrequiredinteger
public_ipv4requiredboolean
versionrequiredstringThe minor its nodes run or are rolling to.
staterequiredstringOne of creating, running, scaling, upgrading, deleting, deleted, error
nodesrequiredarray of KubernetesNode
server_idrequiredstring
hostnamerequiredstring
zonerequiredstring
staterequiredstringThe server's state.
is_readyrequiredbooleanThe node reports Ready to the cluster.
kubelet_versionrequiredstringEmpty until the node joined.
public_ipv6requiredstring | null
public_ipv4requiredstring | null
active_operationrequiredOperation | null
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
created_atrequiredstring (date-time)
platformrequiredKubernetesPlatformRegistrationThe cluster's registration in the Ankra platform (ADR 0006). url is the cluster's page in the platform once registered; reason says why it is not registered otherwise (unlinked: link an Ankra organisation to the account first).
staterequiredstringOne of pending, unlinked, registered, failed, deregistered
organisation_idrequiredstring | null
cluster_idrequiredstring | nullThe platform's identifier of the cluster.
urlrequiredstring | null
reasonrequiredstring
next_attempt_atrequiredstring (date-time) | nullWhen a pending registration is tried again.
registered_atrequiredstring (date-time) | null
active_operationrequiredOperation | null
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
created_atrequiredstring (date-time)
operationrequiredOperation
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X POST 'https://cloud.ankra.app/v1/kubernetes-clusters/<id>/upgrade' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "version": "1.36"
}'

Whether a managed Kubernetes cluster can be created in a zone now, and why not#

GET/v1/kubernetes-clusters/availability
Operation
get_kubernetes_availability
Credentials
API token, Portal session
Requires
Permission read

Applies the rule create_kubernetes_cluster applies before it records anything: the zone's region needs a ready host cluster to run control planes on. available false comes with reason, the refusal the create would answer with 503. available true comes with the host's stage and the control-plane tiers a new cluster there can be created as: a development host offers the development tier only, which a create that names no tier gets, and a create naming another tier is a 400. An unknown zone, or one not offered to the account, is a 400 as it is on create. Clients read this before they create a cluster, so a region that cannot take one is refused up front.

Parameters

Parameters
NameInTypeDescription
zonerequiredquerystringThe zone the cluster would be created in.

Responses

200The zone's availability.application/json · KubernetesAvailability

200 response fields
FieldTypeDescription
zonerequiredstring
regionrequiredstring
availablerequiredbooleanWhether a cluster can be created in the zone now.
reasonrequiredstring | nullWhy not; null when available.
host_stagerequiredstring | nullThe region host's stage; null unless available.One of development, production
control_planesrequiredarray of stringThe tiers a new cluster in the zone can be created as, cheapest first; empty unless available.One of development, production
default_control_planerequiredstring | nullThe tier a create that names none gets; null unless available.
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/kubernetes-clusters/availability?zone=<zone>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

The Kubernetes versions a cluster can run, with their pinned add-ons, the control-plane tiers and the prices#

GET/v1/kubernetes-clusters/versions
Operation
list_kubernetes_versions
Credentials
API token, Portal session
Requires
Permission read

The three latest Kubernetes minors the pinned vCluster release supports. Each minor pins its patch release and the add-on versions every cluster of that minor runs. A cluster upgrades one minor at a time. control_planes are the tiers a cluster's control plane can be created as, with their monthly prices: development (one replica, no fee; the nodes are the whole bill) and production (three replicas with embedded etcd quorum, the monthly fee). control_plane_price_monthly_cents is the default tier's price.

Responses

200The versions.application/json · KubernetesVersionList

200 response fields
FieldTypeDescription
itemsrequiredarray of KubernetesVersion
versionrequiredstringThe minor.
kubernetes_versionrequiredstringThe patch release this minor runs.
is_defaultrequiredboolean
addonsrequiredarray of KubernetesAddon
namerequiredstring
versionrequiredstringThe pinned Helm chart version.
vcluster_chart_versionrequiredstring
control_planesrequiredarray of KubernetesControlPlaneOfferThe control-plane tiers on offer, cheapest first.
control_planerequiredstringWhat a cluster's control plane is built for. development: one API server and etcd replica, no control-plane fee, the nodes are the whole bill; an upgrade or a host node failure interrupts the API. production: three replicas with embedded etcd quorum spread across host nodes, the monthly control-plane fee. The tier is chosen at create and does not change in place.One of development, production
replicasrequiredintegerAPI server and embedded etcd replicas.
high_availabilityrequiredboolean
price_monthly_centsrequiredintegerPer cluster, billed per hour; 0 for development.
is_defaultrequiredboolean
production_recommendedrequiredbooleanFalse for the tier every surface flags as not for production.
descriptionrequiredstring
default_control_planerequiredstringWhat a cluster's control plane is built for. development: one API server and etcd replica, no control-plane fee, the nodes are the whole bill; an upgrade or a host node failure interrupts the API. production: three replicas with embedded etcd quorum spread across host nodes, the monthly control-plane fee. The tier is chosen at create and does not change in place.One of development, production
control_plane_price_monthly_centsrequiredintegerThe default tier's price per cluster, billed per hour; control_planes has every tier.
ipv4_price_monthly_centsrequiredintegerThe IPv4 API endpoint add-on, billed per hour.
region_control_planesarray of KubernetesRegionControlPlanesPer region with a ready host cluster, the tiers a new cluster there can be created as. A region whose host is development (no Ankra Storage in its zone yet, so tenant etcd runs on single-node local volumes) offers the development tier only and is not for production. A region missing here has no ready host.
regionrequiredstring
host_stagerequiredstringOne of development, production
control_planesrequiredarray of stringOne of development, production
default_control_planerequiredstringWhat a cluster's control plane is built for. development: one API server and etcd replica, no control-plane fee, the nodes are the whole bill; an upgrade or a host node failure interrupts the API. production: three replicas with embedded etcd quorum spread across host nodes, the monthly control-plane fee. The tier is chosen at create and does not change in place.One of development, production
production_recommendedrequiredboolean
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/kubernetes-clusters/versions' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

OpenID Connect discovery for the Kubernetes token issuer#

GET/v1/kubernetes-oidc/.well-known/openid-configuration
Operation
get_kubernetes_oidc_configuration
Credentials
None (public)

Every managed cluster's API server trusts this issuer for get_kubernetes_cluster_token tokens.

Responses

200The discovery document.application/json

200 response fields
FieldTypeDescription
issuerrequiredstring
jwks_urirequiredstring
response_types_supportedrequiredarray of string
subject_types_supportedrequiredarray of string
id_token_signing_alg_values_supportedrequiredarray of string
claims_supportedarray of string
  • 503No capacity or address is free in the zone right now (reason: capacity_unavailable, with availability wording in detail), or a host did not answer; try another plan or zone, or try again later.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/kubernetes-oidc/.well-known/openid-configuration'

The Kubernetes token issuer's public keys (JWKS)#

GET/v1/kubernetes-oidc/keys
Operation
get_kubernetes_oidc_keys
Credentials
None (public)

Responses

200The JSON Web Key Set.application/json

200 response fields
FieldTypeDescription
keysrequiredarray of object
ktyrequiredstring
kidrequiredstring
userequiredstring
algrequiredstring
crvstring
xstring
ystring
  • 503No capacity or address is free in the zone right now (reason: capacity_unavailable, with availability wording in detail), or a host did not answer; try another plan or zone, or try again later.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/kubernetes-oidc/keys'