AnkraDocs
Console

API reference · Managed services

Dev clusters

9 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
NameInTypeDescription
cursorquerystringThe next_cursor of the previous page.
limitqueryintegerPage 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
FieldTypeDescription
itemsrequiredarray of DevCluster
idrequiredstring
zonerequiredstring
regionrequiredstring
namerequiredstring
versionrequiredstringThe Kubernetes minor.
k3s_versionrequiredstringThe k3s release installed when the cluster was created.
planrequiredstringThe server's plan.
staterequiredstringcreating 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_ipv4requiredbooleanWhether the server holds a public IPv4 (the add-on). A cluster created with it is dual-stack; one that got it later (public_ipv4_change.added_at) serves ingress on IPv4 through a forwarder.
network_idrequiredstring | nullThe private network the server also joins.
server_idrequiredstring | nullThe cluster's server, in the account's servers.
endpointrequiredstring | nullThe API server URL on IPv6, once the server has its address.
endpoint_ipv4requiredstring | nullThe API server URL on IPv4, with public_ipv4.
ipv6_addressrequiredstring | nullThe server's public IPv6 address: the API on 6443, ingress on 80 and 443.
ipv4_addressrequiredstring | nullThe server's public IPv4 address, with public_ipv4.
labelsrequiredLabelsKeys of 1-63 letters, digits, ., _, / or -, starting and ending with a letter or digit; values of at most 255 printable characters. On a server, keys under kubernetes.ankra.cloud/ and playground.ankra.cloud/ are set by the platform only.
healthrequiredDevClusterHealth
api_serverrequiredstringWhether the API answered /readyz when last observed; unknown before the first observation.One of healthy, unhealthy, unknown
node_readyrequiredbooleanWhether the node reported Ready.
observed_atrequiredstring (date-time) | null
detailrequiredstringWhat is wrong, empty when nothing is.
failure_reasonrequiredstring | nullWhy a cluster in error failed.
plan_changenull | DevClusterPlanChangeThe plan change under way (change_dev_cluster_plan), or the last one that did not take; null when there is neither.
desired_planrequiredstring | nullThe plan the server is moving to while a change is under way; the cluster's own plan while it returns to it after a change that did not take. Null once the change is over.
requested_atrequiredstring (date-time) | nullWhen the change, or the return to the old plan, began.
failurerequiredstring | nullWhy the last change did not take; the cluster then kept, or returned to, its plan.
public_ipv4_changenull | DevClusterPublicIPv4ChangeThe public IPv4 addition under way (add_dev_cluster_public_ipv4), the finished one of a cluster created without the add-on, or the last one that did not take; null when there is none.
requested_atrequiredstring (date-time) | nullWhen the addition under way began; null once it is over.
added_atrequiredstring (date-time) | nullWhen the add-on was added to the running cluster. Its pod and Service networks stayed IPv6 only, and its node carries the IPv4 forwarder for ports 80 and 443.
failurerequiredstring | nullWhy the last addition did not take (the cluster has no public IPv4), or, with added_at, what of it is still missing (the forwarder waits for the cluster's API).
production_recommendedrequiredbooleanAlways false: a dev cluster is one server.One of false
production_warningrequiredstringWhat running on one server means, to show wherever the cluster is shown.
is_trialbooleanCreated without a payment method: free, and deleted with its server at trial_expires_at unless the account saves a card first.
trial_expires_atstring (date-time) | nullWhen a live trial is deleted; null once it converted or for a paid cluster.
trial_converted_atstring (date-time) | nullWhen the account saved a card and the trial became an ordinary cluster, its server billed from the next full hour.
bootstrap_chartsarray of DevClusterBootstrapChartViewThe charts k3s installed at first boot (bootstrap_charts of the create), never with their values.
namerequiredstringThe Helm release and the HelmChart object in kube-system.
namespacerequiredstringThe namespace the chart is installed into.
repositoryrequiredstring
chartrequiredstring
versionrequiredstring
created_atrequiredstring (date-time)
updated_atrequiredstring (date-time)
next_cursorrequiredstring | nullPass 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).
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/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. default_firewall starts the server behind a firewall open only on the cluster's ports. bootstrap_charts are Helm charts (from registry.ankra.cloud, pinned) that k3s installs itself at first boot, so they need no inbound reach to the cluster; their values_yaml is sealed and never answered. 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).

Creating one needs a payment method or a credit that covers it, like every billable create (402 otherwise), with one exception: an account linked to an Ankra platform organisation that has neither gets a free trial (is_trial) when dev_cluster_trial.is_available in GET /v1/account/billing: one at a time, a plan with at most 2 cores and 4 GiB (starter-2c-4g), no public_ipv4, deleted with its server at trial_expires_at (24 hours) unless the account saves a card first, which keeps it as an ordinary cluster billed from the next full hour. A trial request outside those terms answers 400; an account that may not start one answers 402 payment_method_required saying why.

