API reference · Managed services

Managed Kubernetes

18 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
Name	In	Type	Description
`cursor`	query	string	The `next_cursor` of the previous page.
`limit`	query	integer	Page size; the server applies its default and maximum.

Responses

200One page of clusters.application/json

200 response fields
Field	Type	Description
`items`required	array of KubernetesCluster
`id`required	string
`zone`required	string
`region`required	string
`name`required	string
`version`required	string	The minor, e.g. 1.36.
`kubernetes_version`required	string	The patch release the control plane runs, e.g. v1.36.5.
`available_upgrade`required	string \| null	The next minor this cluster can upgrade to.
`state`required	string	One of `creating`, `running`, `upgrading`, `restoring`, `error`, `deleting`, `deleted`
`network_id`required	string
`public_ipv4`required	boolean
`private_endpoint`required	boolean
`endpoint`required	string \| null	The API server URL on IPv6; null until the control plane is up.
`endpoint_ipv4`required	string \| null	The API server URL on IPv4, with the add-on.
`oidc_issuer_url`required	string
`labels`required	Labels	Keys of 1-63 letters, digits, `.`, `_`, `/` or `-`, starting and ending with a letter or digit; values of at most 255 printable characters.
`health`required	KubernetesHealth
`api_server`required	string	One of `healthy`, `unhealthy`, `unknown`
`etcd_members_ready`required	integer
`etcd_members_total`required	integer
`has_etcd_quorum`required	boolean
`nodes_ready`required	integer
`nodes_total`required	integer
`observed_at`required	string (date-time) \| null
`detail`required	string
`addons`required	array of KubernetesAddon
`name`required	string
`version`required	string	The pinned Helm chart version.
`etcd_snapshot_schedule`required	string
`etcd_snapshot_retention`required	integer
`node_pools`	array of KubernetesNodePool	Only on get_kubernetes_cluster.
`id`required	string
`cluster_id`required	string
`name`required	string
`plan`required	string
`count`required	integer
`zones`required	array of string
`labels`required	Labels	Keys of 1-63 letters, digits, `.`, `_`, `/` or `-`, starting and ending with a letter or digit; values of at most 255 printable characters.
`taints`required	array of KubernetesTaint
`key`required	string
`value`	string
`effect`required	string	One of `NoSchedule`, `PreferNoSchedule`, `NoExecute`
`autoscaling`required	KubernetesAutoscaling \| null
`min`required	integer
`max`required	integer
`public_ipv4`required	boolean
`version`required	string	The minor its nodes run or are rolling to.
`state`required	string	One of `creating`, `running`, `scaling`, `upgrading`, `deleting`, `deleted`, `error`
`nodes`required	array of KubernetesNode
`server_id`required	string
`hostname`required	string
`zone`required	string
`state`required	string	The server's state.
`is_ready`required	boolean	The node reports Ready to the cluster.
`kubelet_version`required	string	Empty until the node joined.
`public_ipv6`required	string \| null
`public_ipv4`required	string \| null
`active_operation`required	Operation \| null
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	string \| null
`node_id`	string	Set on node maintenance operations (operator only); absent otherwise.
`load_balancer_id`	string \| null	Set on the operations that create and delete a load balancer.
`database_id`	string \| null	Set on the operations that create and delete a managed database.
`edge_id`	string \| null	Set on the operations that sync and delete a network edge.
`snapshot_id`	string \| null	Set on the operations that create and delete a snapshot, and on a `storage.create` that clones one.
`kubernetes_cluster_id`	string \| null	Set on the operations of a managed Kubernetes cluster.
`node_pool_id`	string \| null	Set on the operations of a Kubernetes node pool.
`kubernetes_host_id`	string	Set on a regional host cluster bootstrap (operator only); absent otherwise.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	string (date-time)
`actor`	string	Who asked for the operation: `user:<id>`, `token:<name>`, `operator`, `system:<component>`; empty on older operations.
`progress`	MigrationProgress	Present on `GET /v1/operations/{id}` while a `server.migrate` drives a live transfer.
`events`	array of OperationEvent	Present on `GET /v1/operations/{id}`; the newest 100 entries of the operation's log, oldest first.
`created_at`required	string (date-time)
`platform`required	KubernetesPlatformRegistration	The 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).
`state`required	string	One of `pending`, `unlinked`, `registered`, `failed`, `deregistered`
`organisation_id`required	string \| null
`cluster_id`required	string \| null	The platform's identifier of the cluster.
`url`required	string \| null
`reason`required	string
`next_attempt_at`required	string (date-time) \| null	When a pending registration is tried again.
`registered_at`required	string (date-time) \| null
`active_operation`required	Operation \| null
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	string \| null
`node_id`	string	Set on node maintenance operations (operator only); absent otherwise.
`load_balancer_id`	string \| null	Set on the operations that create and delete a load balancer.
`database_id`	string \| null	Set on the operations that create and delete a managed database.
`edge_id`	string \| null	Set on the operations that sync and delete a network edge.
`snapshot_id`	string \| null	Set on the operations that create and delete a snapshot, and on a `storage.create` that clones one.
`kubernetes_cluster_id`	string \| null	Set on the operations of a managed Kubernetes cluster.
`node_pool_id`	string \| null	Set on the operations of a Kubernetes node pool.
`kubernetes_host_id`	string	Set on a regional host cluster bootstrap (operator only); absent otherwise.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	string (date-time)
`actor`	string	Who asked for the operation: `user:<id>`, `token:<name>`, `operator`, `system:<component>`; empty on older operations.
`progress`	MigrationProgress	Present on `GET /v1/operations/{id}` while a `server.migrate` drives a live transfer.
`state`required	string	One of `reserved`, `detached`, `preparing`, `sending`, `switched`, `aborting`
`source_node_id`required	string
`target_node_id`required	string
`phase`required	string	How far the nodes report the current attempt.One of , `preparing`, `transferring`, `completed`, `failed`
`attempt`required	integer	Which send this is under the convergence policy, from 1.
`iteration`required	integer	Memory passes so far in the current attempt.
`transferred_bytes`required	integer
`total_bytes`required	integer	0 when the hypervisor does not report it.
`dirty_bytes_per_second`required	integer
`downtime_milliseconds`required	integer	The pause the guest took at handover, once completed.
`detail`required	string
`reported_at`required	string (date-time) \| null	The reporting node's clock.
`events`	array of OperationEvent	Present on `GET /v1/operations/{id}`; the newest 100 entries of the operation's log, oldest first.
`at`required	string (date-time)
`kind`required	string	For example `target_chosen`, `send_started`, `handed_over`, `undoing`, `cold_fallback`, `move_cancelled`, `recovery_started`, `succeeded`, `failed`.
`message`required	string
`data`required	object
`created_at`required	string (date-time)
`next_cursor`required	string \| 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).
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: three API server replicas with embedded etcd spread across host nodes and zones, etcd on ankra-standard volumes and snapshotted to object storage every six hours. The cluster's worker nodes are servers in your account, created by its node pools (node_pools here creates them with the cluster). 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 control plane is billed per hour at control_plane_price_monthly_cents of list_kubernetes_versions; nodes are billed as servers. An account may hold 5 clusters.

Request bodyapplication/json

