AnkraDocs
Console

API reference · Locations and tools

Zones and their capabilities

2 operations of the Ankra Cloud API: Node registration (ankra-node) and the operator's view of zones, nodes and gateways.

List zones#

GET/v1/zones
Operation
list_zones
Credentials
Operator token, API token, Portal session
Requires
Permission read

Zones in listing order (position, then name). A customer sees the zones that are not hidden from customers (customer_visible), and hidden ones only when the account may use them; the operator token sees every zone. Accepts the operator token as well as a customer credential.

Responses

200Every zone; a small fixed catalogue, so the list is never paged and next_cursor is always null.application/json · ZoneList

200 response fields
FieldTypeDescription
itemsrequiredarray of Zone
namerequiredstring
regionrequiredstring
display_namerequiredstring
created_atrequiredstring (date-time)
underlaystringHow the zone's hosts reach each other (ADR 0004): fabric is a private network, wireguard the encrypted underlay.One of fabric, wireguard
countrystringThe zone's region's ISO 3166-1 alpha-2 country code.
positionintegerWhere the zone is listed, lowest first (then by name); regions follow the position of their first zone.
customer_visiblebooleanFalse for a zone hidden from customers: a customer only sees it, and places new resources in it, when the account may use hidden zones or has private hosts there. Operators always see every zone.
is_private_cloudbooleanTrue, in a customer's listing, on a zone in which Ankra dedicated compute hosts to the caller's account (its private cloud): the account's servers there run only on its own hosts. Hidden zone access alone never sets it; always false for operators.
sold_out_plan_familiesarray of stringThe plan tiers (a plan's family) out of stock in the zone: a new server, or a plan change into the tier, is refused there. Servers already on the tier keep it and resize within it. Empty when every tier is on sale.One of starter, cloud_native, premium
sells_dedicated_cpubooleanTrue on a zone that sells the Dedicated CPU tier (premium plans) as dedicated: a new server on it there has its vCPUs pinned one to one to host CPUs no other server uses. Elsewhere the tier's servers share host CPUs, and a server keeps the CPUs it was created with.
public_ipv4_availablebooleanWhether the zone can hand out a public IPv4 address now, the priced add-on (public_ipv4 on a server or a load balancer). Absent when that could not be read, which is not a no. Availability can change at any time: the create decides.
next_cursorrequiredstring | nullPass as ?cursor= for the next page; null on the last page.
  • 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/zones' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

What the zone offers at its growth stage#

GET/v1/zones/{zone}/capabilities
Operation
get_zone_capabilities
Credentials
Operator token, API token, Portal session
Requires
Permission read

A customer reads availability: stage, servers, gateways, compute_nodes, account.compute_nodes, a CPU pool's nodes and flag_count read 0, datacenters, latency_budget and warnings are empty, storage_copies is empty, reasons are generic or null, and only an operator reads the rest of this description's figures.

Computed from the zone's registered nodes (ADR 0002); nothing is configured by hand. A zone is born on one server carrying every role (stage 1) and grows one server at a time: servers counts the nodes with a gateway, storage or compute role, and stage is 1, 2, or 3 from three servers on. storage_backends are the zone's active storage backends as its storage backend records say (see list_storage_backends): ankra-local while the zone has a storage node, ceph (Ankra Storage) once storage.rebalance_policy has made it active, ankra-s3-single while the single-node S3 server serves the zone. load_balancer_ha needs two compute nodes; live_migration and ha_restart also need active Ankra Storage (the ceph backend); separate_edges starts at three servers. compute needs one compute node: a zone without one is a network-only location (it routes IPv6 and IPv4 for the cloud) and refuses servers with 409. reasons says why each missing feature is missing. What a zone lacks is refused (409, naming the feature) or degraded honestly: a single-VM load balancer with high_availability: false, an HA policy reported ha_status: unavailable. A server whose storages are on local-nvme is refused a live migration or an HA restart on its own (409, "local-nvme volumes live on one node") even where the zone offers them. underlay, datacenters and latency_budget say how the zone's hosts are connected (ADR 0004): with hosts in several datacenters, each pair of datacenters is rated against the measured latency budget for Ankra Storage replication and live migration. local_storage says whether new local-nvme volumes can be made: every storage host keeps them in a thin pool, and a pool that is 80 % full (data or metadata) or would be provisioned more than 1.5 times its size takes no new volume (the operator can set other limits); creates that need one are then refused with 409 or 503 naming the pool's state. Accepts the operator token as well as a customer credential. A customer is answered for its account: compute_nodes and features.compute count only the compute nodes that may take the account's servers (public, or the account's private hosts once it has any, not in maintenance), and account adds them with the account's remaining quota, so a preflight sees a zone whose hosts are private to someone else, and a cluster that does not fit the quota, before it creates anything.

