API reference · Networking

Network edges

5 operations of the Ankra Cloud API: Network edges - bastion, NAT64/DNS64 gateway and dual-stack load balancer roles.

List network edges#

GET/v1/edges

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

Without machines and members; get one for those.

Parameters

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 edges, newest first.application/json

200 response fields
Field	Type	Description
`items`required	array of Edge
`id`required	string
`zone`required	string
`name`required	string
`network_id`required	string
`roles`required	array of string	One of `bastion`, `nat_gateway`, `load_balancer`
`placement`required	string	One of `separate`, `combined`
`plan`required	string
`state`required	string	One of `creating`, `running`, `error`, `deleting`
`production_recommended`required	boolean	False for a combined edge.
`production_recommendation_reason`required	string \| null	Why a combined edge is not recommended for production.
`public_ipv4`required	string \| null	The IPv4 address to allow-list, point DNS at and SSH to (a combined edge's only one).
`bastion_jump_host`required	string \| null	`admin@<ipv4>`, for `ssh -J`.
`dns64_address`required	string \| null	The nat_gateway role's DNS64 resolver on the network's ULA /64.
`load_balancer_id`required	string \| null	The managed load balancer of a separate load_balancer role.
`ssh_key_count`required	integer
`configuration_generation`required	integer
`machines`required	array of object
`id`required	string
`name`required	string
`roles`required	array of string	One of `bastion`, `nat_gateway`, `load_balancer`
`state`required	string
`is_healthy`required	boolean
`health_detail`required	string
`public_ipv4`required	string \| null
`public_ipv6`required	string \| null
`public_ipv6_prefix`required	string \| null
`private_ipv4`required	string \| null
`private_ipv6`required	string \| null
`members`required	array of object
`id`required	string
`name`required	string
`frontend_port`required	integer
`address`required	string
`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	string \| null	Pass as `?cursor=` for the next page; null on the last page.

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/edges' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Attach a bastion, NAT gateway or load balancer to a private network#

POST/v1/edges

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

The way in from the IPv4 internet (bastion, load_balancer) and out to it (nat_gateway: NAT64 for 64:ff9b::/96, NAT44 for the network's IPv4 subnet, DNS64) for servers without IPv4 of their own. separate (the default and the production recommendation) runs every role on a VM of its own, the load_balancer role on a managed load balancer pair; combined runs every role on one VM (edge-<id>): one plan and one IPv4 address, but one failure domain, so production_recommended is false. Every edge VM is dual-stack and billed at its plan plus the IPv4 add-on. separate needs a zone of three servers (get_zone_capabilities, separate_edges): asked for explicitly in a smaller zone it is refused with 409 naming separate_edges; left out there, the edge is combined.

Request bodyapplication/json · CreateEdgeRequest

Request body fields
Field	Type	Description
`network_id`required	string
`name`	string	Defaults to "<network name> edge".
`roles`required	array of string	One of `bastion`, `nat_gateway`, `load_balancer`
`placement`	string	separate where the zone offers it (separate_edges), combined otherwise.One of `separate`, `combined`
`plan`	string	The plan of the bastion and NAT gateway VMs (the load balancer pair keeps its own).
`ssh_key_ids`	array of string	The bastion's keys from the account's library; defaults to all of them.
`members`	array of EdgeMemberInput	The load_balancer role's backends, one TCP frontend per frontend_port.
`name`required	string
`frontend_port`required	integer	The TCP port the edge listens on (IPv4 and IPv6).
`address`required	string	An IPv4 host of the network, or an IPv6 address: a server's public IPv6 or its leg's `address6`.
`port`required	integer
`weight`	integer
`enabled`	boolean

Responses

202The edge and its edge.sync operation.application/json

202 response fields
Field	Type	Description
`edge`required	Edge
`id`required	string
`zone`required	string
`name`required	string
`network_id`required	string
`roles`required	array of string	One of `bastion`, `nat_gateway`, `load_balancer`
`placement`required	string	One of `separate`, `combined`
`plan`required	string
`state`required	string	One of `creating`, `running`, `error`, `deleting`
`production_recommended`required	boolean	False for a combined edge.
`production_recommendation_reason`required	string \| null	Why a combined edge is not recommended for production.
`public_ipv4`required	string \| null	The IPv4 address to allow-list, point DNS at and SSH to (a combined edge's only one).
`bastion_jump_host`required	string \| null	`admin@<ipv4>`, for `ssh -J`.
`dns64_address`required	string \| null	The nat_gateway role's DNS64 resolver on the network's ULA /64.
`load_balancer_id`required	string \| null	The managed load balancer of a separate load_balancer role.
`ssh_key_count`required	integer
`configuration_generation`required	integer
`machines`required	array of object
`id`required	string
`name`required	string
`roles`required	array of string	One of `bastion`, `nat_gateway`, `load_balancer`
`state`required	string
`is_healthy`required	boolean
`health_detail`required	string
`public_ipv4`required	string \| null
`public_ipv6`required	string \| null
`public_ipv6_prefix`required	string \| null
`private_ipv4`required	string \| null
`private_ipv6`required	string \| null
`members`required	array of object
`id`required	string
`name`required	string
`frontend_port`required	integer
`address`required	string
`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/edges' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "network_id": "string",
  "roles": [
    "bastion"
  ]
}'