Request body fields
Field	Type	Description
`zone`required	string	The zone the node pools default to; its region hosts the control plane.
`name`required	string	DNS label, 2 to 40 characters.
`network_id`required	string	The private network every node joins.
`version`	string	A minor from list_kubernetes_versions; defaults to the newest.
`public_ipv4`	boolean	Serve the API on IPv4 too (paid add-on). Default false: IPv6 only.
`private_endpoint`	boolean	Not available yet; true answers 400.
`labels`	Labels	Keys of 1-63 letters, digits, `.`, `_`, `/` or `-`, starting and ending with a letter or digit; values of at most 255 printable characters.
`node_pools`	array of KubernetesNodePoolRequest
`name`required	string
`plan`required	string	A server plan from list_plans.
`count`required	integer
`zones`	array of string	Zones of the cluster's region to spread nodes across; defaults to the cluster's zone.
`labels`	Labels	Keys of 1-63 letters, digits, `.`, `_`, `/` or `-`, starting and ending with a letter or digit; values of at most 255 printable characters.
`taints`	array of KubernetesTaint
`key`required	string
`value`	string
`effect`required	string	One of `NoSchedule`, `PreferNoSchedule`, `NoExecute`
`autoscaling`	KubernetesAutoscaling \| null
`min`required	integer
`max`required	integer
`public_ipv4`	boolean	Give 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
Field	Type	Description
`kubernetes_cluster`required	KubernetesCluster
`id`required	string
`zone`required	string
`region`required	string
`name`required	string
`version`required	string	The minor, e.g. 1.36.
`kubernetes_version`required	string	The patch release the control plane runs, e.g. v1.36.5.
`available_upgrade`required	string \| null	The next minor this cluster can upgrade to.
`state`required	string	One of `creating`, `running`, `upgrading`, `restoring`, `error`, `deleting`, `deleted`
`network_id`required	string
`public_ipv4`required	boolean
`private_endpoint`required	boolean
`endpoint`required	string \| null	The API server URL on IPv6; null until the control plane is up.
`endpoint_ipv4`required	string \| null	The API server URL on IPv4, with the add-on.
`oidc_issuer_url`required	string
`labels`required	Labels	Keys of 1-63 letters, digits, `.`, `_`, `/` or `-`, starting and ending with a letter or digit; values of at most 255 printable characters.
`health`required	KubernetesHealth
`api_server`required	string	One of `healthy`, `unhealthy`, `unknown`
`etcd_members_ready`required	integer
`etcd_members_total`required	integer
`has_etcd_quorum`required	boolean
`nodes_ready`required	integer
`nodes_total`required	integer
`observed_at`required	string (date-time) \| null
`detail`required	string
`addons`required	array of KubernetesAddon
`name`required	string
`version`required	string	The pinned Helm chart version.
`etcd_snapshot_schedule`required	string
`etcd_snapshot_retention`required	integer
`node_pools`	array of KubernetesNodePool	Only on get_kubernetes_cluster.
`id`required	string
`cluster_id`required	string
`name`required	string
`plan`required	string
`count`required	integer
`zones`required	array of string
`labels`required	Labels	Keys of 1-63 letters, digits, `.`, `_`, `/` or `-`, starting and ending with a letter or digit; values of at most 255 printable characters.
`taints`required	array of KubernetesTaint
`key`required	string
`value`	string
`effect`required	string	One of `NoSchedule`, `PreferNoSchedule`, `NoExecute`
`autoscaling`required	KubernetesAutoscaling \| null
`min`required	integer
`max`required	integer
`public_ipv4`required	boolean
`version`required	string	The minor its nodes run or are rolling to.
`state`required	string	One of `creating`, `running`, `scaling`, `upgrading`, `deleting`, `deleted`, `error`
`nodes`required	array of KubernetesNode
`server_id`required	string
`hostname`required	string
`zone`required	string
`state`required	string	The server's state.
`is_ready`required	boolean	The node reports Ready to the cluster.
`kubelet_version`required	string	Empty until the node joined.
`public_ipv6`required	string \| null
`public_ipv4`required	string \| null
`active_operation`required	Operation \| null
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	string \| null
`node_id`	string	Set on node maintenance operations (operator only); absent otherwise.
`load_balancer_id`	string \| null	Set on the operations that create and delete a load balancer.
`database_id`	string \| null	Set on the operations that create and delete a managed database.
`edge_id`	string \| null	Set on the operations that sync and delete a network edge.
`snapshot_id`	string \| null	Set on the operations that create and delete a snapshot, and on a `storage.create` that clones one.
`kubernetes_cluster_id`	string \| null	Set on the operations of a managed Kubernetes cluster.
`node_pool_id`	string \| null	Set on the operations of a Kubernetes node pool.
`kubernetes_host_id`	string	Set on a regional host cluster bootstrap (operator only); absent otherwise.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	string (date-time)
`actor`	string	Who asked for the operation: `user:<id>`, `token:<name>`, `operator`, `system:<component>`; empty on older operations.
`progress`	MigrationProgress	Present on `GET /v1/operations/{id}` while a `server.migrate` drives a live transfer.
`events`	array of OperationEvent	Present on `GET /v1/operations/{id}`; the newest 100 entries of the operation's log, oldest first.
`created_at`required	string (date-time)
`platform`required	KubernetesPlatformRegistration	The 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).
`state`required	string	One of `pending`, `unlinked`, `registered`, `failed`, `deregistered`
`organisation_id`required	string \| null
`cluster_id`required	string \| null	The platform's identifier of the cluster.
`url`required	string \| null
`reason`required	string
`next_attempt_at`required	string (date-time) \| null	When a pending registration is tried again.
`registered_at`required	string (date-time) \| null
`active_operation`required	Operation \| null
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	string \| null
`node_id`	string	Set on node maintenance operations (operator only); absent otherwise.
`load_balancer_id`	string \| null	Set on the operations that create and delete a load balancer.
`database_id`	string \| null	Set on the operations that create and delete a managed database.
`edge_id`	string \| null	Set on the operations that sync and delete a network edge.
`snapshot_id`	string \| null	Set on the operations that create and delete a snapshot, and on a `storage.create` that clones one.
`kubernetes_cluster_id`	string \| null	Set on the operations of a managed Kubernetes cluster.
`node_pool_id`	string \| null	Set on the operations of a Kubernetes node pool.
`kubernetes_host_id`	string	Set on a regional host cluster bootstrap (operator only); absent otherwise.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	string (date-time)
`actor`	string	Who asked for the operation: `user:<id>`, `token:<name>`, `operator`, `system:<component>`; empty on older operations.
`progress`	MigrationProgress	Present on `GET /v1/operations/{id}` while a `server.migrate` drives a live transfer.
`state`required	string	One of `reserved`, `detached`, `preparing`, `sending`, `switched`, `aborting`
`source_node_id`required	string
`target_node_id`required	string
`phase`required	string	How far the nodes report the current attempt.One of , `preparing`, `transferring`, `completed`, `failed`
`attempt`required	integer	Which send this is under the convergence policy, from 1.
`iteration`required	integer	Memory passes so far in the current attempt.
`transferred_bytes`required	integer
`total_bytes`required	integer	0 when the hypervisor does not report it.
`dirty_bytes_per_second`required	integer
`downtime_milliseconds`required	integer	The pause the guest took at handover, once completed.
`detail`required	string
`reported_at`required	string (date-time) \| null	The reporting node's clock.
`events`	array of OperationEvent	Present on `GET /v1/operations/{id}`; the newest 100 entries of the operation's log, oldest first.
`at`required	string (date-time)
`kind`required	string	For example `target_chosen`, `send_started`, `handed_over`, `undoing`, `cold_fallback`, `move_cancelled`, `recovery_started`, `succeeded`, `failed`.
`message`required	string
`data`required	object
`created_at`required	string (date-time)
`operation`required	Operation
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	string \| null
`node_id`	string	Set on node maintenance operations (operator only); absent otherwise.
`load_balancer_id`	string \| null	Set on the operations that create and delete a load balancer.
`database_id`	string \| null	Set on the operations that create and delete a managed database.
`edge_id`	string \| null	Set on the operations that sync and delete a network edge.
`snapshot_id`	string \| null	Set on the operations that create and delete a snapshot, and on a `storage.create` that clones one.
`kubernetes_cluster_id`	string \| null	Set on the operations of a managed Kubernetes cluster.
`node_pool_id`	string \| null	Set on the operations of a Kubernetes node pool.
`kubernetes_host_id`	string	Set on a regional host cluster bootstrap (operator only); absent otherwise.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	string (date-time)
`actor`	string	Who asked for the operation: `user:<id>`, `token:<name>`, `operator`, `system:<component>`; empty on older operations.
`progress`	MigrationProgress	Present on `GET /v1/operations/{id}` while a `server.migrate` drives a live transfer.
`state`required	string	One of `reserved`, `detached`, `preparing`, `sending`, `switched`, `aborting`
`source_node_id`required	string
`target_node_id`required	string
`phase`required	string	How far the nodes report the current attempt.One of , `preparing`, `transferring`, `completed`, `failed`
`attempt`required	integer	Which send this is under the convergence policy, from 1.
`iteration`required	integer	Memory passes so far in the current attempt.
`transferred_bytes`required	integer
`total_bytes`required	integer	0 when the hypervisor does not report it.
`dirty_bytes_per_second`required	integer
`downtime_milliseconds`required	integer	The pause the guest took at handover, once completed.
`detail`required	string
`reported_at`required	string (date-time) \| null	The reporting node's clock.
`events`	array of OperationEvent	Present on `GET /v1/operations/{id}`; the newest 100 entries of the operation's log, oldest first.
`at`required	string (date-time)
`kind`required	string	For example `target_chosen`, `send_started`, `handed_over`, `undoing`, `cold_fallback`, `move_cancelled`, `recovery_started`, `succeeded`, `failed`.
`message`required	string
`data`required	object

