API reference · Networking

Load balancers

18 operations of the Ankra Cloud API: Managed load balancers and their certificates.

List load balancers#

GET/v1/load-balancers

Operation: list_load_balancers
Credentials: API token, Portal session
Requires: Permission read

Without nodes, frontends and backends; get one for those.

Parameters

Parameters
Name	In	Type	Description
`label`	query	array of string	`key=value`; repeat to require several labels. Only load balancers carrying every label are listed.

Responses

200Every load balancer that matches (next_cursor is always null).application/json

200 response fields
Field	Type	Description
`items`required	array of LoadBalancer
`id`required	string
`zone`required	string
`region`	string	The region of the load balancer's zone.
`name`required	string
`network_id`required	string
`state`required	string	One of `creating`, `running`, `error`, `deleting`
`labels`required	Labels	Keys of 1-63 letters, digits, `.`, `_`, `/` or `-`, starting and ending with a letter or digit; values of at most 255 printable characters.
`high_availability`required	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_ipv4`required	string \| null	The floating IPv4 frontend address (the add-on); null without the add-on or until allocated.
`public_ipv6`required	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_addresses`required	array of string	Every VM's IPv6 frontend address, in VM order; each VM serves every frontend on its own.
`address`required	string \| null	The public IPv4 address, the same as public_ipv4 (kept for older clients); null without the IPv4 add-on or until allocated.
`configuration_generation`required	integer
`is_configuration_applied`required	boolean
`nodes`required	array of object
`id`required	string
`name`required	string
`state`required	string
`is_active`required	boolean	The VM that holds the load balancer's address (the active member of the pair's failover), as its guest last reported.
`is_healthy`required	boolean
`health_detail`required	string
`is_configuration_applied`required	boolean
`frontends`required	array of LoadBalancerFrontend
`id`required	string
`name`required	string
`port`required	integer
`mode`required	string	The mode of its backend.One of `tcp`, `http`
`backend_id`required	string
`tls`required	boolean	Terminates TLS with its certificates.
`certificate_ids`required	array of string	The first answers clients that send no server name; the others are chosen by SNI.
`redirect_to_https`required	boolean	Answers every request with a 301 to https on the same host.
`backends`required	array of LoadBalancerBackend
`id`required	string
`name`required	string
`mode`required	string	One of `tcp`, `http`
`balance`required	string	One of `roundrobin`, `leastconn`, `source`
`health_check_path`required	string	The http check's path, empty for other checks. Kept for older clients; read health_check.
`health_check`required	LoadBalancerHealthCheck
`type`required	string	tcp connects to the member; http sends GET <path>; none never checks.One of `tcp`, `http`, `none`
`path`required	string	For http checks.
`expected_status`required	string	For http checks: 200, or a range such as 200-399.
`interval_seconds`required	integer
`rise`required	integer	Successes that bring a member back.
`fall`required	integer	Failures that take a member out.
`members`required	array of LoadBalancerMember
`id`required	string
`backend_id`required	string
`name`required	string
`address`required	string	An IPv4 or IPv6 address.
`port`required	integer
`weight`required	integer
`enabled`required	boolean
`active_operation`required	Operation \| null
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	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.
`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.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	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.
`state`required	string	One of `reserved`, `detached`, `preparing`, `sending`, `switched`, `aborting`
`source_node_id`required	string
`target_node_id`required	string
`phase`required	string	How far the nodes report the current attempt.One of , `preparing`, `transferring`, `completed`, `failed`
`attempt`required	integer	Which send this is under the convergence policy, from 1.
`iteration`required	integer	Memory passes so far in the current attempt.
`transferred_bytes`required	integer
`total_bytes`required	integer	0 when the hypervisor does not report it.
`dirty_bytes_per_second`required	integer
`downtime_milliseconds`required	integer	The pause the guest took at handover, once completed.
`detail`required	string
`reported_at`required	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.
`at`required	string (date-time)
`kind`required	string	For example `target_chosen`, `send_started`, `handed_over`, `undoing`, `cold_fallback`, `move_cancelled`, `recovery_started`, `succeeded`, `failed`.
`message`required	string
`data`required	object
`created_at`required	string (date-time)
`next_cursor`required	null

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

Example

bash

curl 'https://cloud.ankra.app/v1/load-balancers' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Create a load balancer on a private network#

POST/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. public_ipv4 (default true) adds a floating IPv4 frontend address, the paid add-on.

Price per month: €4.50 per VM plus €3 for the IPv4 add-on, so €12 for a pair with IPv4 (as before), €9 for a pair without, €7.50 for one VM with IPv4 and €4.50 for one VM without. An account may hold 5.

Request bodyapplication/json

Request body fields
Field	Type	Description
`zone`required	string
`name`required	string
`network_id`required	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.
`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. IPv6 is always on.
`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

202 response fields
Field	Type	Description
`load_balancer`required	LoadBalancer
`id`required	string
`zone`required	string
`region`	string	The region of the load balancer's zone.
`name`required	string
`network_id`required	string
`state`required	string	One of `creating`, `running`, `error`, `deleting`
`labels`required	Labels	Keys of 1-63 letters, digits, `.`, `_`, `/` or `-`, starting and ending with a letter or digit; values of at most 255 printable characters.
`high_availability`required	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_ipv4`required	string \| null	The floating IPv4 frontend address (the add-on); null without the add-on or until allocated.
`public_ipv6`required	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_addresses`required	array of string	Every VM's IPv6 frontend address, in VM order; each VM serves every frontend on its own.
`address`required	string \| null	The public IPv4 address, the same as public_ipv4 (kept for older clients); null without the IPv4 add-on or until allocated.
`configuration_generation`required	integer
`is_configuration_applied`required	boolean
`nodes`required	array of object
`id`required	string
`name`required	string
`state`required	string
`is_active`required	boolean	The VM that holds the load balancer's address (the active member of the pair's failover), as its guest last reported.
`is_healthy`required	boolean
`health_detail`required	string
`is_configuration_applied`required	boolean
`frontends`required	array of LoadBalancerFrontend
`id`required	string
`name`required	string
`port`required	integer
`mode`required	string	The mode of its backend.One of `tcp`, `http`
`backend_id`required	string
`tls`required	boolean	Terminates TLS with its certificates.
`certificate_ids`required	array of string	The first answers clients that send no server name; the others are chosen by SNI.
`redirect_to_https`required	boolean	Answers every request with a 301 to https on the same host.
`backends`required	array of LoadBalancerBackend
`id`required	string
`name`required	string
`mode`required	string	One of `tcp`, `http`
`balance`required	string	One of `roundrobin`, `leastconn`, `source`
`health_check_path`required	string	The http check's path, empty for other checks. Kept for older clients; read health_check.
`health_check`required	LoadBalancerHealthCheck
`type`required	string	tcp connects to the member; http sends GET <path>; none never checks.One of `tcp`, `http`, `none`
`path`required	string	For http checks.
`expected_status`required	string	For http checks: 200, or a range such as 200-399.
`interval_seconds`required	integer
`rise`required	integer	Successes that bring a member back.
`fall`required	integer	Failures that take a member out.
`members`required	array of LoadBalancerMember
`id`required	string
`backend_id`required	string
`name`required	string
`address`required	string	An IPv4 or IPv6 address.
`port`required	integer
`weight`required	integer
`enabled`required	boolean
`active_operation`required	Operation \| null
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	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.
`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.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	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.
`state`required	string	One of `reserved`, `detached`, `preparing`, `sending`, `switched`, `aborting`
`source_node_id`required	string
`target_node_id`required	string
`phase`required	string	How far the nodes report the current attempt.One of , `preparing`, `transferring`, `completed`, `failed`
`attempt`required	integer	Which send this is under the convergence policy, from 1.
`iteration`required	integer	Memory passes so far in the current attempt.
`transferred_bytes`required	integer
`total_bytes`required	integer	0 when the hypervisor does not report it.
`dirty_bytes_per_second`required	integer
`downtime_milliseconds`required	integer	The pause the guest took at handover, once completed.
`detail`required	string
`reported_at`required	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.
`at`required	string (date-time)
`kind`required	string	For example `target_chosen`, `send_started`, `handed_over`, `undoing`, `cold_fallback`, `move_cancelled`, `recovery_started`, `succeeded`, `failed`.
`message`required	string
`data`required	object
`created_at`required	string (date-time)
`operation`required	Operation
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	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.
`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.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	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.
`state`required	string	One of `reserved`, `detached`, `preparing`, `sending`, `switched`, `aborting`
`source_node_id`required	string
`target_node_id`required	string
`phase`required	string	How far the nodes report the current attempt.One of , `preparing`, `transferring`, `completed`, `failed`
`attempt`required	integer	Which send this is under the convergence policy, from 1.
`iteration`required	integer	Memory passes so far in the current attempt.
`transferred_bytes`required	integer
`total_bytes`required	integer	0 when the hypervisor does not report it.
`dirty_bytes_per_second`required	integer
`downtime_milliseconds`required	integer	The pause the guest took at handover, once completed.
`detail`required	string
`reported_at`required	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.
`at`required	string (date-time)
`kind`required	string	For example `target_chosen`, `send_started`, `handed_over`, `undoing`, `cold_fallback`, `move_cancelled`, `recovery_started`, `succeeded`, `failed`.
`message`required	string
`data`required	object

400The request is invalid; detail says why.
401Not signed in, or the credential is invalid or expired.
402The account may not create billable resources. reason is payment_method_required while it has neither a default payment method nor a live credit (add one through POST /v1/account/billing/setup-session or redeem a coupon), or account_suspended while an invoice is overdue past the grace period (pay it; nothing already running is stopped) or Ankra staff suspended the account (contact support). GET /v1/account/billing reports the same standing.
403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
404No such resource in the caller's account.
409The resource's state does not allow this now.
422The account would exceed a quota; detail names the limit.
503No capacity or address is free, or a host did not answer; try again later.
defaultAny other error, usually 500.

Example

bash

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#

GET/v1/load-balancers/{id}

Operation: get_load_balancer
Credentials: API token, Portal session
Requires: Permission read

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Responses

200The load balancer.application/json

200 response fields
Field	Type	Description
`load_balancer`required	LoadBalancer
`id`required	string
`zone`required	string
`region`	string	The region of the load balancer's zone.
`name`required	string
`network_id`required	string
`state`required	string	One of `creating`, `running`, `error`, `deleting`
`labels`required	Labels	Keys of 1-63 letters, digits, `.`, `_`, `/` or `-`, starting and ending with a letter or digit; values of at most 255 printable characters.
`high_availability`required	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_ipv4`required	string \| null	The floating IPv4 frontend address (the add-on); null without the add-on or until allocated.
`public_ipv6`required	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_addresses`required	array of string	Every VM's IPv6 frontend address, in VM order; each VM serves every frontend on its own.
`address`required	string \| null	The public IPv4 address, the same as public_ipv4 (kept for older clients); null without the IPv4 add-on or until allocated.
`configuration_generation`required	integer
`is_configuration_applied`required	boolean
`nodes`required	array of object
`id`required	string
`name`required	string
`state`required	string
`is_active`required	boolean	The VM that holds the load balancer's address (the active member of the pair's failover), as its guest last reported.
`is_healthy`required	boolean
`health_detail`required	string
`is_configuration_applied`required	boolean
`frontends`required	array of LoadBalancerFrontend
`id`required	string
`name`required	string
`port`required	integer
`mode`required	string	The mode of its backend.One of `tcp`, `http`
`backend_id`required	string
`tls`required	boolean	Terminates TLS with its certificates.
`certificate_ids`required	array of string	The first answers clients that send no server name; the others are chosen by SNI.
`redirect_to_https`required	boolean	Answers every request with a 301 to https on the same host.
`backends`required	array of LoadBalancerBackend
`id`required	string
`name`required	string
`mode`required	string	One of `tcp`, `http`
`balance`required	string	One of `roundrobin`, `leastconn`, `source`
`health_check_path`required	string	The http check's path, empty for other checks. Kept for older clients; read health_check.
`health_check`required	LoadBalancerHealthCheck
`type`required	string	tcp connects to the member; http sends GET <path>; none never checks.One of `tcp`, `http`, `none`
`path`required	string	For http checks.
`expected_status`required	string	For http checks: 200, or a range such as 200-399.
`interval_seconds`required	integer
`rise`required	integer	Successes that bring a member back.
`fall`required	integer	Failures that take a member out.
`members`required	array of LoadBalancerMember
`id`required	string
`backend_id`required	string
`name`required	string
`address`required	string	An IPv4 or IPv6 address.
`port`required	integer
`weight`required	integer
`enabled`required	boolean
`active_operation`required	Operation \| null
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	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.
`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.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	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.
`state`required	string	One of `reserved`, `detached`, `preparing`, `sending`, `switched`, `aborting`
`source_node_id`required	string
`target_node_id`required	string
`phase`required	string	How far the nodes report the current attempt.One of , `preparing`, `transferring`, `completed`, `failed`
`attempt`required	integer	Which send this is under the convergence policy, from 1.
`iteration`required	integer	Memory passes so far in the current attempt.
`transferred_bytes`required	integer
`total_bytes`required	integer	0 when the hypervisor does not report it.
`dirty_bytes_per_second`required	integer
`downtime_milliseconds`required	integer	The pause the guest took at handover, once completed.
`detail`required	string
`reported_at`required	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.
`at`required	string (date-time)
`kind`required	string	For example `target_chosen`, `send_started`, `handed_over`, `undoing`, `cold_fallback`, `move_cancelled`, `recovery_started`, `succeeded`, `failed`.
`message`required	string
`data`required	object
`created_at`required	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_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
404No such resource in the caller's account.
defaultAny other error, usually 500.