Request bodyapplication/json · CreateDevCluster

Request body fields
FieldTypeDescription
zonerequiredstringA zone that offers dev clusters (list_dev_cluster_versions).
namerequiredstringDNS label, 2 to 40 characters, unique among the account's dev clusters.
planrequiredstringA server plan with at least minimum_memory_mebibytes of memory.
versionstringA minor from list_dev_cluster_versions; defaults to the default one.
public_ipv4booleanGive the server a public IPv4 too (paid add-on) and make the cluster dual-stack. Default false: IPv6 only.
network_idstringA private network of the zone the server also joins.
ssh_keysarray of stringSSH public keys for the server. Without these and ssh_key_ids nobody can log in to it.
ssh_key_idsarray of stringKeys from the account's library for the server.
labelsLabelsKeys of 1-63 letters, digits, ., _, / or -, starting and ending with a letter or digit; values of at most 255 printable characters. On a server, keys under kubernetes.ankra.cloud/ and playground.ankra.cloud/ are set by the platform only.
default_firewallbooleanStart the server behind a firewall that accepts inbound SSH (22), HTTP (80), HTTPS (443), the Kubernetes API (6443) and ping, and with network_id everything from that private network, and drops every other inbound packet; outbound traffic is not filtered. It is the server's own firewall, so change it later on the server. Default false: the server has no firewall, like every server.
bootstrap_chartsarray of DevClusterBootstrapChartUp to 4 Helm charts k3s installs at the server's first boot, for software that must run in the cluster without anything dialling its API (the Ankra platform's agent on an IPv6-only trial). Default none.
namerequiredstringThe Helm release name, unique among the cluster's bootstrap charts; not traefik or traefik-crd.
namespacerequiredstringThe namespace the chart is installed into; it is created.
repositoryrequiredstringAn oci:// or https:// location on an allowed registry host (registry.ankra.cloud), without credentials, port, query or fragment. For OCI the chart is pulled as <repository>/<chart>.
chartrequiredstringThe chart's name in the repository; never a path or file.
versionrequiredstringThe pinned chart version.
values_yamlstringThe chart's values as one YAML mapping, at most 8 KiB per chart and 16 KiB for all of them. May hold secrets (an agent token): sealed at rest, never answered, never logged or audited.

Responses

201The creating dev cluster.application/json · DevClusterEnvelope