400The request is invalid; detail says why.
401Not signed in, or the credential is invalid or expired.
402The account may not create billable resources. reason is payment_method_required while it has neither a default payment method nor a live credit (add one through POST /v1/account/billing/setup-session or redeem a coupon), or account_suspended while an invoice is overdue past the grace period (pay it; nothing already running is stopped) or Ankra staff suspended the account (contact support). GET /v1/account/billing reports the same standing.
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.
503No capacity or address is free, or a host did not answer; 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
Name	In	Type	Description
`id`required	path	string

Responses

200The cluster.application/json

200 response fields
Field	Type	Description
`kubernetes_cluster`required	KubernetesCluster
`id`required	string
`zone`required	string
`region`required	string
`name`required	string
`version`required	string	The minor, e.g. 1.36.
`kubernetes_version`required	string	The patch release the control plane runs, e.g. v1.36.5.
`available_upgrade`required	string \| null	The next minor this cluster can upgrade to.
`state`required	string	One of `creating`, `running`, `upgrading`, `restoring`, `error`, `deleting`, `deleted`
`network_id`required	string
`public_ipv4`required	boolean
`private_endpoint`required	boolean
`endpoint`required	string \| null	The API server URL on IPv6; null until the control plane is up.
`endpoint_ipv4`required	string \| null	The API server URL on IPv4, with the add-on.
`oidc_issuer_url`required	string
`labels`required	Labels	Keys of 1-63 letters, digits, `.`, `_`, `/` or `-`, starting and ending with a letter or digit; values of at most 255 printable characters.
`health`required	KubernetesHealth
`api_server`required	string	One of `healthy`, `unhealthy`, `unknown`
`etcd_members_ready`required	integer
`etcd_members_total`required	integer
`has_etcd_quorum`required	boolean
`nodes_ready`required	integer
`nodes_total`required	integer
`observed_at`required	string (date-time) \| null
`detail`required	string
`addons`required	array of KubernetesAddon
`name`required	string
`version`required	string	The pinned Helm chart version.
`etcd_snapshot_schedule`required	string
`etcd_snapshot_retention`required	integer
`node_pools`	array of KubernetesNodePool	Only on get_kubernetes_cluster.
`id`required	string
`cluster_id`required	string
`name`required	string
`plan`required	string
`count`required	integer
`zones`required	array of string
`labels`required	Labels	Keys of 1-63 letters, digits, `.`, `_`, `/` or `-`, starting and ending with a letter or digit; values of at most 255 printable characters.
`taints`required	array of KubernetesTaint
`key`required	string
`value`	string
`effect`required	string	One of `NoSchedule`, `PreferNoSchedule`, `NoExecute`
`autoscaling`required	KubernetesAutoscaling \| null
`min`required	integer
`max`required	integer
`public_ipv4`required	boolean
`version`required	string	The minor its nodes run or are rolling to.
`state`required	string	One of `creating`, `running`, `scaling`, `upgrading`, `deleting`, `deleted`, `error`
`nodes`required	array of KubernetesNode
`server_id`required	string
`hostname`required	string
`zone`required	string
`state`required	string	The server's state.
`is_ready`required	boolean	The node reports Ready to the cluster.
`kubelet_version`required	string	Empty until the node joined.
`public_ipv6`required	string \| null
`public_ipv4`required	string \| null
`active_operation`required	Operation \| null
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	string \| null
`node_id`	string	Set on node maintenance operations (operator only); absent otherwise.
`load_balancer_id`	string \| null	Set on the operations that create and delete a load balancer.
`database_id`	string \| null	Set on the operations that create and delete a managed database.
`edge_id`	string \| null	Set on the operations that sync and delete a network edge.
`snapshot_id`	string \| null	Set on the operations that create and delete a snapshot, and on a `storage.create` that clones one.
`kubernetes_cluster_id`	string \| null	Set on the operations of a managed Kubernetes cluster.
`node_pool_id`	string \| null	Set on the operations of a Kubernetes node pool.
`kubernetes_host_id`	string	Set on a regional host cluster bootstrap (operator only); absent otherwise.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	string (date-time)
`actor`	string	Who asked for the operation: `user:<id>`, `token:<name>`, `operator`, `system:<component>`; empty on older operations.
`progress`	MigrationProgress	Present on `GET /v1/operations/{id}` while a `server.migrate` drives a live transfer.
`events`	array of OperationEvent	Present on `GET /v1/operations/{id}`; the newest 100 entries of the operation's log, oldest first.
`created_at`required	string (date-time)
`platform`required	KubernetesPlatformRegistration	The 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).
`state`required	string	One of `pending`, `unlinked`, `registered`, `failed`, `deregistered`
`organisation_id`required	string \| null
`cluster_id`required	string \| null	The platform's identifier of the cluster.
`url`required	string \| null
`reason`required	string
`next_attempt_at`required	string (date-time) \| null	When a pending registration is tried again.
`registered_at`required	string (date-time) \| null
`active_operation`required	Operation \| null
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	string \| null
`node_id`	string	Set on node maintenance operations (operator only); absent otherwise.
`load_balancer_id`	string \| null	Set on the operations that create and delete a load balancer.
`database_id`	string \| null	Set on the operations that create and delete a managed database.
`edge_id`	string \| null	Set on the operations that sync and delete a network edge.
`snapshot_id`	string \| null	Set on the operations that create and delete a snapshot, and on a `storage.create` that clones one.
`kubernetes_cluster_id`	string \| null	Set on the operations of a managed Kubernetes cluster.
`node_pool_id`	string \| null	Set on the operations of a Kubernetes node pool.
`kubernetes_host_id`	string	Set on a regional host cluster bootstrap (operator only); absent otherwise.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	string (date-time)
`actor`	string	Who asked for the operation: `user:<id>`, `token:<name>`, `operator`, `system:<component>`; empty on older operations.
`progress`	MigrationProgress	Present on `GET /v1/operations/{id}` while a `server.migrate` drives a live transfer.
`state`required	string	One of `reserved`, `detached`, `preparing`, `sending`, `switched`, `aborting`
`source_node_id`required	string
`target_node_id`required	string
`phase`required	string	How far the nodes report the current attempt.One of , `preparing`, `transferring`, `completed`, `failed`
`attempt`required	integer	Which send this is under the convergence policy, from 1.
`iteration`required	integer	Memory passes so far in the current attempt.
`transferred_bytes`required	integer
`total_bytes`required	integer	0 when the hypervisor does not report it.
`dirty_bytes_per_second`required	integer
`downtime_milliseconds`required	integer	The pause the guest took at handover, once completed.
`detail`required	string
`reported_at`required	string (date-time) \| null	The reporting node's clock.
`events`	array of OperationEvent	Present on `GET /v1/operations/{id}`; the newest 100 entries of the operation's log, oldest first.
`at`required	string (date-time)
`kind`required	string	For example `target_chosen`, `send_started`, `handed_over`, `undoing`, `cold_fallback`, `move_cancelled`, `recovery_started`, `succeeded`, `failed`.
`message`required	string
`data`required	object
`created_at`required	string (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.
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
Name	In	Type	Description
`id`required	path	string

Responses

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

202 response fields
Field	Type	Description
`operation`required	Operation
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	string \| null
`node_id`	string	Set on node maintenance operations (operator only); absent otherwise.
`load_balancer_id`	string \| null	Set on the operations that create and delete a load balancer.
`database_id`	string \| null	Set on the operations that create and delete a managed database.
`edge_id`	string \| null	Set on the operations that sync and delete a network edge.
`snapshot_id`	string \| null	Set on the operations that create and delete a snapshot, and on a `storage.create` that clones one.
`kubernetes_cluster_id`	string \| null	Set on the operations of a managed Kubernetes cluster.
`node_pool_id`	string \| null	Set on the operations of a Kubernetes node pool.
`kubernetes_host_id`	string	Set on a regional host cluster bootstrap (operator only); absent otherwise.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	string (date-time)
`actor`	string	Who asked for the operation: `user:<id>`, `token:<name>`, `operator`, `system:<component>`; empty on older operations.
`progress`	MigrationProgress	Present on `GET /v1/operations/{id}` while a `server.migrate` drives a live transfer.
`state`required	string	One of `reserved`, `detached`, `preparing`, `sending`, `switched`, `aborting`
`source_node_id`required	string
`target_node_id`required	string
`phase`required	string	How far the nodes report the current attempt.One of , `preparing`, `transferring`, `completed`, `failed`
`attempt`required	integer	Which send this is under the convergence policy, from 1.
`iteration`required	integer	Memory passes so far in the current attempt.
`transferred_bytes`required	integer
`total_bytes`required	integer	0 when the hypervisor does not report it.
`dirty_bytes_per_second`required	integer
`downtime_milliseconds`required	integer	The pause the guest took at handover, once completed.
`detail`required	string
`reported_at`required	string (date-time) \| null	The reporting node's clock.
`events`	array of OperationEvent	Present on `GET /v1/operations/{id}`; the newest 100 entries of the operation's log, oldest first.
`at`required	string (date-time)
`kind`required	string	For example `target_chosen`, `send_started`, `handed_over`, `undoing`, `cold_fallback`, `move_cancelled`, `recovery_started`, `succeeded`, `failed`.
`message`required	string
`data`required	object

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.
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
Name	In	Type	Description
`id`required	path	string

Responses

200The snapshots (next_cursor is always null).application/json

200 response fields
Field	Type	Description
`items`required	array of KubernetesEtcdSnapshot
`name`required	string
`taken_at`required	string (date-time)
`size_bytes`required	integer
`next_cursor`required	null
`schedule`required	string	Cron schedule, UTC.
`retention`required	integer

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.
503No capacity or address is free, or a host did not answer; 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
Name	In	Type	Description
`id`required	path	string

Responses

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

202 response fields
Field	Type	Description
`operation`required	Operation
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	string \| null
`node_id`	string	Set on node maintenance operations (operator only); absent otherwise.
`load_balancer_id`	string \| null	Set on the operations that create and delete a load balancer.
`database_id`	string \| null	Set on the operations that create and delete a managed database.
`edge_id`	string \| null	Set on the operations that sync and delete a network edge.
`snapshot_id`	string \| null	Set on the operations that create and delete a snapshot, and on a `storage.create` that clones one.
`kubernetes_cluster_id`	string \| null	Set on the operations of a managed Kubernetes cluster.
`node_pool_id`	string \| null	Set on the operations of a Kubernetes node pool.
`kubernetes_host_id`	string	Set on a regional host cluster bootstrap (operator only); absent otherwise.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	string (date-time)
`actor`	string	Who asked for the operation: `user:<id>`, `token:<name>`, `operator`, `system:<component>`; empty on older operations.
`progress`	MigrationProgress	Present on `GET /v1/operations/{id}` while a `server.migrate` drives a live transfer.
`state`required	string	One of `reserved`, `detached`, `preparing`, `sending`, `switched`, `aborting`
`source_node_id`required	string
`target_node_id`required	string
`phase`required	string	How far the nodes report the current attempt.One of , `preparing`, `transferring`, `completed`, `failed`
`attempt`required	integer	Which send this is under the convergence policy, from 1.
`iteration`required	integer	Memory passes so far in the current attempt.
`transferred_bytes`required	integer
`total_bytes`required	integer	0 when the hypervisor does not report it.
`dirty_bytes_per_second`required	integer
`downtime_milliseconds`required	integer	The pause the guest took at handover, once completed.
`detail`required	string
`reported_at`required	string (date-time) \| null	The reporting node's clock.
`events`	array of OperationEvent	Present on `GET /v1/operations/{id}`; the newest 100 entries of the operation's log, oldest first.
`at`required	string (date-time)
`kind`required	string	For example `target_chosen`, `send_started`, `handed_over`, `undoing`, `cold_fallback`, `move_cancelled`, `recovery_started`, `succeeded`, `failed`.
`message`required	string
`data`required	object

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.
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
Name	In	Type	Description
`id`required	path	string

Responses

200The kubeconfig.application/json

200 response fields
Field	Type	Description
`kubeconfig`required	string	The kubeconfig YAML.
`expires_at`required	string (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.
503No capacity or address is free, or a host did not answer; 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
Name	In	Type	Description
`id`required	path	string

Responses

200Every node pool of the cluster (next_cursor is always null).application/json

200 response fields
Field	Type	Description
`items`required	array of KubernetesNodePool
`id`required	string
`cluster_id`required	string
`name`required	string
`plan`required	string
`count`required	integer
`zones`required	array of string
`labels`required	Labels	Keys of 1-63 letters, digits, `.`, `_`, `/` or `-`, starting and ending with a letter or digit; values of at most 255 printable characters.
`taints`required	array of KubernetesTaint
`key`required	string
`value`	string
`effect`required	string	One of `NoSchedule`, `PreferNoSchedule`, `NoExecute`
`autoscaling`required	KubernetesAutoscaling \| null
`min`required	integer
`max`required	integer
`public_ipv4`required	boolean
`version`required	string	The minor its nodes run or are rolling to.
`state`required	string	One of `creating`, `running`, `scaling`, `upgrading`, `deleting`, `deleted`, `error`
`nodes`required	array of KubernetesNode
`server_id`required	string
`hostname`required	string
`zone`required	string
`state`required	string	The server's state.
`is_ready`required	boolean	The node reports Ready to the cluster.
`kubelet_version`required	string	Empty until the node joined.
`public_ipv6`required	string \| null
`public_ipv4`required	string \| null
`active_operation`required	Operation \| null
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	string \| null
`node_id`	string	Set on node maintenance operations (operator only); absent otherwise.
`load_balancer_id`	string \| null	Set on the operations that create and delete a load balancer.
`database_id`	string \| null	Set on the operations that create and delete a managed database.
`edge_id`	string \| null	Set on the operations that sync and delete a network edge.
`snapshot_id`	string \| null	Set on the operations that create and delete a snapshot, and on a `storage.create` that clones one.
`kubernetes_cluster_id`	string \| null	Set on the operations of a managed Kubernetes cluster.
`node_pool_id`	string \| null	Set on the operations of a Kubernetes node pool.
`kubernetes_host_id`	string	Set on a regional host cluster bootstrap (operator only); absent otherwise.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	string (date-time)
`actor`	string	Who asked for the operation: `user:<id>`, `token:<name>`, `operator`, `system:<component>`; empty on older operations.
`progress`	MigrationProgress	Present on `GET /v1/operations/{id}` while a `server.migrate` drives a live transfer.
`state`required	string	One of `reserved`, `detached`, `preparing`, `sending`, `switched`, `aborting`
`source_node_id`required	string
`target_node_id`required	string
`phase`required	string	How far the nodes report the current attempt.One of , `preparing`, `transferring`, `completed`, `failed`
`attempt`required	integer	Which send this is under the convergence policy, from 1.
`iteration`required	integer	Memory passes so far in the current attempt.
`transferred_bytes`required	integer
`total_bytes`required	integer	0 when the hypervisor does not report it.
`dirty_bytes_per_second`required	integer
`downtime_milliseconds`required	integer	The pause the guest took at handover, once completed.
`detail`required	string
`reported_at`required	string (date-time) \| null	The reporting node's clock.
`events`	array of OperationEvent	Present on `GET /v1/operations/{id}`; the newest 100 entries of the operation's log, oldest first.
`at`required	string (date-time)
`kind`required	string	For example `target_chosen`, `send_started`, `handed_over`, `undoing`, `cold_fallback`, `move_cancelled`, `recovery_started`, `succeeded`, `failed`.
`message`required	string
`data`required	object
`created_at`required	string (date-time)
`next_cursor`required	null

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.
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 with a short-lived bootstrap token. 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
Name	In	Type	Description
`id`required	path	string

Request bodyapplication/json · KubernetesNodePoolRequest

Request body fields
Field	Type	Description
`name`required	string
`plan`required	string	A server plan from list_plans.
`count`required	integer
`zones`	array of string	Zones of the cluster's region to spread nodes across; defaults to the cluster's zone.
`labels`	Labels	Keys of 1-63 letters, digits, `.`, `_`, `/` or `-`, starting and ending with a letter or digit; values of at most 255 printable characters.
`taints`	array of KubernetesTaint
`key`required	string
`value`	string
`effect`required	string	One of `NoSchedule`, `PreferNoSchedule`, `NoExecute`
`autoscaling`	KubernetesAutoscaling \| null
`min`required	integer
`max`required	integer
`public_ipv4`	boolean	Give 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
Field	Type	Description
`node_pool`required	KubernetesNodePool
`id`required	string
`cluster_id`required	string
`name`required	string
`plan`required	string
`count`required	integer
`zones`required	array of string
`labels`required	Labels	Keys of 1-63 letters, digits, `.`, `_`, `/` or `-`, starting and ending with a letter or digit; values of at most 255 printable characters.
`taints`required	array of KubernetesTaint
`key`required	string
`value`	string
`effect`required	string	One of `NoSchedule`, `PreferNoSchedule`, `NoExecute`
`autoscaling`required	KubernetesAutoscaling \| null
`min`required	integer
`max`required	integer
`public_ipv4`required	boolean
`version`required	string	The minor its nodes run or are rolling to.
`state`required	string	One of `creating`, `running`, `scaling`, `upgrading`, `deleting`, `deleted`, `error`
`nodes`required	array of KubernetesNode
`server_id`required	string
`hostname`required	string
`zone`required	string
`state`required	string	The server's state.
`is_ready`required	boolean	The node reports Ready to the cluster.
`kubelet_version`required	string	Empty until the node joined.
`public_ipv6`required	string \| null
`public_ipv4`required	string \| null
`active_operation`required	Operation \| null
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	string \| null
`node_id`	string	Set on node maintenance operations (operator only); absent otherwise.
`load_balancer_id`	string \| null	Set on the operations that create and delete a load balancer.
`database_id`	string \| null	Set on the operations that create and delete a managed database.
`edge_id`	string \| null	Set on the operations that sync and delete a network edge.
`snapshot_id`	string \| null	Set on the operations that create and delete a snapshot, and on a `storage.create` that clones one.
`kubernetes_cluster_id`	string \| null	Set on the operations of a managed Kubernetes cluster.
`node_pool_id`	string \| null	Set on the operations of a Kubernetes node pool.
`kubernetes_host_id`	string	Set on a regional host cluster bootstrap (operator only); absent otherwise.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	string (date-time)
`actor`	string	Who asked for the operation: `user:<id>`, `token:<name>`, `operator`, `system:<component>`; empty on older operations.
`progress`	MigrationProgress	Present on `GET /v1/operations/{id}` while a `server.migrate` drives a live transfer.
`state`required	string	One of `reserved`, `detached`, `preparing`, `sending`, `switched`, `aborting`
`source_node_id`required	string
`target_node_id`required	string
`phase`required	string	How far the nodes report the current attempt.One of , `preparing`, `transferring`, `completed`, `failed`
`attempt`required	integer	Which send this is under the convergence policy, from 1.
`iteration`required	integer	Memory passes so far in the current attempt.
`transferred_bytes`required	integer
`total_bytes`required	integer	0 when the hypervisor does not report it.
`dirty_bytes_per_second`required	integer
`downtime_milliseconds`required	integer	The pause the guest took at handover, once completed.
`detail`required	string
`reported_at`required	string (date-time) \| null	The reporting node's clock.
`events`	array of OperationEvent	Present on `GET /v1/operations/{id}`; the newest 100 entries of the operation's log, oldest first.
`at`required	string (date-time)
`kind`required	string	For example `target_chosen`, `send_started`, `handed_over`, `undoing`, `cold_fallback`, `move_cancelled`, `recovery_started`, `succeeded`, `failed`.
`message`required	string
`data`required	object
`created_at`required	string (date-time)
`operation`required	Operation
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	string \| null
`node_id`	string	Set on node maintenance operations (operator only); absent otherwise.
`load_balancer_id`	string \| null	Set on the operations that create and delete a load balancer.
`database_id`	string \| null	Set on the operations that create and delete a managed database.
`edge_id`	string \| null	Set on the operations that sync and delete a network edge.
`snapshot_id`	string \| null	Set on the operations that create and delete a snapshot, and on a `storage.create` that clones one.
`kubernetes_cluster_id`	string \| null	Set on the operations of a managed Kubernetes cluster.
`node_pool_id`	string \| null	Set on the operations of a Kubernetes node pool.
`kubernetes_host_id`	string	Set on a regional host cluster bootstrap (operator only); absent otherwise.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	string (date-time)
`actor`	string	Who asked for the operation: `user:<id>`, `token:<name>`, `operator`, `system:<component>`; empty on older operations.
`progress`	MigrationProgress	Present on `GET /v1/operations/{id}` while a `server.migrate` drives a live transfer.
`state`required	string	One of `reserved`, `detached`, `preparing`, `sending`, `switched`, `aborting`
`source_node_id`required	string
`target_node_id`required	string
`phase`required	string	How far the nodes report the current attempt.One of , `preparing`, `transferring`, `completed`, `failed`
`attempt`required	integer	Which send this is under the convergence policy, from 1.
`iteration`required	integer	Memory passes so far in the current attempt.
`transferred_bytes`required	integer
`total_bytes`required	integer	0 when the hypervisor does not report it.
`dirty_bytes_per_second`required	integer
`downtime_milliseconds`required	integer	The pause the guest took at handover, once completed.
`detail`required	string
`reported_at`required	string (date-time) \| null	The reporting node's clock.
`events`	array of OperationEvent	Present on `GET /v1/operations/{id}`; the newest 100 entries of the operation's log, oldest first.
`at`required	string (date-time)
`kind`required	string	For example `target_chosen`, `send_started`, `handed_over`, `undoing`, `cold_fallback`, `move_cancelled`, `recovery_started`, `succeeded`, `failed`.
`message`required	string
`data`required	object

400The request is invalid; detail says why.
401Not signed in, or the credential is invalid or expired.
402The account may not create billable resources. reason is payment_method_required while it has neither a default payment method nor a live credit (add one through POST /v1/account/billing/setup-session or redeem a coupon), or account_suspended while an invoice is overdue past the grace period (pay it; nothing already running is stopped) or Ankra staff suspended the account (contact support). GET /v1/account/billing reports the same standing.
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.
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
Name	In	Type	Description
`id`required	path	string
`pool`required	path	string	The node pool's id.

Responses

200The node pool.application/json

200 response fields
Field	Type	Description
`node_pool`required	KubernetesNodePool
`id`required	string
`cluster_id`required	string
`name`required	string
`plan`required	string
`count`required	integer
`zones`required	array of string
`labels`required	Labels	Keys of 1-63 letters, digits, `.`, `_`, `/` or `-`, starting and ending with a letter or digit; values of at most 255 printable characters.
`taints`required	array of KubernetesTaint
`key`required	string
`value`	string
`effect`required	string	One of `NoSchedule`, `PreferNoSchedule`, `NoExecute`
`autoscaling`required	KubernetesAutoscaling \| null
`min`required	integer
`max`required	integer
`public_ipv4`required	boolean
`version`required	string	The minor its nodes run or are rolling to.
`state`required	string	One of `creating`, `running`, `scaling`, `upgrading`, `deleting`, `deleted`, `error`
`nodes`required	array of KubernetesNode
`server_id`required	string
`hostname`required	string
`zone`required	string
`state`required	string	The server's state.
`is_ready`required	boolean	The node reports Ready to the cluster.
`kubelet_version`required	string	Empty until the node joined.
`public_ipv6`required	string \| null
`public_ipv4`required	string \| null
`active_operation`required	Operation \| null
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	string \| null
`node_id`	string	Set on node maintenance operations (operator only); absent otherwise.
`load_balancer_id`	string \| null	Set on the operations that create and delete a load balancer.
`database_id`	string \| null	Set on the operations that create and delete a managed database.
`edge_id`	string \| null	Set on the operations that sync and delete a network edge.
`snapshot_id`	string \| null	Set on the operations that create and delete a snapshot, and on a `storage.create` that clones one.
`kubernetes_cluster_id`	string \| null	Set on the operations of a managed Kubernetes cluster.
`node_pool_id`	string \| null	Set on the operations of a Kubernetes node pool.
`kubernetes_host_id`	string	Set on a regional host cluster bootstrap (operator only); absent otherwise.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	string (date-time)
`actor`	string	Who asked for the operation: `user:<id>`, `token:<name>`, `operator`, `system:<component>`; empty on older operations.
`progress`	MigrationProgress	Present on `GET /v1/operations/{id}` while a `server.migrate` drives a live transfer.
`state`required	string	One of `reserved`, `detached`, `preparing`, `sending`, `switched`, `aborting`
`source_node_id`required	string
`target_node_id`required	string
`phase`required	string	How far the nodes report the current attempt.One of , `preparing`, `transferring`, `completed`, `failed`
`attempt`required	integer	Which send this is under the convergence policy, from 1.
`iteration`required	integer	Memory passes so far in the current attempt.
`transferred_bytes`required	integer
`total_bytes`required	integer	0 when the hypervisor does not report it.
`dirty_bytes_per_second`required	integer
`downtime_milliseconds`required	integer	The pause the guest took at handover, once completed.
`detail`required	string
`reported_at`required	string (date-time) \| null	The reporting node's clock.
`events`	array of OperationEvent	Present on `GET /v1/operations/{id}`; the newest 100 entries of the operation's log, oldest first.
`at`required	string (date-time)
`kind`required	string	For example `target_chosen`, `send_started`, `handed_over`, `undoing`, `cold_fallback`, `move_cancelled`, `recovery_started`, `succeeded`, `failed`.
`message`required	string
`data`required	object
`created_at`required	string (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.
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.

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string
`pool`required	path	string	The node pool's id.

Request bodyapplication/json

Request body fields
Field	Type	Description
`count`	integer
`labels`	Labels	Keys of 1-63 letters, digits, `.`, `_`, `/` or `-`, starting and ending with a letter or digit; values of at most 255 printable characters.
`taints`	array of KubernetesTaint
`key`required	string
`value`	string
`effect`required	string	One of `NoSchedule`, `PreferNoSchedule`, `NoExecute`
`autoscaling`	KubernetesAutoscaling \| null
`min`required	integer
`max`required	integer

Responses

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

202 response fields
Field	Type	Description
`node_pool`required	KubernetesNodePool
`id`required	string
`cluster_id`required	string
`name`required	string
`plan`required	string
`count`required	integer
`zones`required	array of string
`labels`required	Labels	Keys of 1-63 letters, digits, `.`, `_`, `/` or `-`, starting and ending with a letter or digit; values of at most 255 printable characters.
`taints`required	array of KubernetesTaint
`key`required	string
`value`	string
`effect`required	string	One of `NoSchedule`, `PreferNoSchedule`, `NoExecute`
`autoscaling`required	KubernetesAutoscaling \| null
`min`required	integer
`max`required	integer
`public_ipv4`required	boolean
`version`required	string	The minor its nodes run or are rolling to.
`state`required	string	One of `creating`, `running`, `scaling`, `upgrading`, `deleting`, `deleted`, `error`
`nodes`required	array of KubernetesNode
`server_id`required	string
`hostname`required	string
`zone`required	string
`state`required	string	The server's state.
`is_ready`required	boolean	The node reports Ready to the cluster.
`kubelet_version`required	string	Empty until the node joined.
`public_ipv6`required	string \| null
`public_ipv4`required	string \| null
`active_operation`required	Operation \| null
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	string \| null
`node_id`	string	Set on node maintenance operations (operator only); absent otherwise.
`load_balancer_id`	string \| null	Set on the operations that create and delete a load balancer.
`database_id`	string \| null	Set on the operations that create and delete a managed database.
`edge_id`	string \| null	Set on the operations that sync and delete a network edge.
`snapshot_id`	string \| null	Set on the operations that create and delete a snapshot, and on a `storage.create` that clones one.
`kubernetes_cluster_id`	string \| null	Set on the operations of a managed Kubernetes cluster.
`node_pool_id`	string \| null	Set on the operations of a Kubernetes node pool.
`kubernetes_host_id`	string	Set on a regional host cluster bootstrap (operator only); absent otherwise.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	string (date-time)
`actor`	string	Who asked for the operation: `user:<id>`, `token:<name>`, `operator`, `system:<component>`; empty on older operations.
`progress`	MigrationProgress	Present on `GET /v1/operations/{id}` while a `server.migrate` drives a live transfer.
`state`required	string	One of `reserved`, `detached`, `preparing`, `sending`, `switched`, `aborting`
`source_node_id`required	string
`target_node_id`required	string
`phase`required	string	How far the nodes report the current attempt.One of , `preparing`, `transferring`, `completed`, `failed`
`attempt`required	integer	Which send this is under the convergence policy, from 1.
`iteration`required	integer	Memory passes so far in the current attempt.
`transferred_bytes`required	integer
`total_bytes`required	integer	0 when the hypervisor does not report it.
`dirty_bytes_per_second`required	integer
`downtime_milliseconds`required	integer	The pause the guest took at handover, once completed.
`detail`required	string
`reported_at`required	string (date-time) \| null	The reporting node's clock.
`events`	array of OperationEvent	Present on `GET /v1/operations/{id}`; the newest 100 entries of the operation's log, oldest first.
`at`required	string (date-time)
`kind`required	string	For example `target_chosen`, `send_started`, `handed_over`, `undoing`, `cold_fallback`, `move_cancelled`, `recovery_started`, `succeeded`, `failed`.
`message`required	string
`data`required	object
`created_at`required	string (date-time)
`operation`required	Operation
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	string \| null
`node_id`	string	Set on node maintenance operations (operator only); absent otherwise.
`load_balancer_id`	string \| null	Set on the operations that create and delete a load balancer.
`database_id`	string \| null	Set on the operations that create and delete a managed database.
`edge_id`	string \| null	Set on the operations that sync and delete a network edge.
`snapshot_id`	string \| null	Set on the operations that create and delete a snapshot, and on a `storage.create` that clones one.
`kubernetes_cluster_id`	string \| null	Set on the operations of a managed Kubernetes cluster.
`node_pool_id`	string \| null	Set on the operations of a Kubernetes node pool.
`kubernetes_host_id`	string	Set on a regional host cluster bootstrap (operator only); absent otherwise.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	string (date-time)
`actor`	string	Who asked for the operation: `user:<id>`, `token:<name>`, `operator`, `system:<component>`; empty on older operations.
`progress`	MigrationProgress	Present on `GET /v1/operations/{id}` while a `server.migrate` drives a live transfer.
`state`required	string	One of `reserved`, `detached`, `preparing`, `sending`, `switched`, `aborting`
`source_node_id`required	string
`target_node_id`required	string
`phase`required	string	How far the nodes report the current attempt.One of , `preparing`, `transferring`, `completed`, `failed`
`attempt`required	integer	Which send this is under the convergence policy, from 1.
`iteration`required	integer	Memory passes so far in the current attempt.
`transferred_bytes`required	integer
`total_bytes`required	integer	0 when the hypervisor does not report it.
`dirty_bytes_per_second`required	integer
`downtime_milliseconds`required	integer	The pause the guest took at handover, once completed.
`detail`required	string
`reported_at`required	string (date-time) \| null	The reporting node's clock.
`events`	array of OperationEvent	Present on `GET /v1/operations/{id}`; the newest 100 entries of the operation's log, oldest first.
`at`required	string (date-time)
`kind`required	string	For example `target_chosen`, `send_started`, `handed_over`, `undoing`, `cold_fallback`, `move_cancelled`, `recovery_started`, `succeeded`, `failed`.
`message`required	string
`data`required	object

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.
422The account would exceed a quota; detail names the limit.
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
Name	In	Type	Description
`id`required	path	string
`pool`required	path	string	The node pool's id.

Responses

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

202 response fields
Field	Type	Description
`operation`required	Operation
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	string \| null
`node_id`	string	Set on node maintenance operations (operator only); absent otherwise.
`load_balancer_id`	string \| null	Set on the operations that create and delete a load balancer.
`database_id`	string \| null	Set on the operations that create and delete a managed database.
`edge_id`	string \| null	Set on the operations that sync and delete a network edge.
`snapshot_id`	string \| null	Set on the operations that create and delete a snapshot, and on a `storage.create` that clones one.
`kubernetes_cluster_id`	string \| null	Set on the operations of a managed Kubernetes cluster.
`node_pool_id`	string \| null	Set on the operations of a Kubernetes node pool.
`kubernetes_host_id`	string	Set on a regional host cluster bootstrap (operator only); absent otherwise.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	string (date-time)
`actor`	string	Who asked for the operation: `user:<id>`, `token:<name>`, `operator`, `system:<component>`; empty on older operations.
`progress`	MigrationProgress	Present on `GET /v1/operations/{id}` while a `server.migrate` drives a live transfer.
`state`required	string	One of `reserved`, `detached`, `preparing`, `sending`, `switched`, `aborting`
`source_node_id`required	string
`target_node_id`required	string
`phase`required	string	How far the nodes report the current attempt.One of , `preparing`, `transferring`, `completed`, `failed`
`attempt`required	integer	Which send this is under the convergence policy, from 1.
`iteration`required	integer	Memory passes so far in the current attempt.
`transferred_bytes`required	integer
`total_bytes`required	integer	0 when the hypervisor does not report it.
`dirty_bytes_per_second`required	integer
`downtime_milliseconds`required	integer	The pause the guest took at handover, once completed.
`detail`required	string
`reported_at`required	string (date-time) \| null	The reporting node's clock.
`events`	array of OperationEvent	Present on `GET /v1/operations/{id}`; the newest 100 entries of the operation's log, oldest first.
`at`required	string (date-time)
`kind`required	string	For example `target_chosen`, `send_started`, `handed_over`, `undoing`, `cold_fallback`, `move_cancelled`, `recovery_started`, `succeeded`, `failed`.
`message`required	string
`data`required	object

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.
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"

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
Name	In	Type	Description
`id`required	path	string

Request bodyapplication/json

Request body fields
Field	Type	Description
`snapshot`required	string	The `name` of a snapshot from list_kubernetes_cluster_etcd_snapshots.

Responses

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

202 response fields
Field	Type	Description
`operation`required	Operation
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	string \| null
`node_id`	string	Set on node maintenance operations (operator only); absent otherwise.
`load_balancer_id`	string \| null	Set on the operations that create and delete a load balancer.
`database_id`	string \| null	Set on the operations that create and delete a managed database.
`edge_id`	string \| null	Set on the operations that sync and delete a network edge.
`snapshot_id`	string \| null	Set on the operations that create and delete a snapshot, and on a `storage.create` that clones one.
`kubernetes_cluster_id`	string \| null	Set on the operations of a managed Kubernetes cluster.
`node_pool_id`	string \| null	Set on the operations of a Kubernetes node pool.
`kubernetes_host_id`	string	Set on a regional host cluster bootstrap (operator only); absent otherwise.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	string (date-time)
`actor`	string	Who asked for the operation: `user:<id>`, `token:<name>`, `operator`, `system:<component>`; empty on older operations.
`progress`	MigrationProgress	Present on `GET /v1/operations/{id}` while a `server.migrate` drives a live transfer.
`state`required	string	One of `reserved`, `detached`, `preparing`, `sending`, `switched`, `aborting`
`source_node_id`required	string
`target_node_id`required	string
`phase`required	string	How far the nodes report the current attempt.One of , `preparing`, `transferring`, `completed`, `failed`
`attempt`required	integer	Which send this is under the convergence policy, from 1.
`iteration`required	integer	Memory passes so far in the current attempt.
`transferred_bytes`required	integer
`total_bytes`required	integer	0 when the hypervisor does not report it.
`dirty_bytes_per_second`required	integer
`downtime_milliseconds`required	integer	The pause the guest took at handover, once completed.
`detail`required	string
`reported_at`required	string (date-time) \| null	The reporting node's clock.
`events`	array of OperationEvent	Present on `GET /v1/operations/{id}`; the newest 100 entries of the operation's log, oldest first.
`at`required	string (date-time)
`kind`required	string	For example `target_chosen`, `send_started`, `handed_over`, `undoing`, `cold_fallback`, `move_cancelled`, `recovery_started`, `succeeded`, `failed`.
`message`required	string
`data`required	object

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.
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
Name	In	Type	Description
`id`required	path	string

Responses

200The ExecCredential.application/json · KubernetesExecCredential

200 response fields
Field	Type	Description
`apiVersion`required	string	One of `client.authentication.k8s.io/v1`
`kind`required	string	One of `ExecCredential`
`status`required	object
`token`required	string
`expirationTimestamp`required	string (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.
503No capacity or address is free, or a host did not answer; 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
Name	In	Type	Description
`id`required	path	string

Request bodyapplication/json

Request body fields
Field	Type	Description
`version`required	string

Responses

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

202 response fields
Field	Type	Description
`kubernetes_cluster`required	KubernetesCluster
`id`required	string
`zone`required	string
`region`required	string
`name`required	string
`version`required	string	The minor, e.g. 1.36.
`kubernetes_version`required	string	The patch release the control plane runs, e.g. v1.36.5.
`available_upgrade`required	string \| null	The next minor this cluster can upgrade to.
`state`required	string	One of `creating`, `running`, `upgrading`, `restoring`, `error`, `deleting`, `deleted`
`network_id`required	string
`public_ipv4`required	boolean
`private_endpoint`required	boolean
`endpoint`required	string \| null	The API server URL on IPv6; null until the control plane is up.
`endpoint_ipv4`required	string \| null	The API server URL on IPv4, with the add-on.
`oidc_issuer_url`required	string
`labels`required	Labels	Keys of 1-63 letters, digits, `.`, `_`, `/` or `-`, starting and ending with a letter or digit; values of at most 255 printable characters.
`health`required	KubernetesHealth
`api_server`required	string	One of `healthy`, `unhealthy`, `unknown`
`etcd_members_ready`required	integer
`etcd_members_total`required	integer
`has_etcd_quorum`required	boolean
`nodes_ready`required	integer
`nodes_total`required	integer
`observed_at`required	string (date-time) \| null
`detail`required	string
`addons`required	array of KubernetesAddon
`name`required	string
`version`required	string	The pinned Helm chart version.
`etcd_snapshot_schedule`required	string
`etcd_snapshot_retention`required	integer
`node_pools`	array of KubernetesNodePool	Only on get_kubernetes_cluster.
`id`required	string
`cluster_id`required	string
`name`required	string
`plan`required	string
`count`required	integer
`zones`required	array of string
`labels`required	Labels	Keys of 1-63 letters, digits, `.`, `_`, `/` or `-`, starting and ending with a letter or digit; values of at most 255 printable characters.
`taints`required	array of KubernetesTaint
`key`required	string
`value`	string
`effect`required	string	One of `NoSchedule`, `PreferNoSchedule`, `NoExecute`
`autoscaling`required	KubernetesAutoscaling \| null
`min`required	integer
`max`required	integer
`public_ipv4`required	boolean
`version`required	string	The minor its nodes run or are rolling to.
`state`required	string	One of `creating`, `running`, `scaling`, `upgrading`, `deleting`, `deleted`, `error`
`nodes`required	array of KubernetesNode
`server_id`required	string
`hostname`required	string
`zone`required	string
`state`required	string	The server's state.
`is_ready`required	boolean	The node reports Ready to the cluster.
`kubelet_version`required	string	Empty until the node joined.
`public_ipv6`required	string \| null
`public_ipv4`required	string \| null
`active_operation`required	Operation \| null
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	string \| null
`node_id`	string	Set on node maintenance operations (operator only); absent otherwise.
`load_balancer_id`	string \| null	Set on the operations that create and delete a load balancer.
`database_id`	string \| null	Set on the operations that create and delete a managed database.
`edge_id`	string \| null	Set on the operations that sync and delete a network edge.
`snapshot_id`	string \| null	Set on the operations that create and delete a snapshot, and on a `storage.create` that clones one.
`kubernetes_cluster_id`	string \| null	Set on the operations of a managed Kubernetes cluster.
`node_pool_id`	string \| null	Set on the operations of a Kubernetes node pool.
`kubernetes_host_id`	string	Set on a regional host cluster bootstrap (operator only); absent otherwise.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	string (date-time)
`actor`	string	Who asked for the operation: `user:<id>`, `token:<name>`, `operator`, `system:<component>`; empty on older operations.
`progress`	MigrationProgress	Present on `GET /v1/operations/{id}` while a `server.migrate` drives a live transfer.
`events`	array of OperationEvent	Present on `GET /v1/operations/{id}`; the newest 100 entries of the operation's log, oldest first.
`created_at`required	string (date-time)
`platform`required	KubernetesPlatformRegistration	The 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).
`state`required	string	One of `pending`, `unlinked`, `registered`, `failed`, `deregistered`
`organisation_id`required	string \| null
`cluster_id`required	string \| null	The platform's identifier of the cluster.
`url`required	string \| null
`reason`required	string
`next_attempt_at`required	string (date-time) \| null	When a pending registration is tried again.
`registered_at`required	string (date-time) \| null
`active_operation`required	Operation \| null
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	string \| null
`node_id`	string	Set on node maintenance operations (operator only); absent otherwise.
`load_balancer_id`	string \| null	Set on the operations that create and delete a load balancer.
`database_id`	string \| null	Set on the operations that create and delete a managed database.
`edge_id`	string \| null	Set on the operations that sync and delete a network edge.
`snapshot_id`	string \| null	Set on the operations that create and delete a snapshot, and on a `storage.create` that clones one.
`kubernetes_cluster_id`	string \| null	Set on the operations of a managed Kubernetes cluster.
`node_pool_id`	string \| null	Set on the operations of a Kubernetes node pool.
`kubernetes_host_id`	string	Set on a regional host cluster bootstrap (operator only); absent otherwise.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	string (date-time)
`actor`	string	Who asked for the operation: `user:<id>`, `token:<name>`, `operator`, `system:<component>`; empty on older operations.
`progress`	MigrationProgress	Present on `GET /v1/operations/{id}` while a `server.migrate` drives a live transfer.
`state`required	string	One of `reserved`, `detached`, `preparing`, `sending`, `switched`, `aborting`
`source_node_id`required	string
`target_node_id`required	string
`phase`required	string	How far the nodes report the current attempt.One of , `preparing`, `transferring`, `completed`, `failed`
`attempt`required	integer	Which send this is under the convergence policy, from 1.
`iteration`required	integer	Memory passes so far in the current attempt.
`transferred_bytes`required	integer
`total_bytes`required	integer	0 when the hypervisor does not report it.
`dirty_bytes_per_second`required	integer
`downtime_milliseconds`required	integer	The pause the guest took at handover, once completed.
`detail`required	string
`reported_at`required	string (date-time) \| null	The reporting node's clock.
`events`	array of OperationEvent	Present on `GET /v1/operations/{id}`; the newest 100 entries of the operation's log, oldest first.
`at`required	string (date-time)
`kind`required	string	For example `target_chosen`, `send_started`, `handed_over`, `undoing`, `cold_fallback`, `move_cancelled`, `recovery_started`, `succeeded`, `failed`.
`message`required	string
`data`required	object
`created_at`required	string (date-time)
`operation`required	Operation
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	string \| null
`node_id`	string	Set on node maintenance operations (operator only); absent otherwise.
`load_balancer_id`	string \| null	Set on the operations that create and delete a load balancer.
`database_id`	string \| null	Set on the operations that create and delete a managed database.
`edge_id`	string \| null	Set on the operations that sync and delete a network edge.
`snapshot_id`	string \| null	Set on the operations that create and delete a snapshot, and on a `storage.create` that clones one.
`kubernetes_cluster_id`	string \| null	Set on the operations of a managed Kubernetes cluster.
`node_pool_id`	string \| null	Set on the operations of a Kubernetes node pool.
`kubernetes_host_id`	string	Set on a regional host cluster bootstrap (operator only); absent otherwise.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	string (date-time)
`actor`	string	Who asked for the operation: `user:<id>`, `token:<name>`, `operator`, `system:<component>`; empty on older operations.
`progress`	MigrationProgress	Present on `GET /v1/operations/{id}` while a `server.migrate` drives a live transfer.
`state`required	string	One of `reserved`, `detached`, `preparing`, `sending`, `switched`, `aborting`
`source_node_id`required	string
`target_node_id`required	string
`phase`required	string	How far the nodes report the current attempt.One of , `preparing`, `transferring`, `completed`, `failed`
`attempt`required	integer	Which send this is under the convergence policy, from 1.
`iteration`required	integer	Memory passes so far in the current attempt.
`transferred_bytes`required	integer
`total_bytes`required	integer	0 when the hypervisor does not report it.
`dirty_bytes_per_second`required	integer
`downtime_milliseconds`required	integer	The pause the guest took at handover, once completed.
`detail`required	string
`reported_at`required	string (date-time) \| null	The reporting node's clock.
`events`	array of OperationEvent	Present on `GET /v1/operations/{id}`; the newest 100 entries of the operation's log, oldest first.
`at`required	string (date-time)
`kind`required	string	For example `target_chosen`, `send_started`, `handed_over`, `undoing`, `cold_fallback`, `move_cancelled`, `recovery_started`, `succeeded`, `failed`.
`message`required	string
`data`required	object

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.
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"
}'

The Kubernetes versions a cluster can run, with their pinned add-ons 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.

Responses

200The versions.application/json · KubernetesVersionList

200 response fields
Field	Type	Description
`items`required	array of KubernetesVersion
`version`required	string	The minor.
`kubernetes_version`required	string	The patch release this minor runs.
`is_default`required	boolean
`addons`required	array of KubernetesAddon
`name`required	string
`version`required	string	The pinned Helm chart version.
`vcluster_chart_version`required	string
`control_plane_price_monthly_cents`required	integer	Per cluster, billed per hour.
`ipv4_price_monthly_cents`required	integer	The IPv4 API endpoint add-on, billed per hour.

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).
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
Field	Type	Description
`issuer`required	string
`jwks_uri`required	string
`response_types_supported`required	array of string
`subject_types_supported`required	array of string
`id_token_signing_alg_values_supported`required	array of string
`claims_supported`	array of string

503No capacity or address is free, or a host did not answer; 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
Field	Type	Description
`keys`required	array of object
`kty`required	string
`kid`required	string
`use`required	string
`alg`required	string
`crv`	string
`x`	string
`y`	string

503No capacity or address is free, or a host did not answer; try again later.
defaultAny other error, usually 500.

Example

bash

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