Example

bash

curl 'https://cloud.ankra.app/v1/load-balancers/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Rename a load balancer or replace its labels#

PATCH/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

Parameters
Name	In	Type	Description
`id`required	path	string

Request bodyapplication/json

Request body fields
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.

Responses

200The load balancer, described in full.application/json

200 response fields
Field	Type	Description
`load_balancer`required	LoadBalancer
`id`required	string
`zone`required	string
`region`	string	The region of the load balancer's zone.
`name`required	string
`network_id`required	string
`state`required	string	One of `creating`, `running`, `error`, `deleting`
`labels`required	Labels	Keys of 1-63 letters, digits, `.`, `_`, `/` or `-`, starting and ending with a letter or digit; values of at most 255 printable characters.
`high_availability`required	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_ipv4`required	string \| null	The floating IPv4 frontend address (the add-on); null without the add-on or until allocated.
`public_ipv6`required	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_addresses`required	array of string	Every VM's IPv6 frontend address, in VM order; each VM serves every frontend on its own.
`address`required	string \| null	The public IPv4 address, the same as public_ipv4 (kept for older clients); null without the IPv4 add-on or until allocated.
`configuration_generation`required	integer
`is_configuration_applied`required	boolean
`nodes`required	array of object
`id`required	string
`name`required	string
`state`required	string
`is_active`required	boolean	The VM that holds the load balancer's address (the active member of the pair's failover), as its guest last reported.
`is_healthy`required	boolean
`health_detail`required	string
`is_configuration_applied`required	boolean
`frontends`required	array of LoadBalancerFrontend
`id`required	string
`name`required	string
`port`required	integer
`mode`required	string	The mode of its backend.One of `tcp`, `http`
`backend_id`required	string
`tls`required	boolean	Terminates TLS with its certificates.
`certificate_ids`required	array of string	The first answers clients that send no server name; the others are chosen by SNI.
`redirect_to_https`required	boolean	Answers every request with a 301 to https on the same host.
`backends`required	array of LoadBalancerBackend
`id`required	string
`name`required	string
`mode`required	string	One of `tcp`, `http`
`balance`required	string	One of `roundrobin`, `leastconn`, `source`
`health_check_path`required	string	The http check's path, empty for other checks. Kept for older clients; read health_check.
`health_check`required	LoadBalancerHealthCheck
`type`required	string	tcp connects to the member; http sends GET <path>; none never checks.One of `tcp`, `http`, `none`
`path`required	string	For http checks.
`expected_status`required	string	For http checks: 200, or a range such as 200-399.
`interval_seconds`required	integer
`rise`required	integer	Successes that bring a member back.
`fall`required	integer	Failures that take a member out.
`members`required	array of LoadBalancerMember
`id`required	string
`backend_id`required	string
`name`required	string
`address`required	string	An IPv4 or IPv6 address.
`port`required	integer
`weight`required	integer
`enabled`required	boolean
`active_operation`required	Operation \| null
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	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.
`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.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	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.
`state`required	string	One of `reserved`, `detached`, `preparing`, `sending`, `switched`, `aborting`
`source_node_id`required	string
`target_node_id`required	string
`phase`required	string	How far the nodes report the current attempt.One of , `preparing`, `transferring`, `completed`, `failed`
`attempt`required	integer	Which send this is under the convergence policy, from 1.
`iteration`required	integer	Memory passes so far in the current attempt.
`transferred_bytes`required	integer
`total_bytes`required	integer	0 when the hypervisor does not report it.
`dirty_bytes_per_second`required	integer
`downtime_milliseconds`required	integer	The pause the guest took at handover, once completed.
`detail`required	string
`reported_at`required	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.
`at`required	string (date-time)
`kind`required	string	For example `target_chosen`, `send_started`, `handed_over`, `undoing`, `cold_fallback`, `move_cancelled`, `recovery_started`, `succeeded`, `failed`.
`message`required	string
`data`required	object
`created_at`required	string (date-time)

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

Example

bash

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#

DELETE/v1/load-balancers/{id}

Operation: delete_load_balancer
Credentials: API token, Portal session
Requires: Permission operate

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Responses

202Accepted; poll the operation.application/json · OperationEnvelope

202 response fields
Field	Type	Description
`operation`required	Operation
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	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.
`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.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	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.
`state`required	string	One of `reserved`, `detached`, `preparing`, `sending`, `switched`, `aborting`
`source_node_id`required	string
`target_node_id`required	string
`phase`required	string	How far the nodes report the current attempt.One of , `preparing`, `transferring`, `completed`, `failed`
`attempt`required	integer	Which send this is under the convergence policy, from 1.
`iteration`required	integer	Memory passes so far in the current attempt.
`transferred_bytes`required	integer
`total_bytes`required	integer	0 when the hypervisor does not report it.
`dirty_bytes_per_second`required	integer
`downtime_milliseconds`required	integer	The pause the guest took at handover, once completed.
`detail`required	string
`reported_at`required	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.
`at`required	string (date-time)
`kind`required	string	For example `target_chosen`, `send_started`, `handed_over`, `undoing`, `cold_fallback`, `move_cancelled`, `recovery_started`, `succeeded`, `failed`.
`message`required	string
`data`required	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_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
404No such resource in the caller's account.
409The resource's state does not allow this now.
defaultAny other error, usually 500.