Get an edge with its VMs, addresses and members#

GET/v1/edges/{id}

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

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Responses

200The edge.application/json

200 response fields
Field	Type	Description
`edge`required	Edge
`id`required	string
`zone`required	string
`name`required	string
`network_id`required	string
`roles`required	array of string	One of `bastion`, `nat_gateway`, `load_balancer`
`placement`required	string	One of `separate`, `combined`
`plan`required	string
`state`required	string	One of `creating`, `running`, `error`, `deleting`
`production_recommended`required	boolean	False for a combined edge.
`production_recommendation_reason`required	string \| null	Why a combined edge is not recommended for production.
`public_ipv4`required	string \| null	The IPv4 address to allow-list, point DNS at and SSH to (a combined edge's only one).
`bastion_jump_host`required	string \| null	`admin@<ipv4>`, for `ssh -J`.
`dns64_address`required	string \| null	The nat_gateway role's DNS64 resolver on the network's ULA /64.
`load_balancer_id`required	string \| null	The managed load balancer of a separate load_balancer role.
`ssh_key_count`required	integer
`configuration_generation`required	integer
`machines`required	array of object
`id`required	string
`name`required	string
`roles`required	array of string	One of `bastion`, `nat_gateway`, `load_balancer`
`state`required	string
`is_healthy`required	boolean
`health_detail`required	string
`public_ipv4`required	string \| null
`public_ipv6`required	string \| null
`public_ipv6_prefix`required	string \| null
`private_ipv4`required	string \| null
`private_ipv6`required	string \| null
`members`required	array of object
`id`required	string
`name`required	string
`frontend_port`required	integer
`address`required	string
`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/edges/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Rename an edge, change its roles, bastion keys or members#

PATCH/v1/edges/{id}

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

Fields left out keep their value. Roles change only on a combined edge (409 on a separate one, whose roles are its VMs); members belong to a combined edge's load_balancer role (a separate one is the managed load balancer load_balancer_id, configured under /v1/load-balancers). Every change is one edge.sync operation.

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Request bodyapplication/json

Request body fields
Field	Type	Description
`name`	string
`roles`	array of string	One of `bastion`, `nat_gateway`, `load_balancer`
`ssh_key_ids`	array of string
`members`	array of EdgeMemberInput
`name`required	string
`frontend_port`required	integer	The TCP port the edge listens on (IPv4 and IPv6).
`address`required	string	An IPv4 host of the network, or an IPv6 address: a server's public IPv6 or its leg's `address6`.
`port`required	integer
`weight`	integer
`enabled`	boolean

Responses

202The changed edge and its edge.sync operation.application/json

202 response fields
Field	Type	Description
`edge`required	Edge
`id`required	string
`zone`required	string
`name`required	string
`network_id`required	string
`roles`required	array of string	One of `bastion`, `nat_gateway`, `load_balancer`
`placement`required	string	One of `separate`, `combined`
`plan`required	string
`state`required	string	One of `creating`, `running`, `error`, `deleting`
`production_recommended`required	boolean	False for a combined edge.
`production_recommendation_reason`required	string \| null	Why a combined edge is not recommended for production.
`public_ipv4`required	string \| null	The IPv4 address to allow-list, point DNS at and SSH to (a combined edge's only one).
`bastion_jump_host`required	string \| null	`admin@<ipv4>`, for `ssh -J`.
`dns64_address`required	string \| null	The nat_gateway role's DNS64 resolver on the network's ULA /64.
`load_balancer_id`required	string \| null	The managed load balancer of a separate load_balancer role.
`ssh_key_count`required	integer
`configuration_generation`required	integer
`machines`required	array of object
`id`required	string
`name`required	string
`roles`required	array of string	One of `bastion`, `nat_gateway`, `load_balancer`
`state`required	string
`is_healthy`required	boolean
`health_detail`required	string
`public_ipv4`required	string \| null
`public_ipv6`required	string \| null
`public_ipv6_prefix`required	string \| null
`private_ipv4`required	string \| null
`private_ipv6`required	string \| null
`members`required	array of object
`id`required	string
`name`required	string
`frontend_port`required	integer
`address`required	string
`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.
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/edges/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "roles": [
    "bastion"
  ],
  "ssh_key_ids": [
    "string"
  ],
  "members": [
    {
      "name": "string",
      "frontend_port": 1,
      "address": "string",
      "port": 1
    }
  ]
}'

Delete an edge, its VMs and (separate placement) its load balancer#

DELETE/v1/edges/{id}

Operation: delete_edge
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/edges/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"