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#
/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
| Field | Type | Description |
|---|---|---|
itemsrequired | array of Zone | |
namerequired | string | |
regionrequired | string | |
display_namerequired | string | |
created_atrequired | 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. |
sold_out_plan_families | array of string | The 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_cpu | boolean | True 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_available | boolean | Whether 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_cursorrequired | 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_credentialson 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
curl 'https://cloud.ankra.app/v1/zones' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"What the zone offers at its growth stage#
/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
| Name | In | Type | Description |
|---|---|---|---|
zonerequired | path | string |
Responses
200The zone's stage, servers, gateways, storage backends and features.application/json · ZoneCapabilities
| Field | Type | Description |
|---|---|---|
stagerequired | integer | 1 for one server, 2 for two, 3 from three on; 0 before any server registered. |
serversrequired | integer | Nodes with a gateway, storage or compute role. |
gatewaysrequired | integer | |
compute_nodes | integer | The hypervisor hosts servers are placed on; 0 in a network-only location. |
storage_backendsrequired | 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 |
featuresrequired | object | |
computerequired | boolean | False in a network-only location: the zone has no compute node and runs no servers. |
live_migrationrequired | boolean | |
ha_restartrequired | boolean | |
load_balancer_harequired | boolean | |
separate_edgesrequired | boolean | |
reasons | map of string | Why the zone lacks each feature that is false, keyed by the feature's name. |
underlayrequired | string | How the zone's hosts reach each other (ADR 0004): fabric is a private network, wireguard the encrypted underlay.One of fabric, wireguard |
datacentersrequired | array of Datacenter | Where the zone's nodes stand. |
namerequired | string | null | null groups the nodes without a recorded datacenter. |
nodesrequired | integer | |
storage_nodesrequired | integer | |
compute_nodesrequired | integer | |
latency_budgetrequired | 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. |
fromrequired | string | null | |
torequired | string | null | |
host_pairsrequired | integer | |
measured_pairsrequired | integer | |
worst_p95_rtt_msrequired | number | null | |
lowest_bandwidth_bits_per_secondrequired | integer | null | |
ceph_replicationrequired | string | Ankra Storage replication's budget: p95 RTT under 2 ms.One of within, over, unmeasured |
live_migrationrequired | 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_tierrequired | 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_offeredrequired | 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_reasonrequired | 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. |
networking | object | How 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). |
ipv6required | boolean | A server gets a public IPv6 delegation of its own (an active IPv6 pool). |
public_ipv4required | boolean | A server can take the IPv4 add-on now. False while public IPv4 is unavailable in the zone. |
public_ipv4_survives_gateway_lossrequired | boolean | Whether 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_routersrequired | boolean | A router can take a NAT address now: one of the zone's routed IPv4 pools has a free address. |
nat64required | boolean | The zone's gateways translate IPv6-only servers' traffic to IPv4: names through DNS64, IPv4 sockets through the guest's CLAT (464XLAT). |
port_forwardrequired | boolean | A 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_sourcesrequired | array of string | Where 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_pools | array of object | The compute nodes grouped by exact CPU; servers are placed in one and migrate within it. |
namerequired | string | |
vendorrequired | string | |
familyrequired | integer | |
modelrequired | string | |
flag_countrequired | integer | |
x86_64_levelrequired | integer | The 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. |
nodesrequired | 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_volumesrequired | boolean | False when every Ankra Local thin pool of the zone is too full or too overcommitted for a new volume. |
reasonrequired | 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: 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_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). |
intervalrequired | string | One of daily |
retention_daysrequired | integer | |
database_backups | boolean | Whether 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_reason | string | null | Why managed databases in the zone keep no backups. |
account | object | null | What 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_nodesrequired | integer | |
quota_remainingrequired | object | |
serversrequired | integer | |
coresrequired | integer | |
memory_mebibytesrequired | integer | |
storage_gibibytesrequired | integer | |
floating_ipsrequired | integer | |
routersrequired | integer | |
private_networksrequired | integer | |
public_ipv4_addressesrequired | 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_credentialson 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
curl 'https://cloud.ankra.app/v1/zones/<zone>/capabilities' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"