Example

bash

curl -X DELETE 'https://cloud.ankra.app/v1/load-balancers/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Add a backend#

POST/v1/load-balancers/{id}/backends

Operation: create_load_balancer_backend
Credentials: API token, Portal session
Requires: Permission operate

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Request bodyapplication/json

Request body fields
Field	Type	Description
`name`required	string
`mode`required	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

201 response fields
Field	Type	Description
`backend`required	LoadBalancerBackend
`id`required	string
`name`required	string
`mode`required	string	One of `tcp`, `http`
`balance`required	string	One of `roundrobin`, `leastconn`, `source`
`health_check_path`required	string	The http check's path, empty for other checks. Kept for older clients; read health_check.
`health_check`required	LoadBalancerHealthCheck
`type`required	string	tcp connects to the member; http sends GET <path>; none never checks.One of `tcp`, `http`, `none`
`path`required	string	For http checks.
`expected_status`required	string	For http checks: 200, or a range such as 200-399.
`interval_seconds`required	integer
`rise`required	integer	Successes that bring a member back.
`fall`required	integer	Failures that take a member out.
`members`required	array of LoadBalancerMember
`id`required	string
`backend_id`required	string
`name`required	string
`address`required	string	An IPv4 or IPv6 address.
`port`required	integer
`weight`required	integer
`enabled`required	boolean

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

