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 (next_cursor is always null).application/json · ZoneList

200 response fields
Field	Type	Description
`items`required	array of Zone
`name`required	string
`region`required	string
`display_name`required	string
`created_at`required	string (date-time)
`underlay`	string	How the zone's hosts reach each other (ADR 0004): `fabric` is a private network, `wireguard` the encrypted underlay.One of `fabric`, `wireguard`
`country`	string	The zone's region's ISO 3166-1 alpha-2 country code.
`position`	integer	Where the zone is listed, lowest first (then by name); regions follow the position of their first zone.
`customer_visible`	boolean	False 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_cloud`	boolean	True, 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.
`next_cursor`required	string \| null	Pass 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).
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

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, as Stockholm does) 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.

Parameters

Parameters
Name	In	Type	Description
`zone`required	path	string

Responses

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

200 response fields
Field	Type	Description
`stage`required	integer	1 for one server, 2 for two, 3 from three on; 0 before any server registered.
`servers`required	integer	Nodes with a gateway, storage or compute role.
`gateways`required	integer
`compute_nodes`	integer	The hypervisor hosts servers are placed on; 0 in a network-only location.
`storage_backends`required	array of string	`ankra-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`
`features`required	object
`compute`required	boolean	False in a network-only location: the zone has no compute node and runs no servers.
`live_migration`required	boolean
`ha_restart`required	boolean
`load_balancer_ha`required	boolean
`separate_edges`required	boolean
`reasons`	map of string	Why the zone lacks each feature that is false, keyed by the feature's name.
`underlay`required	string	How the zone's hosts reach each other (ADR 0004): `fabric` is a private network, `wireguard` the encrypted underlay.One of `fabric`, `wireguard`
`datacenters`required	array of Datacenter	Where the zone's nodes stand.
`name`required	string \| null	null groups the nodes without a recorded datacenter.
`nodes`required	integer
`storage_nodes`required	integer
`compute_nodes`required	integer
`latency_budget`required	array of DatacenterLink	Every 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.
`from`required	string \| null
`to`required	string \| null
`host_pairs`required	integer
`measured_pairs`required	integer
`worst_p95_rtt_ms`required	number \| null
`lowest_bandwidth_bits_per_second`required	integer \| null
`ceph_replication`required	string	Ankra Storage replication's budget: p95 RTT under 2 ms.One of `within`, `over`, `unmeasured`
`live_migration`required	string	Budget p95 RTT under 5 ms and at least 1 Gbit/s.One of `within`, `over`, `unmeasured`
`storage_durability`	string	`replicated` 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_reason`	string \| null	Why the durability is not replicated.
`storage_copies`	string	How 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_tier`required	string	The 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_offered`required	boolean	Whether 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_reason`required	string \| null	Why 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.
`cpu_pools`	array of object	The compute nodes grouped by exact CPU; servers are placed in one and migrate within it.
`name`required	string
`vendor`required	string
`family`required	integer
`model`required	string
`flag_count`required	integer
`nodes`required	integer
`backup_targets`	array of string	`ceph` 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_storage`	object	Whether the zone's Ankra Local (`local-nvme`) storage takes new volumes now.
`accepts_new_volumes`required	boolean	False when every Ankra Local thin pool of the zone is too full or too overcommitted for a new volume.
`reason`required	string \| null	Why some or all of the zone's pools take no new volumes; null when every pool does.
`warnings`	array of string	What 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.
`recovery`	string	What 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, so the account can restore them as new storages (by hand; no operation does it by itself). `none`: it returns only with its host.One of `none`, `restore`, `restart`
`recovery_reason`	string \| null	Why recovery is not a restart.
`gateway_redundancy`	string	`single`: the zone has one gateway, and its public networking stops while that host is down.One of `none`, `single`, `redundant`
`gateway_redundancy_reason`	string \| null
`uplink_redundancy`	string	`redundant`: 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_reason`	string \| null
`object_storage_durability`	string	How 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_backups`	boolean	Whether 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_reason`	string \| null	Why backups do not leave the zone.
`default_backup`	object \| null	The 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).
`interval`required	string	One of `daily`
`retention_days`required	integer

401Not signed in, or the credential is invalid or expired.
403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
404No such resource in the caller's account.
defaultAny other error, usually 500.

Example

bash

curl 'https://cloud.ankra.app/v1/zones/<zone>/capabilities' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"