Parameters

Parameters
NameInTypeDescription
zonerequiredpathstring

Responses

200The zone's stage, servers, gateways, storage backends and features.application/json · ZoneCapabilities

200 response fields
FieldTypeDescription
stagerequiredinteger1 for one server, 2 for two, 3 from three on; 0 before any server registered.
serversrequiredintegerNodes with a gateway, storage or compute role.
gatewaysrequiredinteger
compute_nodesintegerThe hypervisor hosts servers are placed on; 0 in a network-only location.
storage_backendsrequiredarray of stringankra-local is Local NVMe on the storage nodes, ceph is Ankra Storage, ankra-s3-single the single-node S3 server.One of ankra-local, ceph, ankra-s3-single
featuresrequiredobject
computerequiredbooleanFalse in a network-only location: the zone has no compute node and runs no servers.
live_migrationrequiredboolean
ha_restartrequiredboolean
load_balancer_harequiredboolean
separate_edgesrequiredboolean
reasonsmap of stringWhy the zone lacks each feature that is false, keyed by the feature's name.
underlayrequiredstringHow the zone's hosts reach each other (ADR 0004): fabric is a private network, wireguard the encrypted underlay.One of fabric, wireguard
datacentersrequiredarray of DatacenterWhere the zone's nodes stand.
namerequiredstring | nullnull groups the nodes without a recorded datacenter.
nodesrequiredinteger
storage_nodesrequiredinteger
compute_nodesrequiredinteger
latency_budgetrequiredarray of DatacenterLinkEvery pair of the zone's datacenters (a datacenter with itself included) rated against the budget measured over the underlay: Ankra Storage replicates across hosts only under 2 ms p95 RTT, live migration needs under 5 ms and at least 1 Gbit/s.
fromrequiredstring | null
torequiredstring | null
host_pairsrequiredinteger
measured_pairsrequiredinteger
worst_p95_rtt_msrequirednumber | null
lowest_bandwidth_bits_per_secondrequiredinteger | null
ceph_replicationrequiredstringAnkra Storage replication's budget: p95 RTT under 2 ms.One of within, over, unmeasured
live_migrationrequiredstringBudget p95 RTT under 5 ms and at least 1 Gbit/s.One of within, over, unmeasured
storage_durabilitystringreplicated is Ankra Storage on three or more hosts; degraded is Ankra Storage on two hosts (a zone that set ceph_min_hosts to 2): two copies, and writes continue on one while a host is down; single_copy is Ankra Local only.One of replicated, degraded, single_copy
storage_durability_reasonstring | nullWhy the durability is not replicated.
storage_copiesstringHow many copies of a volume on the zone's replicated tiers its storage keeps and where, as its policy last converged: "3 copies, one per host" from three storage hosts, "2 copies, one per host" in a two-host zone, "1 copy" while the zone has no active replicated storage (every volume is Ankra Local on one host).
default_storage_tierrequiredstringThe tier a new server's disk or a new storage gets in the zone when the request names none: standard once the zone offers the Ankra Storage tiers, local-nvme before.
ceph_tiers_offeredrequiredbooleanWhether new storages and server disks may use the Ankra Storage tiers (backend: ceph) in the zone. The Ankra Local tiers (backend: ankra-local in GET /v1/storage-tiers) are offered either way.
ceph_tiers_unavailable_reasonrequiredstring | nullWhy the Ankra Storage tiers are not offered: Ankra Storage is not active yet, or replicates below size 3 / min_size 2 on three hosts without the operator override.
networkingobjectHow the zone's servers reach the internet, for a client that lays out a network before it creates anything (a self-managed Kubernetes cluster behind a NAT router needs nat_routers; one without IPv4 needs ipv6 and nat64).
ipv6requiredbooleanA server gets a public IPv6 delegation of its own (an active IPv6 pool).
public_ipv4requiredbooleanA server can take the IPv4 add-on now. False while public IPv4 is unavailable in the zone.
public_ipv4_survives_gateway_lossrequiredbooleanWhether the address the next IPv4 add-on takes stays reachable when one of the zone's gateways is lost. True when it comes from a routed pool, which every gateway serves. False when it comes from a host-attached pool (the provider delivers those addresses to one gateway's host, so the server's IPv4 is unreachable while that host is down; its IPv6 is not affected) and while public IPv4 is unavailable.
nat_routersrequiredbooleanA router can take a NAT address now: one of the zone's routed IPv4 pools has a free address.
nat64requiredbooleanThe zone's gateways translate IPv6-only servers' traffic to IPv4: names through DNS64, IPv4 sockets through the guest's CLAT (464XLAT).
port_forwardrequiredbooleanA server of the zone with a public IPv6 address can be reached through open_server_port_forward: the zone has a gateway and an IPv6 pool.
port_forward_sourcesrequiredarray of stringWhere a port forward's connections to a server come from (the zone's IPv6 pool gateway addresses, each gateway's own address beside them, and the addresses Ankra Cloud records for the zone, such as a gateway's router uplink address); admit SSH from them in the server's firewall. The list can grow, so read it when you build a firewall.
cpu_poolsarray of objectThe compute nodes grouped by exact CPU; servers are placed in one and migrate within it.
namerequiredstring
vendorrequiredstring
familyrequiredinteger
modelrequiredstring
flag_countrequiredinteger
x86_64_levelrequiredintegerThe x86-64 microarchitecture level (psABI v1-v4) every CPU of the pool meets, 0 when the CPU is not x86-64. Level 3 or more has AVX2, which current builds of many Python, Rust and Go packages require; an image built for it fails with an illegal instruction on a lower level.
nodesrequiredinteger
backup_targetsarray of stringceph is the zone's Ankra Storage, vault the region's off-host backup vault, zone-object-store the zone's single-node S3 server.One of ceph, vault, zone-object-store
local_storageobjectWhether the zone's Ankra Local (local-nvme) storage takes new volumes now.
accepts_new_volumesrequiredbooleanFalse when every Ankra Local thin pool of the zone is too full or too overcommitted for a new volume.
reasonrequiredstring | nullWhy some or all of the zone's pools take no new volumes; null when every pool does.
warningsarray of stringWhat limits the zone's durability, such as a backup target on the same host as the volumes, or local storage pools that take no new volumes.
recoverystringWhat brings a server back after its host is lost. restart: the control plane restarts it on another host from the zone's replicated storage. restore: nothing restarts it, but its volumes' backups are in the region's backup vault outside the zone: a server whose ha_policy is restore is brought back on another host from them, losing what was written after them, and any volume can be restored by hand as a new storage. none: it returns only with its host.One of none, restore, restart
recovery_reasonstring | nullWhy recovery is not a restart.
gateway_redundancystringsingle: the zone has one gateway, and its public networking stops while that host is down.One of none, single, redundant
gateway_redundancy_reasonstring | null
uplink_redundancystringredundant: at least two gateways each reach the internet through a different edge router. single: one gateway or one edge router carries every uplink, or (a provider_native zone) each gateway's public addresses are routed to that host and do not move. unknown: no gateway uplink is recorded for the zone.One of none, single, redundant, unknown
uplink_redundancy_reasonstring | null
object_storage_durabilitystringHow many copies of an object survive a host loss: single_copy on the zone's single-node S3 server, Ankra Storage's durability once the zone serves objects from its replicated object storage, none while the zone has no object storage.One of none, single_copy, degraded, replicated
offsite_backupsbooleanWhether backups of the zone's volumes go to a backup vault outside the zone. False while the region has no vault, while its vault is served from the zone itself, and while the zone backs up into its own Ankra Storage cluster.
offsite_backups_reasonstring | nullWhy backups do not leave the zone.
default_backupobject | nullThe backup rule a new server disk or storage gets in the zone when its request names none: a zone that keeps one copy of every volume backs each new one up to its region's backup vault unless the request sets acknowledge_single_copy_without_backup. Null when the zone applies no default (replicated storage, or no backup vault yet).
intervalrequiredstringOne of daily
retention_daysrequiredinteger
database_backupsbooleanWhether managed databases in the zone keep point-in-time backups: the zone has https object storage for them. Where it does not, POST /v1/databases needs acknowledge_no_backups.
database_backups_reasonstring | nullWhy managed databases in the zone keep no backups.
accountobject | nullWhat the zone offers the calling customer's account; null for the operator token. compute_nodes are the zone's compute nodes that may take the account's next server: public hosts, or only the account's private hosts once it has any there, none of them in maintenance (cordoned, draining or fenced). The top-level compute_nodes and features.compute count only those too, so a zone whose hosts are all private to another account offers this one no compute, with the reason in reasons.compute. quota_remaining is what the account may still allocate under its quota, account-wide (limit less what it holds, never below zero): a client creating several servers at once checks their total against it before it creates anything.
compute_nodesrequiredinteger
quota_remainingrequiredobject
serversrequiredinteger
coresrequiredinteger
memory_mebibytesrequiredinteger
storage_gibibytesrequiredinteger
floating_ipsrequiredinteger
routersrequiredinteger
private_networksrequiredinteger
public_ipv4_addressesrequiredinteger
  • 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/zones/<zone>/capabilities' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"