Example

bash

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#

PATCH/v1/load-balancers/{id}/backends/{backend}

Operation: update_load_balancer_backend
Credentials: API token, Portal session
Requires: Permission operate

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string
`backend`required	path	string

Request bodyapplication/json

Request body fields
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

200 response fields
Field	Type	Description
`backend`required	LoadBalancerBackend
`id`required	string
`name`required	string
`mode`required	string	One of `tcp`, `http`
`balance`required	string	One of `roundrobin`, `leastconn`, `source`
`health_check_path`required	string	The http check's path, empty for other checks. Kept for older clients; read health_check.
`health_check`required	LoadBalancerHealthCheck
`type`required	string	tcp connects to the member; http sends GET <path>; none never checks.One of `tcp`, `http`, `none`
`path`required	string	For http checks.
`expected_status`required	string	For http checks: 200, or a range such as 200-399.
`interval_seconds`required	integer
`rise`required	integer	Successes that bring a member back.
`fall`required	integer	Failures that take a member out.
`members`required	array of LoadBalancerMember
`id`required	string
`backend_id`required	string
`name`required	string
`address`required	string	An IPv4 or IPv6 address.
`port`required	integer
`weight`required	integer
`enabled`required	boolean

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

Example

bash

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#

DELETE/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

Parameters
Name	In	Type	Description
`id`required	path	string
`backend`required	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_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
404No such resource in the caller's account.
409The resource's state does not allow this now.
defaultAny other error, usually 500.