201 response fields
FieldTypeDescription
dev_clusterrequiredDevCluster
idrequiredstring
zonerequiredstring
regionrequiredstring
namerequiredstring
versionrequiredstringThe Kubernetes minor.
k3s_versionrequiredstringThe k3s release installed when the cluster was created.
planrequiredstringThe server's plan.
staterequiredstringcreating 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_ipv4requiredbooleanWhether the server holds a public IPv4 (the add-on). A cluster created with it is dual-stack; one that got it later (public_ipv4_change.added_at) serves ingress on IPv4 through a forwarder.
network_idrequiredstring | nullThe private network the server also joins.
server_idrequiredstring | nullThe cluster's server, in the account's servers.
endpointrequiredstring | nullThe API server URL on IPv6, once the server has its address.
endpoint_ipv4requiredstring | nullThe API server URL on IPv4, with public_ipv4.
ipv6_addressrequiredstring | nullThe server's public IPv6 address: the API on 6443, ingress on 80 and 443.
ipv4_addressrequiredstring | nullThe server's public IPv4 address, with public_ipv4.
labelsrequiredLabelsKeys of 1-63 letters, digits, ., _, / or -, starting and ending with a letter or digit; values of at most 255 printable characters. On a server, keys under kubernetes.ankra.cloud/ and playground.ankra.cloud/ are set by the platform only.
healthrequiredDevClusterHealth
api_serverrequiredstringWhether the API answered /readyz when last observed; unknown before the first observation.One of healthy, unhealthy, unknown
node_readyrequiredbooleanWhether the node reported Ready.
observed_atrequiredstring (date-time) | null
detailrequiredstringWhat is wrong, empty when nothing is.
failure_reasonrequiredstring | nullWhy a cluster in error failed.
plan_changenull | DevClusterPlanChangeThe plan change under way (change_dev_cluster_plan), or the last one that did not take; null when there is neither.
desired_planrequiredstring | nullThe plan the server is moving to while a change is under way; the cluster's own plan while it returns to it after a change that did not take. Null once the change is over.
requested_atrequiredstring (date-time) | nullWhen the change, or the return to the old plan, began.
failurerequiredstring | nullWhy the last change did not take; the cluster then kept, or returned to, its plan.
public_ipv4_changenull | DevClusterPublicIPv4ChangeThe public IPv4 addition under way (add_dev_cluster_public_ipv4), the finished one of a cluster created without the add-on, or the last one that did not take; null when there is none.
requested_atrequiredstring (date-time) | nullWhen the addition under way began; null once it is over.
added_atrequiredstring (date-time) | nullWhen the add-on was added to the running cluster. Its pod and Service networks stayed IPv6 only, and its node carries the IPv4 forwarder for ports 80 and 443.
failurerequiredstring | nullWhy the last addition did not take (the cluster has no public IPv4), or, with added_at, what of it is still missing (the forwarder waits for the cluster's API).
production_recommendedrequiredbooleanAlways false: a dev cluster is one server.One of false
production_warningrequiredstringWhat running on one server means, to show wherever the cluster is shown.
is_trialbooleanCreated without a payment method: free, and deleted with its server at trial_expires_at unless the account saves a card first.
trial_expires_atstring (date-time) | nullWhen a live trial is deleted; null once it converted or for a paid cluster.
trial_converted_atstring (date-time) | nullWhen the account saved a card and the trial became an ordinary cluster, its server billed from the next full hour.
bootstrap_chartsarray of DevClusterBootstrapChartViewThe charts k3s installed at first boot (bootstrap_charts of the create), never with their values.
namerequiredstringThe Helm release and the HelmChart object in kube-system.
namespacerequiredstringThe namespace the chart is installed into.
repositoryrequiredstring
chartrequiredstring
versionrequiredstring
created_atrequiredstring (date-time)
updated_atrequiredstring (date-time)
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 402The account may not create this. reason is payment_method_required while it has no default payment method and its credit does not cover the create: the credit left must cover one month, at monthly list prices, of everything the account already runs plus what the create adds (add a payment method through POST /v1/account/billing/setup-session, or free what the account no longer needs); owner_approval_required while its owner has not approved paid usage and no credit is left; or account_suspended while an invoice is overdue past the grace period (pay it) or Ankra staff suspended the account (contact support). A prepaid account (linked to an Ankra platform organisation) is refused with payment_method_required while it has no card, and with credit_required once it has one but its credit does not cover the create: Cloud never charges its card, so only a top-up on the Ankra platform lifts it, and top_up_url names that page when Cloud knows it. GET /v1/account/billing reports the same standing. For payment_method_required and credit_required, detail names what the create costs, the credit left and the committed monthly spend only to a principal that may read billing (billing.read, and for an API token a scope that includes it); anyone else is told only that the credit does not cover it.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 409The resource's state does not allow this now.
  • 422The account would exceed a quota; detail names the limit and reason is quota_exceeded.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • 503No capacity or address is free in the zone right now (reason: capacity_unavailable, with availability wording in detail), or a host did not answer; try another plan or zone, or try again later.
  • defaultAny other error, usually 500.

Example

bash
curl -X POST 'https://cloud.ankra.app/v1/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
NameInTypeDescription
idrequiredpathstring

Responses

200The dev cluster.application/json · DevClusterEnvelope

200 response fields
FieldTypeDescription
dev_clusterrequiredDevCluster
idrequiredstring
zonerequiredstring
regionrequiredstring
namerequiredstring
versionrequiredstringThe Kubernetes minor.
k3s_versionrequiredstringThe k3s release installed when the cluster was created.
planrequiredstringThe server's plan.
staterequiredstringcreating 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_ipv4requiredbooleanWhether the server holds a public IPv4 (the add-on). A cluster created with it is dual-stack; one that got it later (public_ipv4_change.added_at) serves ingress on IPv4 through a forwarder.
network_idrequiredstring | nullThe private network the server also joins.
server_idrequiredstring | nullThe cluster's server, in the account's servers.
endpointrequiredstring | nullThe API server URL on IPv6, once the server has its address.
endpoint_ipv4requiredstring | nullThe API server URL on IPv4, with public_ipv4.
ipv6_addressrequiredstring | nullThe server's public IPv6 address: the API on 6443, ingress on 80 and 443.
ipv4_addressrequiredstring | nullThe server's public IPv4 address, with public_ipv4.
labelsrequiredLabelsKeys of 1-63 letters, digits, ., _, / or -, starting and ending with a letter or digit; values of at most 255 printable characters. On a server, keys under kubernetes.ankra.cloud/ and playground.ankra.cloud/ are set by the platform only.
healthrequiredDevClusterHealth
api_serverrequiredstringWhether the API answered /readyz when last observed; unknown before the first observation.One of healthy, unhealthy, unknown
node_readyrequiredbooleanWhether the node reported Ready.
observed_atrequiredstring (date-time) | null
detailrequiredstringWhat is wrong, empty when nothing is.
failure_reasonrequiredstring | nullWhy a cluster in error failed.
plan_changenull | DevClusterPlanChangeThe plan change under way (change_dev_cluster_plan), or the last one that did not take; null when there is neither.
desired_planrequiredstring | nullThe plan the server is moving to while a change is under way; the cluster's own plan while it returns to it after a change that did not take. Null once the change is over.
requested_atrequiredstring (date-time) | nullWhen the change, or the return to the old plan, began.
failurerequiredstring | nullWhy the last change did not take; the cluster then kept, or returned to, its plan.
public_ipv4_changenull | DevClusterPublicIPv4ChangeThe public IPv4 addition under way (add_dev_cluster_public_ipv4), the finished one of a cluster created without the add-on, or the last one that did not take; null when there is none.
requested_atrequiredstring (date-time) | nullWhen the addition under way began; null once it is over.
added_atrequiredstring (date-time) | nullWhen the add-on was added to the running cluster. Its pod and Service networks stayed IPv6 only, and its node carries the IPv4 forwarder for ports 80 and 443.
failurerequiredstring | nullWhy the last addition did not take (the cluster has no public IPv4), or, with added_at, what of it is still missing (the forwarder waits for the cluster's API).
production_recommendedrequiredbooleanAlways false: a dev cluster is one server.One of false
production_warningrequiredstringWhat running on one server means, to show wherever the cluster is shown.
is_trialbooleanCreated without a payment method: free, and deleted with its server at trial_expires_at unless the account saves a card first.
trial_expires_atstring (date-time) | nullWhen a live trial is deleted; null once it converted or for a paid cluster.
trial_converted_atstring (date-time) | nullWhen the account saved a card and the trial became an ordinary cluster, its server billed from the next full hour.
bootstrap_chartsarray of DevClusterBootstrapChartViewThe charts k3s installed at first boot (bootstrap_charts of the create), never with their values.
namerequiredstringThe Helm release and the HelmChart object in kube-system.
namespacerequiredstringThe namespace the chart is installed into.
repositoryrequiredstring
chartrequiredstring
versionrequiredstring
created_atrequiredstring (date-time)
updated_atrequiredstring (date-time)
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/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
NameInTypeDescription
idrequiredpathstring

Responses

200The deleting dev cluster.application/json · DevClusterEnvelope

200 response fields
FieldTypeDescription
dev_clusterrequiredDevCluster
idrequiredstring
zonerequiredstring
regionrequiredstring
namerequiredstring
versionrequiredstringThe Kubernetes minor.
k3s_versionrequiredstringThe k3s release installed when the cluster was created.
planrequiredstringThe server's plan.
staterequiredstringcreating 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_ipv4requiredbooleanWhether the server holds a public IPv4 (the add-on). A cluster created with it is dual-stack; one that got it later (public_ipv4_change.added_at) serves ingress on IPv4 through a forwarder.
network_idrequiredstring | nullThe private network the server also joins.
server_idrequiredstring | nullThe cluster's server, in the account's servers.
endpointrequiredstring | nullThe API server URL on IPv6, once the server has its address.
endpoint_ipv4requiredstring | nullThe API server URL on IPv4, with public_ipv4.
ipv6_addressrequiredstring | nullThe server's public IPv6 address: the API on 6443, ingress on 80 and 443.
ipv4_addressrequiredstring | nullThe server's public IPv4 address, with public_ipv4.
labelsrequiredLabelsKeys of 1-63 letters, digits, ., _, / or -, starting and ending with a letter or digit; values of at most 255 printable characters. On a server, keys under kubernetes.ankra.cloud/ and playground.ankra.cloud/ are set by the platform only.
healthrequiredDevClusterHealth
api_serverrequiredstringWhether the API answered /readyz when last observed; unknown before the first observation.One of healthy, unhealthy, unknown
node_readyrequiredbooleanWhether the node reported Ready.
observed_atrequiredstring (date-time) | null
detailrequiredstringWhat is wrong, empty when nothing is.
failure_reasonrequiredstring | nullWhy a cluster in error failed.
plan_changenull | DevClusterPlanChangeThe plan change under way (change_dev_cluster_plan), or the last one that did not take; null when there is neither.
desired_planrequiredstring | nullThe plan the server is moving to while a change is under way; the cluster's own plan while it returns to it after a change that did not take. Null once the change is over.
requested_atrequiredstring (date-time) | nullWhen the change, or the return to the old plan, began.
failurerequiredstring | nullWhy the last change did not take; the cluster then kept, or returned to, its plan.
public_ipv4_changenull | DevClusterPublicIPv4ChangeThe public IPv4 addition under way (add_dev_cluster_public_ipv4), the finished one of a cluster created without the add-on, or the last one that did not take; null when there is none.
requested_atrequiredstring (date-time) | nullWhen the addition under way began; null once it is over.
added_atrequiredstring (date-time) | nullWhen the add-on was added to the running cluster. Its pod and Service networks stayed IPv6 only, and its node carries the IPv4 forwarder for ports 80 and 443.
failurerequiredstring | nullWhy the last addition did not take (the cluster has no public IPv4), or, with added_at, what of it is still missing (the forwarder waits for the cluster's API).
production_recommendedrequiredbooleanAlways false: a dev cluster is one server.One of false
production_warningrequiredstringWhat running on one server means, to show wherever the cluster is shown.
is_trialbooleanCreated without a payment method: free, and deleted with its server at trial_expires_at unless the account saves a card first.
trial_expires_atstring (date-time) | nullWhen a live trial is deleted; null once it converted or for a paid cluster.
trial_converted_atstring (date-time) | nullWhen the account saved a card and the trial became an ordinary cluster, its server billed from the next full hour.
bootstrap_chartsarray of DevClusterBootstrapChartViewThe charts k3s installed at first boot (bootstrap_charts of the create), never with their values.
namerequiredstringThe Helm release and the HelmChart object in kube-system.
namespacerequiredstringThe namespace the chart is installed into.
repositoryrequiredstring
chartrequiredstring
versionrequiredstring
created_atrequiredstring (date-time)
updated_atrequiredstring (date-time)
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • 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
NameInTypeDescription
idrequiredpathstring

Responses

200The kubeconfig.application/json

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

Example

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

Move a running dev cluster's server to another plan#

POST/v1/dev-clusters/{id}/plan
Operation
change_dev_cluster_plan
Credentials
API token, Portal session
Requires
Permission operate

The plan needs at least the memory a dev cluster runs on (minimum_memory_mebibytes of list_dev_cluster_versions). The cluster stays running with plan_change set while the control plane stops its server, changes the server's plan (server.change_plan) and starts it again, so the API and every workload are down for a few minutes; plan turns to the new plan once the server is back. A change the server cannot take (quota, capacity, a failed operation, or one not done within 30 minutes) returns the server to the old plan and says why in plan_change.failure. 409 unless the cluster is running with no change under way; 400 for a live trial, which keeps its plan. Recorded in the account's audit log (dev_cluster.change_plan).

Parameters

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

Request bodyapplication/json

Request body fields
FieldTypeDescription
planrequiredstring

Responses

202The dev cluster with its plan change under way.application/json · DevClusterEnvelope

202 response fields
FieldTypeDescription
dev_clusterrequiredDevCluster
idrequiredstring
zonerequiredstring
regionrequiredstring
namerequiredstring
versionrequiredstringThe Kubernetes minor.
k3s_versionrequiredstringThe k3s release installed when the cluster was created.
planrequiredstringThe server's plan.
staterequiredstringcreating 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_ipv4requiredbooleanWhether the server holds a public IPv4 (the add-on). A cluster created with it is dual-stack; one that got it later (public_ipv4_change.added_at) serves ingress on IPv4 through a forwarder.
network_idrequiredstring | nullThe private network the server also joins.
server_idrequiredstring | nullThe cluster's server, in the account's servers.
endpointrequiredstring | nullThe API server URL on IPv6, once the server has its address.
endpoint_ipv4requiredstring | nullThe API server URL on IPv4, with public_ipv4.
ipv6_addressrequiredstring | nullThe server's public IPv6 address: the API on 6443, ingress on 80 and 443.
ipv4_addressrequiredstring | nullThe server's public IPv4 address, with public_ipv4.
labelsrequiredLabelsKeys of 1-63 letters, digits, ., _, / or -, starting and ending with a letter or digit; values of at most 255 printable characters. On a server, keys under kubernetes.ankra.cloud/ and playground.ankra.cloud/ are set by the platform only.
healthrequiredDevClusterHealth
api_serverrequiredstringWhether the API answered /readyz when last observed; unknown before the first observation.One of healthy, unhealthy, unknown
node_readyrequiredbooleanWhether the node reported Ready.
observed_atrequiredstring (date-time) | null
detailrequiredstringWhat is wrong, empty when nothing is.
failure_reasonrequiredstring | nullWhy a cluster in error failed.
plan_changenull | DevClusterPlanChangeThe plan change under way (change_dev_cluster_plan), or the last one that did not take; null when there is neither.
desired_planrequiredstring | nullThe plan the server is moving to while a change is under way; the cluster's own plan while it returns to it after a change that did not take. Null once the change is over.
requested_atrequiredstring (date-time) | nullWhen the change, or the return to the old plan, began.
failurerequiredstring | nullWhy the last change did not take; the cluster then kept, or returned to, its plan.
public_ipv4_changenull | DevClusterPublicIPv4ChangeThe public IPv4 addition under way (add_dev_cluster_public_ipv4), the finished one of a cluster created without the add-on, or the last one that did not take; null when there is none.
requested_atrequiredstring (date-time) | nullWhen the addition under way began; null once it is over.
added_atrequiredstring (date-time) | nullWhen the add-on was added to the running cluster. Its pod and Service networks stayed IPv6 only, and its node carries the IPv4 forwarder for ports 80 and 443.
failurerequiredstring | nullWhy the last addition did not take (the cluster has no public IPv4), or, with added_at, what of it is still missing (the forwarder waits for the cluster's API).
production_recommendedrequiredbooleanAlways false: a dev cluster is one server.One of false
production_warningrequiredstringWhat running on one server means, to show wherever the cluster is shown.
is_trialbooleanCreated without a payment method: free, and deleted with its server at trial_expires_at unless the account saves a card first.
trial_expires_atstring (date-time) | nullWhen a live trial is deleted; null once it converted or for a paid cluster.
trial_converted_atstring (date-time) | nullWhen the account saved a card and the trial became an ordinary cluster, its server billed from the next full hour.
bootstrap_chartsarray of DevClusterBootstrapChartViewThe charts k3s installed at first boot (bootstrap_charts of the create), never with their values.
namerequiredstringThe Helm release and the HelmChart object in kube-system.
namespacerequiredstringThe namespace the chart is installed into.
repositoryrequiredstring
chartrequiredstring
versionrequiredstring
created_atrequiredstring (date-time)
updated_atrequiredstring (date-time)
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 402The account may not create this. reason is payment_method_required while it has no default payment method and its credit does not cover the create: the credit left must cover one month, at monthly list prices, of everything the account already runs plus what the create adds (add a payment method through POST /v1/account/billing/setup-session, or free what the account no longer needs); owner_approval_required while its owner has not approved paid usage and no credit is left; or account_suspended while an invoice is overdue past the grace period (pay it) or Ankra staff suspended the account (contact support). A prepaid account (linked to an Ankra platform organisation) is refused with payment_method_required while it has no card, and with credit_required once it has one but its credit does not cover the create: Cloud never charges its card, so only a top-up on the Ankra platform lifts it, and top_up_url names that page when Cloud knows it. GET /v1/account/billing reports the same standing. For payment_method_required and credit_required, detail names what the create costs, the credit left and the committed monthly spend only to a principal that may read billing (billing.read, and for an API token a scope that includes it); anyone else is told only that the credit does not cover it.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 422The account would exceed a quota; detail names the limit and reason is quota_exceeded.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X POST 'https://cloud.ankra.app/v1/dev-clusters/<id>/plan' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "plan": "general-4c-8g"
}'

Give a running dev cluster created without it the public IPv4 add-on#

POST/v1/dev-clusters/{id}/public-ipv4
Operation
add_dev_cluster_public_ipv4
Credentials
API token, Portal session
Requires
Permission operate

For a cluster created IPv6 only, such as a trial that converted when the account saved a card. The server gets an address of its zone's public IPv4 pool (operation server.add_public_ipv4, billed per hour from the hour the address is taken, like the add-on at create), which stops and starts the server: the API and every workload are down for a minute or two. The cluster stays running with public_ipv4_change.requested_at set until the server is back with the address; the control plane then puts an IPv4 forwarder on the node (a DaemonSet kube-system/ankra-ipv4-ingress that passes ports 80 and 443 of the IPv4 address to the same ports of the node's IPv6 address, where the bundled ingress listens, so websites and Let's Encrypt HTTP-01 answer on IPv4) and sets public_ipv4, ipv4_address, endpoint_ipv4 and public_ipv4_change.added_at. The pod and Service networks stay IPv6 only: k3s cannot turn a running cluster dual-stack. An addition the server cannot take (no free address in the zone, a failed operation, or one without the address after 30 minutes) ends without the add-on and says why in public_ipv4_change.failure; ask again to retry. 202 with the cluster while the addition is under way (also when one already was); 200 with the cluster and its address when it has the add-on already, without asking the spending gate. 402 when the account may not spend what the add-on costs a month (a prepaid account whose credit does not cover it, ADR 0018); 409 unless the cluster is running with no plan change under way, for a live trial (whose terms rule IPv4 out; it converts once the account saves a card) and when the zone has no free address. Recorded in the account's audit log (dev_cluster.add_public_ipv4) when an addition starts.

Parameters

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

Responses

200The dev cluster, which has the public IPv4 add-on already.application/json · DevClusterEnvelope

200 response fields
FieldTypeDescription
dev_clusterrequiredDevCluster
idrequiredstring
zonerequiredstring
regionrequiredstring
namerequiredstring
versionrequiredstringThe Kubernetes minor.
k3s_versionrequiredstringThe k3s release installed when the cluster was created.
planrequiredstringThe server's plan.
staterequiredstringcreating 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_ipv4requiredbooleanWhether the server holds a public IPv4 (the add-on). A cluster created with it is dual-stack; one that got it later (public_ipv4_change.added_at) serves ingress on IPv4 through a forwarder.
network_idrequiredstring | nullThe private network the server also joins.
server_idrequiredstring | nullThe cluster's server, in the account's servers.
endpointrequiredstring | nullThe API server URL on IPv6, once the server has its address.
endpoint_ipv4requiredstring | nullThe API server URL on IPv4, with public_ipv4.
ipv6_addressrequiredstring | nullThe server's public IPv6 address: the API on 6443, ingress on 80 and 443.
ipv4_addressrequiredstring | nullThe server's public IPv4 address, with public_ipv4.
labelsrequiredLabelsKeys of 1-63 letters, digits, ., _, / or -, starting and ending with a letter or digit; values of at most 255 printable characters. On a server, keys under kubernetes.ankra.cloud/ and playground.ankra.cloud/ are set by the platform only.
healthrequiredDevClusterHealth
api_serverrequiredstringWhether the API answered /readyz when last observed; unknown before the first observation.One of healthy, unhealthy, unknown
node_readyrequiredbooleanWhether the node reported Ready.
observed_atrequiredstring (date-time) | null
detailrequiredstringWhat is wrong, empty when nothing is.
failure_reasonrequiredstring | nullWhy a cluster in error failed.
plan_changenull | DevClusterPlanChangeThe plan change under way (change_dev_cluster_plan), or the last one that did not take; null when there is neither.
desired_planrequiredstring | nullThe plan the server is moving to while a change is under way; the cluster's own plan while it returns to it after a change that did not take. Null once the change is over.
requested_atrequiredstring (date-time) | nullWhen the change, or the return to the old plan, began.
failurerequiredstring | nullWhy the last change did not take; the cluster then kept, or returned to, its plan.
public_ipv4_changenull | DevClusterPublicIPv4ChangeThe public IPv4 addition under way (add_dev_cluster_public_ipv4), the finished one of a cluster created without the add-on, or the last one that did not take; null when there is none.
requested_atrequiredstring (date-time) | nullWhen the addition under way began; null once it is over.
added_atrequiredstring (date-time) | nullWhen the add-on was added to the running cluster. Its pod and Service networks stayed IPv6 only, and its node carries the IPv4 forwarder for ports 80 and 443.
failurerequiredstring | nullWhy the last addition did not take (the cluster has no public IPv4), or, with added_at, what of it is still missing (the forwarder waits for the cluster's API).
production_recommendedrequiredbooleanAlways false: a dev cluster is one server.One of false
production_warningrequiredstringWhat running on one server means, to show wherever the cluster is shown.
is_trialbooleanCreated without a payment method: free, and deleted with its server at trial_expires_at unless the account saves a card first.
trial_expires_atstring (date-time) | nullWhen a live trial is deleted; null once it converted or for a paid cluster.
trial_converted_atstring (date-time) | nullWhen the account saved a card and the trial became an ordinary cluster, its server billed from the next full hour.
bootstrap_chartsarray of DevClusterBootstrapChartViewThe charts k3s installed at first boot (bootstrap_charts of the create), never with their values.
namerequiredstringThe Helm release and the HelmChart object in kube-system.
namespacerequiredstringThe namespace the chart is installed into.
repositoryrequiredstring
chartrequiredstring
versionrequiredstring
created_atrequiredstring (date-time)
updated_atrequiredstring (date-time)

202The dev cluster with its public IPv4 addition under way.application/json · DevClusterEnvelope

202 response fields
FieldTypeDescription
dev_clusterrequiredDevCluster
idrequiredstring
zonerequiredstring
regionrequiredstring
namerequiredstring
versionrequiredstringThe Kubernetes minor.
k3s_versionrequiredstringThe k3s release installed when the cluster was created.
planrequiredstringThe server's plan.
staterequiredstringcreating 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_ipv4requiredbooleanWhether the server holds a public IPv4 (the add-on). A cluster created with it is dual-stack; one that got it later (public_ipv4_change.added_at) serves ingress on IPv4 through a forwarder.
network_idrequiredstring | nullThe private network the server also joins.
server_idrequiredstring | nullThe cluster's server, in the account's servers.
endpointrequiredstring | nullThe API server URL on IPv6, once the server has its address.
endpoint_ipv4requiredstring | nullThe API server URL on IPv4, with public_ipv4.
ipv6_addressrequiredstring | nullThe server's public IPv6 address: the API on 6443, ingress on 80 and 443.
ipv4_addressrequiredstring | nullThe server's public IPv4 address, with public_ipv4.
labelsrequiredLabelsKeys of 1-63 letters, digits, ., _, / or -, starting and ending with a letter or digit; values of at most 255 printable characters. On a server, keys under kubernetes.ankra.cloud/ and playground.ankra.cloud/ are set by the platform only.
healthrequiredDevClusterHealth
api_serverrequiredstringWhether the API answered /readyz when last observed; unknown before the first observation.One of healthy, unhealthy, unknown
node_readyrequiredbooleanWhether the node reported Ready.
observed_atrequiredstring (date-time) | null
detailrequiredstringWhat is wrong, empty when nothing is.
failure_reasonrequiredstring | nullWhy a cluster in error failed.
plan_changenull | DevClusterPlanChangeThe plan change under way (change_dev_cluster_plan), or the last one that did not take; null when there is neither.
desired_planrequiredstring | nullThe plan the server is moving to while a change is under way; the cluster's own plan while it returns to it after a change that did not take. Null once the change is over.
requested_atrequiredstring (date-time) | nullWhen the change, or the return to the old plan, began.
failurerequiredstring | nullWhy the last change did not take; the cluster then kept, or returned to, its plan.
public_ipv4_changenull | DevClusterPublicIPv4ChangeThe public IPv4 addition under way (add_dev_cluster_public_ipv4), the finished one of a cluster created without the add-on, or the last one that did not take; null when there is none.
requested_atrequiredstring (date-time) | nullWhen the addition under way began; null once it is over.
added_atrequiredstring (date-time) | nullWhen the add-on was added to the running cluster. Its pod and Service networks stayed IPv6 only, and its node carries the IPv4 forwarder for ports 80 and 443.
failurerequiredstring | nullWhy the last addition did not take (the cluster has no public IPv4), or, with added_at, what of it is still missing (the forwarder waits for the cluster's API).
production_recommendedrequiredbooleanAlways false: a dev cluster is one server.One of false
production_warningrequiredstringWhat running on one server means, to show wherever the cluster is shown.
is_trialbooleanCreated without a payment method: free, and deleted with its server at trial_expires_at unless the account saves a card first.
trial_expires_atstring (date-time) | nullWhen a live trial is deleted; null once it converted or for a paid cluster.
trial_converted_atstring (date-time) | nullWhen the account saved a card and the trial became an ordinary cluster, its server billed from the next full hour.
bootstrap_chartsarray of DevClusterBootstrapChartViewThe charts k3s installed at first boot (bootstrap_charts of the create), never with their values.
namerequiredstringThe Helm release and the HelmChart object in kube-system.
namespacerequiredstringThe namespace the chart is installed into.
repositoryrequiredstring
chartrequiredstring
versionrequiredstring
created_atrequiredstring (date-time)
updated_atrequiredstring (date-time)
  • 401Not signed in, or the credential is invalid or expired.
  • 402The account may not create this. reason is payment_method_required while it has no default payment method and its credit does not cover the create: the credit left must cover one month, at monthly list prices, of everything the account already runs plus what the create adds (add a payment method through POST /v1/account/billing/setup-session, or free what the account no longer needs); owner_approval_required while its owner has not approved paid usage and no credit is left; or account_suspended while an invoice is overdue past the grace period (pay it) or Ankra staff suspended the account (contact support). A prepaid account (linked to an Ankra platform organisation) is refused with payment_method_required while it has no card, and with credit_required once it has one but its credit does not cover the create: Cloud never charges its card, so only a top-up on the Ankra platform lifts it, and top_up_url names that page when Cloud knows it. GET /v1/account/billing reports the same standing. For payment_method_required and credit_required, detail names what the create costs, the credit left and the committed monthly spend only to a principal that may read billing (billing.read, and for an API token a scope that includes it); anyone else is told only that the credit does not cover it.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 422The Idempotency-Key was already used with a different request (reason: idempotency_key_reused).
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X POST 'https://cloud.ankra.app/v1/dev-clusters/<id>/public-ipv4' \
  -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
NameInTypeDescription
idrequiredpathstring

Responses

200The ExecCredential.application/json · KubernetesExecCredential

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

Example

bash
curl 'https://cloud.ankra.app/v1/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
FieldTypeDescription
itemsrequiredarray of object
versionrequiredstring
k3s_versionrequiredstring
is_defaultrequiredboolean
is_availablerequiredbooleanWhether any zone offers dev clusters.
all_zonesrequiredbooleanEvery zone offers dev clusters; zones is then empty.
zonesrequiredarray of stringThe zones that offer dev clusters, unless all_zones.
minimum_memory_mebibytesrequiredintegerThe smallest plan a dev cluster runs on.
ipv4_price_monthly_centsrequiredintegerWhat public_ipv4 adds a month.
production_warningrequiredstring
trialrequiredDevClusterTrialTerms
lifetime_hoursrequiredintegerHow long a trial runs before it is deleted with its server.
maximum_coresrequiredintegerThe largest plan's cores a trial may use.
maximum_memory_mebibytesrequiredintegerThe largest plan's memory a trial may use.
trials_per_windowrequiredintegerHow many trials an account may start in window_days.
window_daysrequiredinteger
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

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