API reference · Networking
Load balancers
22 operations of the Ankra Cloud API: Managed load balancers and their certificates.
List load balancers#
/v1/load-balancers- Operation
list_load_balancers- Credentials
- API token, Portal session
- Requires
- Permission
read
Without nodes, frontends and backends; get one for those. Keyset-paginated, newest first: limit is 1 to 100 (default 50) and next_cursor is null on the last page; pass it back as cursor for the next one. A malformed cursor or a limit out of range is a 400.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
cursor | query | string | The next_cursor of the previous page. |
limit | query | integer | Page size; the server applies its default and maximum. |
label | query | array of string | key=value; repeat to require several labels. Only load balancers carrying every label are listed. |
Responses
200A page of the load balancers that match, newest first.application/json
| Field | Type | Description |
|---|---|---|
itemsrequired | array of LoadBalancer | |
idrequired | string | |
zonerequired | string | |
region | string | The region of the load balancer's zone. |
namerequired | string | |
network_idrequired | string | |
staterequired | string | One of creating, running, error, deleting |
labelsrequired | Labels | Keys 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. |
high_availabilityrequired | boolean | Two VMs on different compute nodes (true) or one (false). A load balancer created without high_availability in a zone that lacks the load_balancer_ha capability (one compute node, see get_zone_capabilities) runs on a single VM; asking for a pair there is refused with 409. |
public_ipv4required | string | null | The floating IPv4 frontend address (the add-on); null without the add-on or until allocated. |
public_ipv6required | string | null | The IPv6 frontend address to publish: the first VM's own address (the first of its public /64). On a pair it does not fail over to the second VM; publish public_ipv6_addresses for that. Null until the VM's /64 is allocated. |
public_ipv6_addressesrequired | array of string | Every VM's IPv6 frontend address, in VM order; each VM serves every frontend on its own. |
addressrequired | string | null | The public IPv4 address, the same as public_ipv4 (kept for older clients); null without the IPv4 add-on or until allocated. |
internalrequired | boolean | Reachable only on its private network, at private_address: from servers there, peered networks and VPN gateways that connect the network. It has no public frontend address (public_ipv4, public_ipv6 and public_ipv6_addresses stay empty) and its VMs admit the frontends' ports only from the network's ranges. |
private_addressrequired | string | null | An internal load balancer's frontend address on its private network, reserved so no server takes it; it moves between the VMs of a pair. Null on a public load balancer. |
configuration_generationrequired | integer | |
is_configuration_appliedrequired | boolean | |
nodesrequired | array of object | |
idrequired | string | |
namerequired | string | |
staterequired | string | |
is_activerequired | boolean | The VM that holds the load balancer's address (the active member of the pair's failover), as its guest last reported. |
is_healthyrequired | boolean | |
health_detailrequired | string | |
is_configuration_appliedrequired | boolean | |
frontendsrequired | array of LoadBalancerFrontend | |
idrequired | string | |
namerequired | string | |
portrequired | integer | |
moderequired | string | The mode of its backend.One of tcp, http |
backend_idrequired | string | |
tlsrequired | boolean | Terminates TLS with its certificates. |
certificate_idsrequired | array of string | The first answers clients that send no server name; the others are chosen by SNI. |
redirect_to_httpsrequired | boolean | Answers every request with a 301 to https on the same host. |
backendsrequired | array of LoadBalancerBackend | |
idrequired | string | |
namerequired | string | |
moderequired | string | One of tcp, http |
balancerequired | string | One of roundrobin, leastconn, source |
health_check_pathrequired | string | The http check's path, empty for other checks. Kept for older clients; read health_check. |
health_checkrequired | LoadBalancerHealthCheck | |
typerequired | string | tcp connects to the member; http sends GET <path>; none never checks.One of tcp, http, none |
pathrequired | string | For http checks. |
expected_statusrequired | string | For http checks: 200, or a range such as 200-399. |
interval_secondsrequired | integer | |
riserequired | integer | Successes that bring a member back. |
fallrequired | integer | Failures that take a member out. |
membersrequired | array of LoadBalancerMember | |
idrequired | string | |
backend_idrequired | string | |
namerequired | string | |
addressrequired | string | An IPv4 or IPv6 address. |
portrequired | integer | |
weightrequired | integer | |
enabledrequired | boolean | |
active_operationrequired | Operation | null | |
idrequired | string | |
kindrequired | string | One of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify |
server_idrequired | string | null | |
storage_idrequired | string | null | |
backup_idrequired | string | null | |
template_idrequired | string | null | |
router_idrequired | string | null | |
floating_ip_idrequired | string | null | |
node_id | string | Set on node maintenance operations (operator only); absent otherwise. |
load_balancer_id | string | null | Set on the operations that create and delete a load balancer. |
database_id | string | null | Set on the operations that create and delete a managed database. |
edge_id | string | null | Set on the operations that sync and delete a network edge. |
vpn_gateway_id | string | null | Set on the operations that sync and delete a VPN gateway. |
snapshot_id | string | null | Set on the operations that create and delete a snapshot, and on a storage.create that clones one. |
kubernetes_cluster_id | string | null | Set on the operations of a managed Kubernetes cluster. |
node_pool_id | string | null | Set on the operations of a Kubernetes node pool. |
kubernetes_host_id | string | Set on a regional host cluster bootstrap (operator only); absent otherwise. |
statusrequired | string | One of pending, running, succeeded, failed, cancelled |
steprequired | string | Machine name of the current step, e.g. create_disk or transfer_cross_zone. |
step_indexrequired | integer | |
step_countrequired | integer | |
errorrequired | string | Empty unless the operation failed. |
created_atrequired | string (date-time) | |
started_atrequired | string (date-time) | null | |
finished_atrequired | string (date-time) | null | |
deadline_atrequired | string (date-time) | |
actor | string | Who asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations. |
progress | MigrationProgress | Present on GET /v1/operations/{id} while a server.migrate drives a live transfer. |
staterequired | string | One of reserved, detached, preparing, sending, switched, aborting |
source_node_idrequired | string | |
target_node_idrequired | string | |
phaserequired | string | How far the nodes report the current attempt.One of , preparing, transferring, completed, failed |
attemptrequired | integer | Which send this is under the convergence policy, from 1. |
iterationrequired | integer | Memory passes so far in the current attempt. |
transferred_bytesrequired | integer | |
total_bytesrequired | integer | 0 when the hypervisor does not report it. |
dirty_bytes_per_secondrequired | integer | |
downtime_millisecondsrequired | integer | The pause the guest took at handover, once completed. |
detailrequired | string | |
reported_atrequired | string (date-time) | null | The reporting node's clock. |
events | array of OperationEvent | Present on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first. |
atrequired | string (date-time) | |
kindrequired | string | For example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed. |
messagerequired | string | |
datarequired | object | |
created_atrequired | string (date-time) | |
next_cursorrequired | string | null | Pass as ?cursor= for the next page; null on the last page. |
- 400The request is invalid;
detailsays 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_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/load-balancers' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Create a load balancer on a private network#
/v1/load-balancers- Operation
create_load_balancer- Credentials
- API token, Portal session
- Requires
- Permission
operate
HAProxy on the account's private network. high_availability true is two VMs on different compute nodes that
move a floating IPv4 address between them with VRRP; false is one VM. Without the field a zone with two or more
compute nodes gets a pair and a zone with one gets a single VM; asking for a pair where the zone lacks the
load_balancer_ha capability (one compute node, see get_zone_capabilities) is a 409 that says so.
IPv6 is always on: every VM serves the frontends on the first address of its own public /64 (public_ipv6, all
of them in public_ipv6_addresses). On a pair that address is the first VM's and does not move to the second
when the first fails: VRRP carries the IPv4 address only, so publish every entry of public_ipv6_addresses
(for example as several AAAA records or Service ingress IPs) for IPv6 failover. A load balancer is IPv6-only
unless the request asks for IPv4: public_ipv4 (default false) true adds a floating IPv4 frontend address, the
paid add-on, and is refused with 400 in a zone that offers no public IPv4.
Price per month: €1.49 per VM plus €4.00 for every public IPv4 address the load balancer holds. With the IPv4
add-on it holds its frontend address, part of the load balancer's usage line, and each VM holds an address of
its own, a public_ipv4 line where that address is a public IPv4 address and nothing where it is not. So a
pair with IPv4 costs at most €14.98 and one VM with IPv4 at most €9.49; a pair without costs €2.98 and one VM
without €1.49. The platform assigns the addresses. An account may hold 5.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
Idempotency-Key | header | string | A 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
| Field | Type | Description |
|---|---|---|
zonerequired | string | |
namerequired | string | |
network_idrequired | string | |
labels | Labels | Keys 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. |
high_availability | boolean | Two VMs on different compute nodes (true) or one (false). Defaults to true where the zone has two compute nodes, false where it has one. |
public_ipv4 | boolean | The floating IPv4 frontend address, the paid add-on. Default false: IPv6 only, which is always on. |
internal | boolean | Internal only: the load balancer takes an address on network_id and serves its frontends there, never on the internet. Reach it from servers on the network or through a VPN gateway that connects it. Cannot be combined with public_ipv4 (400). |
zone_redundant | boolean | A VM pair in each of two or more zones of the zone's region. Validated against the region (400 in a region with one zone), then answered 501 until zone-redundant placement lands. |
Responses
202The load balancer and its load_balancer.create operation.application/json
| Field | Type | Description |
|---|---|---|
load_balancerrequired | LoadBalancer | |
idrequired | string | |
zonerequired | string | |
region | string | The region of the load balancer's zone. |
namerequired | string | |
network_idrequired | string | |
staterequired | string | One of creating, running, error, deleting |
labelsrequired | Labels | Keys 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. |
high_availabilityrequired | boolean | Two VMs on different compute nodes (true) or one (false). A load balancer created without high_availability in a zone that lacks the load_balancer_ha capability (one compute node, see get_zone_capabilities) runs on a single VM; asking for a pair there is refused with 409. |
public_ipv4required | string | null | The floating IPv4 frontend address (the add-on); null without the add-on or until allocated. |
public_ipv6required | string | null | The IPv6 frontend address to publish: the first VM's own address (the first of its public /64). On a pair it does not fail over to the second VM; publish public_ipv6_addresses for that. Null until the VM's /64 is allocated. |
public_ipv6_addressesrequired | array of string | Every VM's IPv6 frontend address, in VM order; each VM serves every frontend on its own. |
addressrequired | string | null | The public IPv4 address, the same as public_ipv4 (kept for older clients); null without the IPv4 add-on or until allocated. |
internalrequired | boolean | Reachable only on its private network, at private_address: from servers there, peered networks and VPN gateways that connect the network. It has no public frontend address (public_ipv4, public_ipv6 and public_ipv6_addresses stay empty) and its VMs admit the frontends' ports only from the network's ranges. |
private_addressrequired | string | null | An internal load balancer's frontend address on its private network, reserved so no server takes it; it moves between the VMs of a pair. Null on a public load balancer. |
configuration_generationrequired | integer | |
is_configuration_appliedrequired | boolean | |
nodesrequired | array of object | |
idrequired | string | |
namerequired | string | |
staterequired | string | |
is_activerequired | boolean | The VM that holds the load balancer's address (the active member of the pair's failover), as its guest last reported. |
is_healthyrequired | boolean | |
health_detailrequired | string | |
is_configuration_appliedrequired | boolean | |
frontendsrequired | array of LoadBalancerFrontend | |
idrequired | string | |
namerequired | string | |
portrequired | integer | |
moderequired | string | The mode of its backend.One of tcp, http |
backend_idrequired | string | |
tlsrequired | boolean | Terminates TLS with its certificates. |
certificate_idsrequired | array of string | The first answers clients that send no server name; the others are chosen by SNI. |
redirect_to_httpsrequired | boolean | Answers every request with a 301 to https on the same host. |
backendsrequired | array of LoadBalancerBackend | |
idrequired | string | |
namerequired | string | |
moderequired | string | One of tcp, http |
balancerequired | string | One of roundrobin, leastconn, source |
health_check_pathrequired | string | The http check's path, empty for other checks. Kept for older clients; read health_check. |
health_checkrequired | LoadBalancerHealthCheck | |
typerequired | string | tcp connects to the member; http sends GET <path>; none never checks.One of tcp, http, none |
pathrequired | string | For http checks. |
expected_statusrequired | string | For http checks: 200, or a range such as 200-399. |
interval_secondsrequired | integer | |
riserequired | integer | Successes that bring a member back. |
fallrequired | integer | Failures that take a member out. |
membersrequired | array of LoadBalancerMember | |
idrequired | string | |
backend_idrequired | string | |
namerequired | string | |
addressrequired | string | An IPv4 or IPv6 address. |
portrequired | integer | |
weightrequired | integer | |
enabledrequired | boolean | |
active_operationrequired | Operation | null | |
idrequired | string | |
kindrequired | string | One of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify |
server_idrequired | string | null | |
storage_idrequired | string | null | |
backup_idrequired | string | null | |
template_idrequired | string | null | |
router_idrequired | string | null | |
floating_ip_idrequired | string | null | |
node_id | string | Set on node maintenance operations (operator only); absent otherwise. |
load_balancer_id | string | null | Set on the operations that create and delete a load balancer. |
database_id | string | null | Set on the operations that create and delete a managed database. |
edge_id | string | null | Set on the operations that sync and delete a network edge. |
vpn_gateway_id | string | null | Set on the operations that sync and delete a VPN gateway. |
snapshot_id | string | null | Set on the operations that create and delete a snapshot, and on a storage.create that clones one. |
kubernetes_cluster_id | string | null | Set on the operations of a managed Kubernetes cluster. |
node_pool_id | string | null | Set on the operations of a Kubernetes node pool. |
kubernetes_host_id | string | Set on a regional host cluster bootstrap (operator only); absent otherwise. |
statusrequired | string | One of pending, running, succeeded, failed, cancelled |
steprequired | string | Machine name of the current step, e.g. create_disk or transfer_cross_zone. |
step_indexrequired | integer | |
step_countrequired | integer | |
errorrequired | string | Empty unless the operation failed. |
created_atrequired | string (date-time) | |
started_atrequired | string (date-time) | null | |
finished_atrequired | string (date-time) | null | |
deadline_atrequired | string (date-time) | |
actor | string | Who asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations. |
progress | MigrationProgress | Present on GET /v1/operations/{id} while a server.migrate drives a live transfer. |
staterequired | string | One of reserved, detached, preparing, sending, switched, aborting |
source_node_idrequired | string | |
target_node_idrequired | string | |
phaserequired | string | How far the nodes report the current attempt.One of , preparing, transferring, completed, failed |
attemptrequired | integer | Which send this is under the convergence policy, from 1. |
iterationrequired | integer | Memory passes so far in the current attempt. |
transferred_bytesrequired | integer | |
total_bytesrequired | integer | 0 when the hypervisor does not report it. |
dirty_bytes_per_secondrequired | integer | |
downtime_millisecondsrequired | integer | The pause the guest took at handover, once completed. |
detailrequired | string | |
reported_atrequired | string (date-time) | null | The reporting node's clock. |
events | array of OperationEvent | Present on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first. |
atrequired | string (date-time) | |
kindrequired | string | For example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed. |
messagerequired | string | |
datarequired | object | |
created_atrequired | string (date-time) | |
operationrequired | Operation | |
idrequired | string | |
kindrequired | string | One of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify |
server_idrequired | string | null | |
storage_idrequired | string | null | |
backup_idrequired | string | null | |
template_idrequired | string | null | |
router_idrequired | string | null | |
floating_ip_idrequired | string | null | |
node_id | string | Set on node maintenance operations (operator only); absent otherwise. |
load_balancer_id | string | null | Set on the operations that create and delete a load balancer. |
database_id | string | null | Set on the operations that create and delete a managed database. |
edge_id | string | null | Set on the operations that sync and delete a network edge. |
vpn_gateway_id | string | null | Set on the operations that sync and delete a VPN gateway. |
snapshot_id | string | null | Set on the operations that create and delete a snapshot, and on a storage.create that clones one. |
kubernetes_cluster_id | string | null | Set on the operations of a managed Kubernetes cluster. |
node_pool_id | string | null | Set on the operations of a Kubernetes node pool. |
kubernetes_host_id | string | Set on a regional host cluster bootstrap (operator only); absent otherwise. |
statusrequired | string | One of pending, running, succeeded, failed, cancelled |
steprequired | string | Machine name of the current step, e.g. create_disk or transfer_cross_zone. |
step_indexrequired | integer | |
step_countrequired | integer | |
errorrequired | string | Empty unless the operation failed. |
created_atrequired | string (date-time) | |
started_atrequired | string (date-time) | null | |
finished_atrequired | string (date-time) | null | |
deadline_atrequired | string (date-time) | |
actor | string | Who asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations. |
progress | MigrationProgress | Present on GET /v1/operations/{id} while a server.migrate drives a live transfer. |
staterequired | string | One of reserved, detached, preparing, sending, switched, aborting |
source_node_idrequired | string | |
target_node_idrequired | string | |
phaserequired | string | How far the nodes report the current attempt.One of , preparing, transferring, completed, failed |
attemptrequired | integer | Which send this is under the convergence policy, from 1. |
iterationrequired | integer | Memory passes so far in the current attempt. |
transferred_bytesrequired | integer | |
total_bytesrequired | integer | 0 when the hypervisor does not report it. |
dirty_bytes_per_secondrequired | integer | |
downtime_millisecondsrequired | integer | The pause the guest took at handover, once completed. |
detailrequired | string | |
reported_atrequired | string (date-time) | null | The reporting node's clock. |
events | array of OperationEvent | Present on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first. |
atrequired | string (date-time) | |
kindrequired | string | For example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed. |
messagerequired | string | |
datarequired | object |
- 400The request is invalid;
detailsays why. - 401Not signed in, or the credential is invalid or expired.
- 402The account may not create this.
reasonispayment_method_requiredwhile 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 throughPOST /v1/account/billing/setup-session, or free what the account no longer needs);owner_approval_requiredwhile its owner has not approved paid usage and no credit is left; oraccount_suspendedwhile an invoice is overdue past the grace period (pay it) or Ankra staff suspended the account (contact support). Aprepaidaccount (linked to an Ankra platform organisation) is refused withpayment_method_requiredwhile it has no card, and withcredit_requiredonce 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, andtop_up_urlnames that page when Cloud knows it.GET /v1/account/billingreports the samestanding. Forpayment_method_requiredandcredit_required,detailnames 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_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.
- 409The resource's state does not allow this now.
- 422The account would exceed a quota;
detailnames the limit andreasonisquota_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 indetail), or a host did not answer; try another plan or zone, or try again later. - defaultAny other error, usually 500.
Example
curl -X POST 'https://cloud.ankra.app/v1/load-balancers' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"zone": "string",
"name": "string",
"network_id": "string"
}'Get a load balancer with its VMs, frontends and backends#
/v1/load-balancers/{id}- Operation
get_load_balancer- Credentials
- API token, Portal session
- Requires
- Permission
read
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
200The load balancer.application/json
| Field | Type | Description |
|---|---|---|
load_balancerrequired | LoadBalancer | |
idrequired | string | |
zonerequired | string | |
region | string | The region of the load balancer's zone. |
namerequired | string | |
network_idrequired | string | |
staterequired | string | One of creating, running, error, deleting |
labelsrequired | Labels | Keys 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. |
high_availabilityrequired | boolean | Two VMs on different compute nodes (true) or one (false). A load balancer created without high_availability in a zone that lacks the load_balancer_ha capability (one compute node, see get_zone_capabilities) runs on a single VM; asking for a pair there is refused with 409. |
public_ipv4required | string | null | The floating IPv4 frontend address (the add-on); null without the add-on or until allocated. |
public_ipv6required | string | null | The IPv6 frontend address to publish: the first VM's own address (the first of its public /64). On a pair it does not fail over to the second VM; publish public_ipv6_addresses for that. Null until the VM's /64 is allocated. |
public_ipv6_addressesrequired | array of string | Every VM's IPv6 frontend address, in VM order; each VM serves every frontend on its own. |
addressrequired | string | null | The public IPv4 address, the same as public_ipv4 (kept for older clients); null without the IPv4 add-on or until allocated. |
internalrequired | boolean | Reachable only on its private network, at private_address: from servers there, peered networks and VPN gateways that connect the network. It has no public frontend address (public_ipv4, public_ipv6 and public_ipv6_addresses stay empty) and its VMs admit the frontends' ports only from the network's ranges. |
private_addressrequired | string | null | An internal load balancer's frontend address on its private network, reserved so no server takes it; it moves between the VMs of a pair. Null on a public load balancer. |
configuration_generationrequired | integer | |
is_configuration_appliedrequired | boolean | |
nodesrequired | array of object | |
idrequired | string | |
namerequired | string | |
staterequired | string | |
is_activerequired | boolean | The VM that holds the load balancer's address (the active member of the pair's failover), as its guest last reported. |
is_healthyrequired | boolean | |
health_detailrequired | string | |
is_configuration_appliedrequired | boolean | |
frontendsrequired | array of LoadBalancerFrontend | |
idrequired | string | |
namerequired | string | |
portrequired | integer | |
moderequired | string | The mode of its backend.One of tcp, http |
backend_idrequired | string | |
tlsrequired | boolean | Terminates TLS with its certificates. |
certificate_idsrequired | array of string | The first answers clients that send no server name; the others are chosen by SNI. |
redirect_to_httpsrequired | boolean | Answers every request with a 301 to https on the same host. |
backendsrequired | array of LoadBalancerBackend | |
idrequired | string | |
namerequired | string | |
moderequired | string | One of tcp, http |
balancerequired | string | One of roundrobin, leastconn, source |
health_check_pathrequired | string | The http check's path, empty for other checks. Kept for older clients; read health_check. |
health_checkrequired | LoadBalancerHealthCheck | |
typerequired | string | tcp connects to the member; http sends GET <path>; none never checks.One of tcp, http, none |
pathrequired | string | For http checks. |
expected_statusrequired | string | For http checks: 200, or a range such as 200-399. |
interval_secondsrequired | integer | |
riserequired | integer | Successes that bring a member back. |
fallrequired | integer | Failures that take a member out. |
membersrequired | array of LoadBalancerMember | |
idrequired | string | |
backend_idrequired | string | |
namerequired | string | |
addressrequired | string | An IPv4 or IPv6 address. |
portrequired | integer | |
weightrequired | integer | |
enabledrequired | boolean | |
active_operationrequired | Operation | null | |
idrequired | string | |
kindrequired | string | One of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify |
server_idrequired | string | null | |
storage_idrequired | string | null | |
backup_idrequired | string | null | |
template_idrequired | string | null | |
router_idrequired | string | null | |
floating_ip_idrequired | string | null | |
node_id | string | Set on node maintenance operations (operator only); absent otherwise. |
load_balancer_id | string | null | Set on the operations that create and delete a load balancer. |
database_id | string | null | Set on the operations that create and delete a managed database. |
edge_id | string | null | Set on the operations that sync and delete a network edge. |
vpn_gateway_id | string | null | Set on the operations that sync and delete a VPN gateway. |
snapshot_id | string | null | Set on the operations that create and delete a snapshot, and on a storage.create that clones one. |
kubernetes_cluster_id | string | null | Set on the operations of a managed Kubernetes cluster. |
node_pool_id | string | null | Set on the operations of a Kubernetes node pool. |
kubernetes_host_id | string | Set on a regional host cluster bootstrap (operator only); absent otherwise. |
statusrequired | string | One of pending, running, succeeded, failed, cancelled |
steprequired | string | Machine name of the current step, e.g. create_disk or transfer_cross_zone. |
step_indexrequired | integer | |
step_countrequired | integer | |
errorrequired | string | Empty unless the operation failed. |
created_atrequired | string (date-time) | |
started_atrequired | string (date-time) | null | |
finished_atrequired | string (date-time) | null | |
deadline_atrequired | string (date-time) | |
actor | string | Who asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations. |
progress | MigrationProgress | Present on GET /v1/operations/{id} while a server.migrate drives a live transfer. |
staterequired | string | One of reserved, detached, preparing, sending, switched, aborting |
source_node_idrequired | string | |
target_node_idrequired | string | |
phaserequired | string | How far the nodes report the current attempt.One of , preparing, transferring, completed, failed |
attemptrequired | integer | Which send this is under the convergence policy, from 1. |
iterationrequired | integer | Memory passes so far in the current attempt. |
transferred_bytesrequired | integer | |
total_bytesrequired | integer | 0 when the hypervisor does not report it. |
dirty_bytes_per_secondrequired | integer | |
downtime_millisecondsrequired | integer | The pause the guest took at handover, once completed. |
detailrequired | string | |
reported_atrequired | string (date-time) | null | The reporting node's clock. |
events | array of OperationEvent | Present on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first. |
atrequired | string (date-time) | |
kindrequired | string | For example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed. |
messagerequired | string | |
datarequired | object | |
created_atrequired | string (date-time) |
- 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_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/load-balancers/<id>' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Rename a load balancer or replace its labels#
/v1/load-balancers/{id}- Operation
update_load_balancer- Credentials
- API token, Portal session
- Requires
- Permission
operate
labels replaces the labels whole ({} removes them all); an absent field is left unchanged. Neither reaches
HAProxy, so the configuration generation stays. 409 when the name is taken or the load balancer is being deleted.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request bodyapplication/json
| Field | Type | Description |
|---|---|---|
name | string | |
labels | Labels | Keys 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. |
Responses
200The load balancer, described in full.application/json
| Field | Type | Description |
|---|---|---|
load_balancerrequired | LoadBalancer | |
idrequired | string | |
zonerequired | string | |
region | string | The region of the load balancer's zone. |
namerequired | string | |
network_idrequired | string | |
staterequired | string | One of creating, running, error, deleting |
labelsrequired | Labels | Keys 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. |
high_availabilityrequired | boolean | Two VMs on different compute nodes (true) or one (false). A load balancer created without high_availability in a zone that lacks the load_balancer_ha capability (one compute node, see get_zone_capabilities) runs on a single VM; asking for a pair there is refused with 409. |
public_ipv4required | string | null | The floating IPv4 frontend address (the add-on); null without the add-on or until allocated. |
public_ipv6required | string | null | The IPv6 frontend address to publish: the first VM's own address (the first of its public /64). On a pair it does not fail over to the second VM; publish public_ipv6_addresses for that. Null until the VM's /64 is allocated. |
public_ipv6_addressesrequired | array of string | Every VM's IPv6 frontend address, in VM order; each VM serves every frontend on its own. |
addressrequired | string | null | The public IPv4 address, the same as public_ipv4 (kept for older clients); null without the IPv4 add-on or until allocated. |
internalrequired | boolean | Reachable only on its private network, at private_address: from servers there, peered networks and VPN gateways that connect the network. It has no public frontend address (public_ipv4, public_ipv6 and public_ipv6_addresses stay empty) and its VMs admit the frontends' ports only from the network's ranges. |
private_addressrequired | string | null | An internal load balancer's frontend address on its private network, reserved so no server takes it; it moves between the VMs of a pair. Null on a public load balancer. |
configuration_generationrequired | integer | |
is_configuration_appliedrequired | boolean | |
nodesrequired | array of object | |
idrequired | string | |
namerequired | string | |
staterequired | string | |
is_activerequired | boolean | The VM that holds the load balancer's address (the active member of the pair's failover), as its guest last reported. |
is_healthyrequired | boolean | |
health_detailrequired | string | |
is_configuration_appliedrequired | boolean | |
frontendsrequired | array of LoadBalancerFrontend | |
idrequired | string | |
namerequired | string | |
portrequired | integer | |
moderequired | string | The mode of its backend.One of tcp, http |
backend_idrequired | string | |
tlsrequired | boolean | Terminates TLS with its certificates. |
certificate_idsrequired | array of string | The first answers clients that send no server name; the others are chosen by SNI. |
redirect_to_httpsrequired | boolean | Answers every request with a 301 to https on the same host. |
backendsrequired | array of LoadBalancerBackend | |
idrequired | string | |
namerequired | string | |
moderequired | string | One of tcp, http |
balancerequired | string | One of roundrobin, leastconn, source |
health_check_pathrequired | string | The http check's path, empty for other checks. Kept for older clients; read health_check. |
health_checkrequired | LoadBalancerHealthCheck | |
typerequired | string | tcp connects to the member; http sends GET <path>; none never checks.One of tcp, http, none |
pathrequired | string | For http checks. |
expected_statusrequired | string | For http checks: 200, or a range such as 200-399. |
interval_secondsrequired | integer | |
riserequired | integer | Successes that bring a member back. |
fallrequired | integer | Failures that take a member out. |
membersrequired | array of LoadBalancerMember | |
idrequired | string | |
backend_idrequired | string | |
namerequired | string | |
addressrequired | string | An IPv4 or IPv6 address. |
portrequired | integer | |
weightrequired | integer | |
enabledrequired | boolean | |
active_operationrequired | Operation | null | |
idrequired | string | |
kindrequired | string | One of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify |
server_idrequired | string | null | |
storage_idrequired | string | null | |
backup_idrequired | string | null | |
template_idrequired | string | null | |
router_idrequired | string | null | |
floating_ip_idrequired | string | null | |
node_id | string | Set on node maintenance operations (operator only); absent otherwise. |
load_balancer_id | string | null | Set on the operations that create and delete a load balancer. |
database_id | string | null | Set on the operations that create and delete a managed database. |
edge_id | string | null | Set on the operations that sync and delete a network edge. |
vpn_gateway_id | string | null | Set on the operations that sync and delete a VPN gateway. |
snapshot_id | string | null | Set on the operations that create and delete a snapshot, and on a storage.create that clones one. |
kubernetes_cluster_id | string | null | Set on the operations of a managed Kubernetes cluster. |
node_pool_id | string | null | Set on the operations of a Kubernetes node pool. |
kubernetes_host_id | string | Set on a regional host cluster bootstrap (operator only); absent otherwise. |
statusrequired | string | One of pending, running, succeeded, failed, cancelled |
steprequired | string | Machine name of the current step, e.g. create_disk or transfer_cross_zone. |
step_indexrequired | integer | |
step_countrequired | integer | |
errorrequired | string | Empty unless the operation failed. |
created_atrequired | string (date-time) | |
started_atrequired | string (date-time) | null | |
finished_atrequired | string (date-time) | null | |
deadline_atrequired | string (date-time) | |
actor | string | Who asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations. |
progress | MigrationProgress | Present on GET /v1/operations/{id} while a server.migrate drives a live transfer. |
staterequired | string | One of reserved, detached, preparing, sending, switched, aborting |
source_node_idrequired | string | |
target_node_idrequired | string | |
phaserequired | string | How far the nodes report the current attempt.One of , preparing, transferring, completed, failed |
attemptrequired | integer | Which send this is under the convergence policy, from 1. |
iterationrequired | integer | Memory passes so far in the current attempt. |
transferred_bytesrequired | integer | |
total_bytesrequired | integer | 0 when the hypervisor does not report it. |
dirty_bytes_per_secondrequired | integer | |
downtime_millisecondsrequired | integer | The pause the guest took at handover, once completed. |
detailrequired | string | |
reported_atrequired | string (date-time) | null | The reporting node's clock. |
events | array of OperationEvent | Present on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first. |
atrequired | string (date-time) | |
kindrequired | string | For example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed. |
messagerequired | string | |
datarequired | object | |
created_atrequired | string (date-time) |
- 400The request is invalid;
detailsays 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_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.
- 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
curl -X PATCH 'https://cloud.ankra.app/v1/load-balancers/<id>' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"name": "string",
"labels": {}
}'Delete a load balancer, its VMs and its address#
/v1/load-balancers/{id}- Operation
delete_load_balancer- Credentials
- API token, Portal session
- Requires
- Permission
operate
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
202Accepted; poll the operation.application/json · OperationEnvelope
| Field | Type | Description |
|---|---|---|
operationrequired | Operation | |
idrequired | string | |
kindrequired | string | One of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify |
server_idrequired | string | null | |
storage_idrequired | string | null | |
backup_idrequired | string | null | |
template_idrequired | string | null | |
router_idrequired | string | null | |
floating_ip_idrequired | string | null | |
node_id | string | Set on node maintenance operations (operator only); absent otherwise. |
load_balancer_id | string | null | Set on the operations that create and delete a load balancer. |
database_id | string | null | Set on the operations that create and delete a managed database. |
edge_id | string | null | Set on the operations that sync and delete a network edge. |
vpn_gateway_id | string | null | Set on the operations that sync and delete a VPN gateway. |
snapshot_id | string | null | Set on the operations that create and delete a snapshot, and on a storage.create that clones one. |
kubernetes_cluster_id | string | null | Set on the operations of a managed Kubernetes cluster. |
node_pool_id | string | null | Set on the operations of a Kubernetes node pool. |
kubernetes_host_id | string | Set on a regional host cluster bootstrap (operator only); absent otherwise. |
statusrequired | string | One of pending, running, succeeded, failed, cancelled |
steprequired | string | Machine name of the current step, e.g. create_disk or transfer_cross_zone. |
step_indexrequired | integer | |
step_countrequired | integer | |
errorrequired | string | Empty unless the operation failed. |
created_atrequired | string (date-time) | |
started_atrequired | string (date-time) | null | |
finished_atrequired | string (date-time) | null | |
deadline_atrequired | string (date-time) | |
actor | string | Who asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations. |
progress | MigrationProgress | Present on GET /v1/operations/{id} while a server.migrate drives a live transfer. |
staterequired | string | One of reserved, detached, preparing, sending, switched, aborting |
source_node_idrequired | string | |
target_node_idrequired | string | |
phaserequired | string | How far the nodes report the current attempt.One of , preparing, transferring, completed, failed |
attemptrequired | integer | Which send this is under the convergence policy, from 1. |
iterationrequired | integer | Memory passes so far in the current attempt. |
transferred_bytesrequired | integer | |
total_bytesrequired | integer | 0 when the hypervisor does not report it. |
dirty_bytes_per_secondrequired | integer | |
downtime_millisecondsrequired | integer | The pause the guest took at handover, once completed. |
detailrequired | string | |
reported_atrequired | string (date-time) | null | The reporting node's clock. |
events | array of OperationEvent | Present on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first. |
atrequired | string (date-time) | |
kindrequired | string | For example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed. |
messagerequired | string | |
datarequired | object |
- 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.
- 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
curl -X DELETE 'https://cloud.ankra.app/v1/load-balancers/<id>' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Add a backend#
/v1/load-balancers/{id}/backends- Operation
create_load_balancer_backend- Credentials
- API token, Portal session
- Requires
- Permission
operate
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request bodyapplication/json
| Field | Type | Description |
|---|---|---|
namerequired | string | |
moderequired | string | One of tcp, http |
balance | string | One of roundrobin, leastconn, source |
health_check_path | string | Older form of an http health check of this path. |
health_check | LoadBalancerHealthCheckInput | Fields left out keep their value (on creation, the default of a TCP check every 2 s, rise 2, fall 3, path /, expected 200-399). |
type | string | One of tcp, http, none |
path | string | |
expected_status | string | |
interval_seconds | integer | |
rise | integer | |
fall | integer |
Responses
201The backend.application/json
| Field | Type | Description |
|---|---|---|
backendrequired | LoadBalancerBackend | |
idrequired | string | |
namerequired | string | |
moderequired | string | One of tcp, http |
balancerequired | string | One of roundrobin, leastconn, source |
health_check_pathrequired | string | The http check's path, empty for other checks. Kept for older clients; read health_check. |
health_checkrequired | LoadBalancerHealthCheck | |
typerequired | string | tcp connects to the member; http sends GET <path>; none never checks.One of tcp, http, none |
pathrequired | string | For http checks. |
expected_statusrequired | string | For http checks: 200, or a range such as 200-399. |
interval_secondsrequired | integer | |
riserequired | integer | Successes that bring a member back. |
fallrequired | integer | Failures that take a member out. |
membersrequired | array of LoadBalancerMember | |
idrequired | string | |
backend_idrequired | string | |
namerequired | string | |
addressrequired | string | An IPv4 or IPv6 address. |
portrequired | integer | |
weightrequired | integer | |
enabledrequired | boolean |
- 400The request is invalid;
detailsays 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_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.
- 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
curl -X POST 'https://cloud.ankra.app/v1/load-balancers/<id>/backends' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"name": "string",
"mode": "tcp"
}'Change how a backend balances and checks its members#
/v1/load-balancers/{id}/backends/{backend}- Operation
update_load_balancer_backend- Credentials
- API token, Portal session
- Requires
- Permission
operate
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
backendrequired | path | string |
Request bodyapplication/json
| Field | Type | Description |
|---|---|---|
balance | string | One of roundrobin, leastconn, source |
health_check | LoadBalancerHealthCheckInput | Fields left out keep their value (on creation, the default of a TCP check every 2 s, rise 2, fall 3, path /, expected 200-399). |
type | string | One of tcp, http, none |
path | string | |
expected_status | string | |
interval_seconds | integer | |
rise | integer | |
fall | integer |
Responses
200The backend.application/json
| Field | Type | Description |
|---|---|---|
backendrequired | LoadBalancerBackend | |
idrequired | string | |
namerequired | string | |
moderequired | string | One of tcp, http |
balancerequired | string | One of roundrobin, leastconn, source |
health_check_pathrequired | string | The http check's path, empty for other checks. Kept for older clients; read health_check. |
health_checkrequired | LoadBalancerHealthCheck | |
typerequired | string | tcp connects to the member; http sends GET <path>; none never checks.One of tcp, http, none |
pathrequired | string | For http checks. |
expected_statusrequired | string | For http checks: 200, or a range such as 200-399. |
interval_secondsrequired | integer | |
riserequired | integer | Successes that bring a member back. |
fallrequired | integer | Failures that take a member out. |
membersrequired | array of LoadBalancerMember | |
idrequired | string | |
backend_idrequired | string | |
namerequired | string | |
addressrequired | string | An IPv4 or IPv6 address. |
portrequired | integer | |
weightrequired | integer | |
enabledrequired | boolean |
- 400The request is invalid;
detailsays 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_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.
- 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
curl -X PATCH 'https://cloud.ankra.app/v1/load-balancers/<id>/backends/<backend>' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"balance": "roundrobin",
"health_check": {
"type": "tcp",
"path": "string",
"expected_status": "string",
"interval_seconds": 1,
"rise": 1,
"fall": 1
}
}'Remove a backend and its members#
/v1/load-balancers/{id}/backends/{backend}- Operation
delete_load_balancer_backend- Credentials
- API token, Portal session
- Requires
- Permission
operate
409 while a frontend forwards to it.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
backendrequired | path | string |
Responses
204Removed.
- 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.
- 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
curl -X DELETE 'https://cloud.ankra.app/v1/load-balancers/<id>/backends/<backend>' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Replace a backend's whole member list at once#
/v1/load-balancers/{id}/backends/{backend}/members- Operation
replace_load_balancer_members- Credentials
- API token, Portal session
- Requires
- Permission
operate
The list becomes the backend's members in one configuration change (one configuration generation), so HAProxy never serves a half-replaced backend: members missing from it leave, new ones join, and a member named again keeps its id and takes the new address, port, weight and state. An empty list empties the backend; a list equal to the current one changes nothing. Members follow the add-member rules (IPv4 host of the network, its ULA /64 or a global IPv6 address); names are unique within the list; at most 256 members.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
backendrequired | path | string |
Request bodyapplication/json
| Field | Type | Description |
|---|---|---|
membersrequired | array of object | |
namerequired | string | |
addressrequired | string | An IPv4 or IPv6 address. |
portrequired | integer | |
weight | integer | |
enabled | boolean |
Responses
200The backend's members after the replacement.application/json
| Field | Type | Description |
|---|---|---|
membersrequired | array of LoadBalancerMember | |
idrequired | string | |
backend_idrequired | string | |
namerequired | string | |
addressrequired | string | An IPv4 or IPv6 address. |
portrequired | integer | |
weightrequired | integer | |
enabledrequired | boolean |
- 400The request is invalid;
detailsays 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_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.
- 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
curl -X PUT 'https://cloud.ankra.app/v1/load-balancers/<id>/backends/<backend>/members' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"members": [
{
"name": "string",
"address": "10.0.0.20",
"port": 1
}
]
}'Add a member to a backend#
/v1/load-balancers/{id}/backends/{backend}/members- Operation
create_load_balancer_member- Credentials
- API token, Portal session
- Requires
- Permission
operate
A member is IPv4 or IPv6: an IPv4 host of the load balancer's private network, an address of that network's
ULA /64 (a server's leg address6) or a global IPv6 address (a server's public_ipv6). 400 for anything else.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
backendrequired | path | string |
Request bodyapplication/json
| Field | Type | Description |
|---|---|---|
namerequired | string | |
addressrequired | string | An IPv4 or IPv6 address. |
portrequired | integer | |
weight | integer | |
enabled | boolean |
Responses
201The member.application/json
| Field | Type | Description |
|---|---|---|
memberrequired | LoadBalancerMember | |
idrequired | string | |
backend_idrequired | string | |
namerequired | string | |
addressrequired | string | An IPv4 or IPv6 address. |
portrequired | integer | |
weightrequired | integer | |
enabledrequired | boolean |
- 400The request is invalid;
detailsays 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_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.
- 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
curl -X POST 'https://cloud.ankra.app/v1/load-balancers/<id>/backends/<backend>/members' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"name": "string",
"address": "10.0.0.20",
"port": 1
}'Change a member's weight or take it out of rotation#
/v1/load-balancers/{id}/backends/{backend}/members/{member}- Operation
update_load_balancer_member- Credentials
- API token, Portal session
- Requires
- Permission
operate
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
backendrequired | path | string | |
memberrequired | path | string |
Request bodyapplication/json
| Field | Type | Description |
|---|---|---|
weight | integer | |
enabled | boolean |
Responses
200The member.application/json
| Field | Type | Description |
|---|---|---|
memberrequired | LoadBalancerMember | |
idrequired | string | |
backend_idrequired | string | |
namerequired | string | |
addressrequired | string | An IPv4 or IPv6 address. |
portrequired | integer | |
weightrequired | integer | |
enabledrequired | boolean |
- 400The request is invalid;
detailsays 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_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.
- 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
curl -X PATCH 'https://cloud.ankra.app/v1/load-balancers/<id>/backends/<backend>/members/<member>' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"weight": 0,
"enabled": false
}'Remove a member from its backend#
/v1/load-balancers/{id}/backends/{backend}/members/{member}- Operation
delete_load_balancer_member- Credentials
- API token, Portal session
- Requires
- Permission
operate
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
backendrequired | path | string | |
memberrequired | path | string |
Responses
204Removed.
- 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.
- 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
curl -X DELETE 'https://cloud.ankra.app/v1/load-balancers/<id>/backends/<backend>/members/<member>' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Listen on a port and forward to a backend#
/v1/load-balancers/{id}/frontends- Operation
create_load_balancer_frontend- Credentials
- API token, Portal session
- Requires
- Permission
operate
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request bodyapplication/json
| Field | Type | Description |
|---|---|---|
namerequired | string | |
portrequired | integer | |
backend_idrequired | string | |
tls | boolean | Terminate TLS; needs certificate_ids. |
certificate_ids | array of string | Certificates of the account; the first answers clients without SNI. A load balancer uses at most 16. |
redirect_to_https | boolean | Only on a plain frontend of an http backend. |
Responses
201The frontend.application/json
| Field | Type | Description |
|---|---|---|
frontendrequired | LoadBalancerFrontend | |
idrequired | string | |
namerequired | string | |
portrequired | integer | |
moderequired | string | The mode of its backend.One of tcp, http |
backend_idrequired | string | |
tlsrequired | boolean | Terminates TLS with its certificates. |
certificate_idsrequired | array of string | The first answers clients that send no server name; the others are chosen by SNI. |
redirect_to_httpsrequired | boolean | Answers every request with a 301 to https on the same host. |
- 400The request is invalid;
detailsays 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_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.
- 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
curl -X POST 'https://cloud.ankra.app/v1/load-balancers/<id>/frontends' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"name": "string",
"port": 1,
"backend_id": "string"
}'Stop listening on a frontend's port#
/v1/load-balancers/{id}/frontends/{frontend}- Operation
delete_load_balancer_frontend- Credentials
- API token, Portal session
- Requires
- Permission
operate
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
frontendrequired | path | string |
Responses
204Removed.
- 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.
- 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
curl -X DELETE 'https://cloud.ankra.app/v1/load-balancers/<id>/frontends/<frontend>' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"List the certificates the control plane obtains and renews from Let's Encrypt#
/v1/load-balancers/acme-certificates- Operation
list_load_balancer_acme_certificates- Credentials
- API token, Portal session
- Requires
- Permission
read
Keyset-paginated, newest first: limit is 1 to 100 (default 50) and next_cursor is null on the last page; pass it back as cursor for the next one. A malformed cursor or a limit out of range is a 400.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
cursor | query | string | The next_cursor of the previous page. |
limit | query | integer | Page size; the server applies its default and maximum. |
Responses
200A page of ACME certificates, newest first.application/json
| Field | Type | Description |
|---|---|---|
itemsrequired | array of LoadBalancerACMECertificate | |
idrequired | string | |
namerequired | string | |
domainsrequired | array of string | |
load_balancer_idrequired | string | The load balancer that answers the HTTP-01 challenges on port 80. |
staterequired | string | pending waits for its first order, validating has an open order, issued has a certificate (renewals keep it served), failed never obtained one and retries at next_attempt_at.One of pending, validating, issued, failed |
last_errorrequired | string | Why the last order failed; empty after a success. |
next_attempt_atrequired | string (date-time) | When the next order starts; the renewal time once issued. |
not_beforerequired | string (date-time) | null | |
not_afterrequired | string (date-time) | null | |
frontend_countrequired | integer | Frontends that terminate TLS with it. |
created_atrequired | string (date-time) | |
next_cursorrequired | string | null | Pass as ?cursor= for the next page; null on the last page. |
- 400The request is invalid;
detailsays 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_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/load-balancers/acme-certificates' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Request a certificate the control plane obtains and renews from Let's Encrypt#
/v1/load-balancers/acme-certificates- Operation
create_load_balancer_acme_certificate- Credentials
- API token, Portal session
- Requires
- Permission
operate
The control plane orders the certificate at once and renews it two thirds into its lifetime. The domains (1 to 10 DNS names, no wildcards) must resolve to the named load balancer: its HAProxy answers the HTTP-01 challenges on port 80, in its plain HTTP frontend on that port or, without one, in a frontend of its own that answers nothing else. A TCP or TLS frontend on port 80 is a 400. Once issued, the certificate of the same id is listed with the account's certificates and frontends name it like an uploaded one; every renewal moves the load balancers using it to a new configuration. 503 when the control plane cannot obtain ACME certificates or has no secret key; an account holds at most 50 ACME certificates.
Request bodyapplication/json
| Field | Type | Description |
|---|---|---|
namerequired | string | |
domainsrequired | array of string | |
load_balancer_idrequired | string | The load balancer the domains resolve to, which answers the challenges. |
Responses
201The ACME certificate, pending its first order.application/json
| Field | Type | Description |
|---|---|---|
acme_certificaterequired | LoadBalancerACMECertificate | A certificate the control plane obtains and renews from Let's Encrypt. Once issued it is also a LoadBalancerCertificate with the same id. |
idrequired | string | |
namerequired | string | |
domainsrequired | array of string | |
load_balancer_idrequired | string | The load balancer that answers the HTTP-01 challenges on port 80. |
staterequired | string | pending waits for its first order, validating has an open order, issued has a certificate (renewals keep it served), failed never obtained one and retries at next_attempt_at.One of pending, validating, issued, failed |
last_errorrequired | string | Why the last order failed; empty after a success. |
next_attempt_atrequired | string (date-time) | When the next order starts; the renewal time once issued. |
not_beforerequired | string (date-time) | null | |
not_afterrequired | string (date-time) | null | |
frontend_countrequired | integer | Frontends that terminate TLS with it. |
created_atrequired | string (date-time) |
- 400The request is invalid;
detailsays 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_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.
- 409The resource's state does not allow this now.
- 422The account would exceed a quota;
detailnames the limit andreasonisquota_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 indetail), or a host did not answer; try another plan or zone, or try again later. - defaultAny other error, usually 500.
Example
curl -X POST 'https://cloud.ankra.app/v1/load-balancers/acme-certificates' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"name": "string",
"domains": [
"string"
],
"load_balancer_id": "string"
}'Get an ACME certificate and the state of its order#
/v1/load-balancers/acme-certificates/{certificate}- Operation
get_load_balancer_acme_certificate- Credentials
- API token, Portal session
- Requires
- Permission
read
Parameters
| Name | In | Type | Description |
|---|---|---|---|
certificaterequired | path | string |
Responses
200The ACME certificate.application/json
| Field | Type | Description |
|---|---|---|
acme_certificaterequired | LoadBalancerACMECertificate | A certificate the control plane obtains and renews from Let's Encrypt. Once issued it is also a LoadBalancerCertificate with the same id. |
idrequired | string | |
namerequired | string | |
domainsrequired | array of string | |
load_balancer_idrequired | string | The load balancer that answers the HTTP-01 challenges on port 80. |
staterequired | string | pending waits for its first order, validating has an open order, issued has a certificate (renewals keep it served), failed never obtained one and retries at next_attempt_at.One of pending, validating, issued, failed |
last_errorrequired | string | Why the last order failed; empty after a success. |
next_attempt_atrequired | string (date-time) | When the next order starts; the renewal time once issued. |
not_beforerequired | string (date-time) | null | |
not_afterrequired | string (date-time) | null | |
frontend_countrequired | integer | Frontends that terminate TLS with it. |
created_atrequired | string (date-time) |
- 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_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/load-balancers/acme-certificates/<certificate>' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Stop renewing an ACME certificate and delete it with its sealed key#
/v1/load-balancers/acme-certificates/{certificate}- Operation
delete_load_balancer_acme_certificate- Credentials
- API token, Portal session
- Requires
- Permission
operate
409 while a frontend terminates TLS with it.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
certificaterequired | path | string |
Responses
204Deleted.
- 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.
- 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
curl -X DELETE 'https://cloud.ankra.app/v1/load-balancers/acme-certificates/<certificate>' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"List the account's load balancer certificates#
/v1/load-balancers/certificates- Operation
list_load_balancer_certificates- Credentials
- API token, Portal session
- Requires
- Permission
read
Keyset-paginated, newest first: limit is 1 to 100 (default 50) and next_cursor is null on the last page; pass it back as cursor for the next one. A malformed cursor or a limit out of range is a 400.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
cursor | query | string | The next_cursor of the previous page. |
limit | query | integer | Page size; the server applies its default and maximum. |
Responses
200A page of certificates, newest first.application/json
| Field | Type | Description |
|---|---|---|
itemsrequired | array of LoadBalancerCertificate | |
idrequired | string | |
namerequired | string | |
common_namerequired | string | |
dns_namesrequired | array of string | |
not_beforerequired | string (date-time) | |
not_afterrequired | string (date-time) | |
fingerprint_sha256required | string | Lowercase hex SHA-256 of the leaf certificate. |
frontend_countrequired | integer | Frontends that terminate TLS with it. |
created_atrequired | string (date-time) | |
next_cursorrequired | string | null | Pass as ?cursor= for the next page; null on the last page. |
- 400The request is invalid;
detailsays 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_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/load-balancers/certificates' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Upload a certificate chain and its private key#
/v1/load-balancers/certificates- Operation
create_load_balancer_certificate- Credentials
- API token, Portal session
- Requires
- Permission
operate
The chain (leaf first) and an unencrypted private key (PKCS #8, PKCS #1 or SEC 1; RSA of at least 2048 bits, ECDSA or Ed25519), both PEM. The key must belong to the leaf. It is sealed with the control plane's secret key and only ever leaves it inside a configuration pushed to a load balancer VM. 503 when the control plane has no secret key; an account holds at most 100 certificates.
Request bodyapplication/json
| Field | Type | Description |
|---|---|---|
namerequired | string | |
certificaterequired | string | |
private_keyrequired | string |
Responses
201The certificate, without its key.application/json
| Field | Type | Description |
|---|---|---|
certificaterequired | LoadBalancerCertificate | A certificate chain the account's load balancers terminate TLS with. Its private key is sealed at rest and never returned. |
idrequired | string | |
namerequired | string | |
common_namerequired | string | |
dns_namesrequired | array of string | |
not_beforerequired | string (date-time) | |
not_afterrequired | string (date-time) | |
fingerprint_sha256required | string | Lowercase hex SHA-256 of the leaf certificate. |
frontend_countrequired | integer | Frontends that terminate TLS with it. |
created_atrequired | string (date-time) |
- 400The request is invalid;
detailsays 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_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). - 409The resource's state does not allow this now.
- 422The account would exceed a quota;
detailnames the limit andreasonisquota_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 indetail), or a host did not answer; try another plan or zone, or try again later. - defaultAny other error, usually 500.
Example
curl -X POST 'https://cloud.ankra.app/v1/load-balancers/certificates' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"name": "string",
"certificate": "string",
"private_key": "string"
}'Get a certificate#
/v1/load-balancers/certificates/{certificate}- Operation
get_load_balancer_certificate- Credentials
- API token, Portal session
- Requires
- Permission
read
Parameters
| Name | In | Type | Description |
|---|---|---|---|
certificaterequired | path | string |
Responses
200The certificate, without its key.application/json
| Field | Type | Description |
|---|---|---|
certificaterequired | LoadBalancerCertificate | A certificate chain the account's load balancers terminate TLS with. Its private key is sealed at rest and never returned. |
idrequired | string | |
namerequired | string | |
common_namerequired | string | |
dns_namesrequired | array of string | |
not_beforerequired | string (date-time) | |
not_afterrequired | string (date-time) | |
fingerprint_sha256required | string | Lowercase hex SHA-256 of the leaf certificate. |
frontend_countrequired | integer | Frontends that terminate TLS with it. |
created_atrequired | string (date-time) |
- 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_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/load-balancers/certificates/<certificate>' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Delete a certificate and its sealed key#
/v1/load-balancers/certificates/{certificate}- Operation
delete_load_balancer_certificate- Credentials
- API token, Portal session
- Requires
- Permission
operate
409 while a frontend terminates TLS with it.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
certificaterequired | path | string |
Responses
204Deleted.
- 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.
- 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
curl -X DELETE 'https://cloud.ankra.app/v1/load-balancers/certificates/<certificate>' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"