API reference · Managed services

Dev clusters

7 operations of the Ankra Cloud API: Dev clusters (ADR 0012): Kubernetes for development on one server in the account. The server runs k3s as control plane and only node and is its own network edge: it serves the Kubernetes API (port 6443) and the cluster's ingress (ports 80 and 443) on its own public addresses. Billed as its server; not for production.

The account's dev clusters, newest first#

GET/v1/dev-clusters

Operation: list_dev_clusters
Credentials: API token, Portal session
Requires: Permission read

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

200A page of dev clusters (limit at most 100, default 50). Deleted clusters are not listed.application/json · DevClusterList

200 response fields
Field	Type	Description
`items`required	array of DevCluster
`id`required	string
`zone`required	string
`region`required	string
`name`required	string
`version`required	string	The Kubernetes minor.
`k3s_version`required	string	The k3s release installed when the cluster was created.
`plan`required	string	The server's plan.
`state`required	string	`creating` until the cluster's API answers; `running`; `error` when it never came up or lost its server (`failure_reason` says which; only a deletion leaves it); `deleting` until its server is gone; `deleted`.One of `creating`, `running`, `error`, `deleting`, `deleted`
`public_ipv4`required	boolean	Whether the server holds a public IPv4 (the add-on) and the cluster is dual-stack.
`network_id`required	string \| null	The private network the server also joins.
`server_id`required	string \| null	The cluster's server, in the account's servers.
`endpoint`required	string \| null	The API server URL on IPv6, once the server has its address.
`endpoint_ipv4`required	string \| null	The API server URL on IPv4, with `public_ipv4`.
`ipv6_address`required	string \| null	The server's public IPv6 address: the API on 6443, ingress on 80 and 443.
`ipv4_address`required	string \| null	The server's public IPv4 address, with `public_ipv4`.
`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	DevClusterHealth
`api_server`required	string	Whether the API answered /readyz when last observed; `unknown` before the first observation.One of `healthy`, `unhealthy`, `unknown`
`node_ready`required	boolean	Whether the node reported Ready.
`observed_at`required	string (date-time) \| null
`detail`required	string	What is wrong, empty when nothing is.
`failure_reason`required	string \| null	Why a cluster in `error` failed.
`production_recommended`required	boolean	Always false: a dev cluster is one server.One of `false`
`production_warning`required	string	What running on one server means, to show wherever the cluster is shown.
`created_at`required	string (date-time)
`updated_at`required	string (date-time)
`next_cursor`required	string \| null	Pass as `?cursor=` for the next page; null on the last page.

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/dev-clusters' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Create a dev cluster#

POST/v1/dev-clusters

Operation: create_dev_cluster
Credentials: API token, Portal session
Requires: Permission operate

Creates one server of plan in zone in your account (image Debian 13, labelled kubernetes.ankra.cloud/dev-cluster) that installs k3s at the version's pinned release and is the cluster's control plane, its only node and its network edge: the Kubernetes API is served on port 6443 and the bundled ingress (Traefik behind ServiceLB) on ports 80 and 443 of the server's own addresses. The server always has its public IPv6 /64; public_ipv4 adds a public IPv4 (the server add-on) and makes the cluster dual-stack. Volumes are local-path volumes on the server's disk. The cluster is creating until its API answers (a few minutes), then running; one that does not come up within 30 minutes turns error with a failure_reason. What the server is refused for (capacity, quota, SSH keys) is this request's answer and leaves nothing behind. Billed as the server, with no fee for the cluster. An account may hold 5 dev clusters. A dev cluster has no high availability, node pools, upgrades or snapshots: every one carries production_recommended: false. Recorded in the account's audit log (dev_cluster.create).

Request bodyapplication/json · CreateDevCluster

Request body fields
Field	Type	Description
`zone`required	string	A zone that offers dev clusters (list_dev_cluster_versions).
`name`required	string	DNS label, 2 to 40 characters, unique among the account's dev clusters.
`plan`required	string	A server plan with at least `minimum_memory_mebibytes` of memory.
`version`	string	A minor from list_dev_cluster_versions; defaults to the default one.
`public_ipv4`	boolean	Give the server a public IPv4 too (paid add-on) and make the cluster dual-stack. Default false: IPv6 only.
`network_id`	string	A private network of the zone the server also joins.
`ssh_keys`	array of string	SSH public keys for the server. Without these and `ssh_key_ids` nobody can log in to it.
`ssh_key_ids`	array of string	Keys from the account's library for the server.
`labels`	Labels	Keys of 1-63 letters, digits, `.`, `_`, `/` or `-`, starting and ending with a letter or digit; values of at most 255 printable characters.

Responses

201The creating dev cluster.application/json · DevClusterEnvelope

201 response fields
Field	Type	Description
`dev_cluster`required	DevCluster
`id`required	string
`zone`required	string
`region`required	string
`name`required	string
`version`required	string	The Kubernetes minor.
`k3s_version`required	string	The k3s release installed when the cluster was created.
`plan`required	string	The server's plan.
`state`required	string	`creating` until the cluster's API answers; `running`; `error` when it never came up or lost its server (`failure_reason` says which; only a deletion leaves it); `deleting` until its server is gone; `deleted`.One of `creating`, `running`, `error`, `deleting`, `deleted`
`public_ipv4`required	boolean	Whether the server holds a public IPv4 (the add-on) and the cluster is dual-stack.
`network_id`required	string \| null	The private network the server also joins.
`server_id`required	string \| null	The cluster's server, in the account's servers.
`endpoint`required	string \| null	The API server URL on IPv6, once the server has its address.
`endpoint_ipv4`required	string \| null	The API server URL on IPv4, with `public_ipv4`.
`ipv6_address`required	string \| null	The server's public IPv6 address: the API on 6443, ingress on 80 and 443.
`ipv4_address`required	string \| null	The server's public IPv4 address, with `public_ipv4`.
`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	DevClusterHealth
`api_server`required	string	Whether the API answered /readyz when last observed; `unknown` before the first observation.One of `healthy`, `unhealthy`, `unknown`
`node_ready`required	boolean	Whether the node reported Ready.
`observed_at`required	string (date-time) \| null
`detail`required	string	What is wrong, empty when nothing is.
`failure_reason`required	string \| null	Why a cluster in `error` failed.
`production_recommended`required	boolean	Always false: a dev cluster is one server.One of `false`
`production_warning`required	string	What running on one server means, to show wherever the cluster is shown.
`created_at`required	string (date-time)
`updated_at`required	string (date-time)

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).
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/dev-clusters' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "zone": "string",
  "name": "string",
  "plan": "string"
}'