Example

bash

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#

PUT/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

Parameters
Name	In	Type	Description
`id`required	path	string
`backend`required	path	string

Request bodyapplication/json

Request body fields
Field	Type	Description
`members`required	array of object
`name`required	string
`address`required	string	An IPv4 or IPv6 address.
`port`required	integer
`weight`	integer
`enabled`	boolean

Responses

200The backend's members after the replacement.application/json

200 response fields
Field	Type	Description
`members`required	array of LoadBalancerMember
`id`required	string
`backend_id`required	string
`name`required	string
`address`required	string	An IPv4 or IPv6 address.
`port`required	integer
`weight`required	integer
`enabled`required	boolean

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

Example

bash

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#

POST/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

Parameters
Name	In	Type	Description
`id`required	path	string
`backend`required	path	string

Request bodyapplication/json

Request body fields
Field	Type	Description
`name`required	string
`address`required	string	An IPv4 or IPv6 address.
`port`required	integer
`weight`	integer
`enabled`	boolean

Responses

201The member.application/json

201 response fields
Field	Type	Description
`member`required	LoadBalancerMember
`id`required	string
`backend_id`required	string
`name`required	string
`address`required	string	An IPv4 or IPv6 address.
`port`required	integer
`weight`required	integer
`enabled`required	boolean

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