One of the account's dev clusters#

GET/v1/dev-clusters/{id}

Operation: get_dev_cluster
Credentials: API token, Portal session
Requires: Permission read

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Responses

200The dev cluster.application/json · DevClusterEnvelope

200 response fields
Field	Type	Description
`dev_cluster`required	DevCluster
`id`required	string
`zone`required	string
`region`required	string
`name`required	string
`version`required	string	The Kubernetes minor.
`k3s_version`required	string	The k3s release installed when the cluster was created.
`plan`required	string	The server's plan.
`state`required	string	`creating` until the cluster's API answers; `running`; `error` when it never came up or lost its server (`failure_reason` says which; only a deletion leaves it); `deleting` until its server is gone; `deleted`.One of `creating`, `running`, `error`, `deleting`, `deleted`
`public_ipv4`required	boolean	Whether the server holds a public IPv4 (the add-on) and the cluster is dual-stack.
`network_id`required	string \| null	The private network the server also joins.
`server_id`required	string \| null	The cluster's server, in the account's servers.
`endpoint`required	string \| null	The API server URL on IPv6, once the server has its address.
`endpoint_ipv4`required	string \| null	The API server URL on IPv4, with `public_ipv4`.
`ipv6_address`required	string \| null	The server's public IPv6 address: the API on 6443, ingress on 80 and 443.
`ipv4_address`required	string \| null	The server's public IPv4 address, with `public_ipv4`.
`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	DevClusterHealth
`api_server`required	string	Whether the API answered /readyz when last observed; `unknown` before the first observation.One of `healthy`, `unhealthy`, `unknown`
`node_ready`required	boolean	Whether the node reported Ready.
`observed_at`required	string (date-time) \| null
`detail`required	string	What is wrong, empty when nothing is.
`failure_reason`required	string \| null	Why a cluster in `error` failed.
`production_recommended`required	boolean	Always false: a dev cluster is one server.One of `false`
`production_warning`required	string	What running on one server means, to show wherever the cluster is shown.
`created_at`required	string (date-time)
`updated_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/dev-clusters/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Delete a dev cluster with its server#

DELETE/v1/dev-clusters/{id}