Example

bash

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#

PATCH/v1/load-balancers/{id}/backends/{backend}/members/{member}

Operation: update_load_balancer_member
Credentials: API token, Portal session
Requires: Permission operate

Parameters

Parameters
Name	In	Type
`id`required	path	string
`backend`required	path	string
`member`required	path	string

Request bodyapplication/json

Request body fields
Field	Type	Description
`weight`	integer
`enabled`	boolean

Responses

200The member.application/json

200 response fields
Field	Type	Description
`member`required	LoadBalancerMember
`id`required	string
`backend_id`required	string
`name`required	string
`address`required	string	An IPv4 or IPv6 address.
`port`required	integer
`weight`required	integer
`enabled`required	boolean

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

Example

bash

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#

DELETE/v1/load-balancers/{id}/backends/{backend}/members/{member}

Operation: delete_load_balancer_member
Credentials: API token, Portal session
Requires: Permission operate

Parameters

Parameters
Name	In	Type
`id`required	path	string
`backend`required	path	string
`member`required	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_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
404No such resource in the caller's account.
409The resource's state does not allow this now.
defaultAny other error, usually 500.

Example

bash

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#

POST/v1/load-balancers/{id}/frontends

Operation: create_load_balancer_frontend
Credentials: API token, Portal session
Requires: Permission operate

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Request bodyapplication/json

Request body fields
Field	Type	Description
`name`required	string
`port`required	integer
`backend_id`required	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