Operation: delete_dev_cluster
Credentials: API token, Portal session
Requires: Permission operate

The cluster becomes deleting, its server is deleted with its disk (every workload and local-path volume goes with it), and it is deleted once the server is gone. 409 while it is deleting already. Recorded in the account's audit log (dev_cluster.delete).

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Responses

200The deleting dev cluster.application/json · DevClusterEnvelope

200 response fields
Field	Type	Description
`dev_cluster`required	DevCluster
`id`required	string
`zone`required	string
`region`required	string
`name`required	string
`version`required	string	The Kubernetes minor.
`k3s_version`required	string	The k3s release installed when the cluster was created.
`plan`required	string	The server's plan.
`state`required	string	`creating` until the cluster's API answers; `running`; `error` when it never came up or lost its server (`failure_reason` says which; only a deletion leaves it); `deleting` until its server is gone; `deleted`.One of `creating`, `running`, `error`, `deleting`, `deleted`
`public_ipv4`required	boolean	Whether the server holds a public IPv4 (the add-on) and the cluster is dual-stack.
`network_id`required	string \| null	The private network the server also joins.
`server_id`required	string \| null	The cluster's server, in the account's servers.
`endpoint`required	string \| null	The API server URL on IPv6, once the server has its address.
`endpoint_ipv4`required	string \| null	The API server URL on IPv4, with `public_ipv4`.
`ipv6_address`required	string \| null	The server's public IPv6 address: the API on 6443, ingress on 80 and 443.
`ipv4_address`required	string \| null	The server's public IPv4 address, with `public_ipv4`.
`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	DevClusterHealth
`api_server`required	string	Whether the API answered /readyz when last observed; `unknown` before the first observation.One of `healthy`, `unhealthy`, `unknown`
`node_ready`required	boolean	Whether the node reported Ready.
`observed_at`required	string (date-time) \| null
`detail`required	string	What is wrong, empty when nothing is.
`failure_reason`required	string \| null	Why a cluster in `error` failed.
`production_recommended`required	boolean	Always false: a dev cluster is one server.One of `false`
`production_warning`required	string	What running on one server means, to show wherever the cluster is shown.
`created_at`required	string (date-time)
`updated_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.
defaultAny other error, usually 500.

Example

bash

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

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

GET/v1/dev-clusters/{id}/kubeconfig

Operation: get_dev_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). When the deployment has the Kubernetes OIDC issuer, the oidc context signs you in as yourself instead: its exec credential plugin calls get_dev_cluster_token, and your Ankra role decides your Kubernetes role (owner and admin: cluster-admin, member: edit, viewer: view). Both verify the API server against the cluster's own authority. 409 while the cluster is not running. Recorded in the account's audit log (dev_cluster.kubeconfig).

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/dev-clusters/<id>/kubeconfig' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

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

GET/v1/dev-clusters/{id}/token

Operation: get_dev_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, 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). 503 when the deployment has no issuer; 409 once the cluster is being deleted. Recorded in the account's audit log (dev_cluster.token).

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.
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/dev-clusters/<id>/token' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

The Kubernetes versions a dev cluster can run, and where and on what terms dev clusters are offered#

GET/v1/dev-clusters/versions

Operation: list_dev_cluster_versions
Credentials: API token, Portal session
Requires: Permission read

items are the Kubernetes minors on offer with the k3s release each installs. is_available is false while the deployment offers dev clusters in no zone (creating one then answers 503). all_zones means every zone offers them and zones is empty; otherwise zones names the zones that do. A dev cluster needs a plan with at least minimum_memory_mebibytes of memory. It has no fee of its own: it is billed as its server, plus ipv4_price_monthly_cents a month with public_ipv4. production_warning says why it is not for production.

Responses

200The versions and the offer.application/json · DevClusterVersions

200 response fields
Field	Type	Description
`items`required	array of object
`version`required	string
`k3s_version`required	string
`is_default`required	boolean
`is_available`required	boolean	Whether any zone offers dev clusters.
`all_zones`required	boolean	Every zone offers dev clusters; `zones` is then empty.
`zones`required	array of string	The zones that offer dev clusters, unless `all_zones`.
`minimum_memory_mebibytes`required	integer	The smallest plan a dev cluster runs on.
`ipv4_price_monthly_cents`required	integer	What `public_ipv4` adds a month.
`production_warning`required	string

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/dev-clusters/versions' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"