201 response fields
Field	Type	Description
`frontend`required	LoadBalancerFrontend
`id`required	string
`name`required	string
`port`required	integer
`mode`required	string	The mode of its backend.One of `tcp`, `http`
`backend_id`required	string
`tls`required	boolean	Terminates TLS with its certificates.
`certificate_ids`required	array of string	The first answers clients that send no server name; the others are chosen by SNI.
`redirect_to_https`required	boolean	Answers every request with a 301 to https on the same host.

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

Example

bash

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#

DELETE/v1/load-balancers/{id}/frontends/{frontend}

Operation: delete_load_balancer_frontend
Credentials: API token, Portal session
Requires: Permission operate

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string
`frontend`required	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_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
404No such resource in the caller's account.
409The resource's state does not allow this now.
defaultAny other error, usually 500.

Example

bash

curl -X DELETE 'https://cloud.ankra.app/v1/load-balancers/<id>/frontends/<frontend>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

List the account's load balancer certificates#

GET/v1/load-balancers/certificates

Operation: list_load_balancer_certificates
Credentials: API token, Portal session
Requires: Permission read

Responses

200Every certificate, newest first (next_cursor is always null).application/json

200 response fields
Field	Type	Description
`items`required	array of LoadBalancerCertificate
`id`required	string
`name`required	string
`common_name`required	string
`dns_names`required	array of string
`not_before`required	string (date-time)
`not_after`required	string (date-time)
`fingerprint_sha256`required	string	Lowercase hex SHA-256 of the leaf certificate.
`frontend_count`required	integer	Frontends that terminate TLS with it.
`created_at`required	string (date-time)
`next_cursor`required	null

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

Example

bash

curl 'https://cloud.ankra.app/v1/load-balancers/certificates' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Upload a certificate chain and its private key#

POST/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

Request body fields
Field	Type	Description
`name`required	string
`certificate`required	string
`private_key`required	string

Responses

201The certificate, without its key.application/json

201 response fields
Field	Type	Description
`certificate`required	LoadBalancerCertificate	A certificate chain the account's load balancers terminate TLS with. Its private key is sealed at rest and never returned.
`id`required	string
`name`required	string
`common_name`required	string
`dns_names`required	array of string
`not_before`required	string (date-time)
`not_after`required	string (date-time)
`fingerprint_sha256`required	string	Lowercase hex SHA-256 of the leaf certificate.
`frontend_count`required	integer	Frontends that terminate TLS with it.
`created_at`required	string (date-time)

400The request is invalid; detail says why.
401Not signed in, or the credential is invalid or expired.
403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
409The resource's state does not allow this now.
422The account would exceed a quota; detail names the limit.
503No capacity or address is free, or a host did not answer; try again later.
defaultAny other error, usually 500.

Example

bash

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#

GET/v1/load-balancers/certificates/{certificate}

Operation: get_load_balancer_certificate
Credentials: API token, Portal session
Requires: Permission read

Parameters

Parameters
Name	In	Type	Description
`certificate`required	path	string

Responses

200The certificate, without its key.application/json

200 response fields
Field	Type	Description
`certificate`required	LoadBalancerCertificate	A certificate chain the account's load balancers terminate TLS with. Its private key is sealed at rest and never returned.
`id`required	string
`name`required	string
`common_name`required	string
`dns_names`required	array of string
`not_before`required	string (date-time)
`not_after`required	string (date-time)
`fingerprint_sha256`required	string	Lowercase hex SHA-256 of the leaf certificate.
`frontend_count`required	integer	Frontends that terminate TLS with it.
`created_at`required	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_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
404No such resource in the caller's account.
defaultAny other error, usually 500.

Example

bash

curl 'https://cloud.ankra.app/v1/load-balancers/certificates/<certificate>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Delete a certificate and its sealed key#

DELETE/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

Parameters
Name	In	Type	Description
`certificate`required	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_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
404No such resource in the caller's account.
409The resource's state does not allow this now.
defaultAny other error, usually 500.

Example

bash

curl -X DELETE 'https://cloud.ankra.app/v1/load-balancers/certificates/<certificate>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"