API reference · Managed services
Object storage
5 operations of the Ankra Cloud API: Managed object storage.
List the zones the account enabled object storage in, with their usage#
/v1/object-storage- Operation
list_object_storage- Credentials
- API token, Portal session
- Requires
- Permission
read
Responses
200One entry per enabled zone, so the list is never paged and next_cursor is always null.application/json
| Field | Type | Description |
|---|---|---|
itemsrequired | array of ObjectStorage | |
idrequired | string | |
zonerequired | string | |
endpointrequired | string | The S3 endpoint, an https URL on the zone's DNS name (path-style URLs, SigV4 with any region). |
certificate_authorityrequired | string | null | PEM of the private CA that signed the endpoint's certificate, for clients to verify it with; null when a public CA signed it or the endpoint is plain HTTP. |
access_key_idrequired | string | |
quota_bytesrequired | integer | |
used_bytesrequired | integer | |
object_countrequired | integer | |
usage_measured_atrequired | string (date-time) | null | |
created_atrequired | string (date-time) | |
backendrequired | string | rgw is replicated object storage on Ankra Storage; ankra-s3-single, the single-node S3 server, serves a zone without Ankra Storage, and migrate_object_storage moves the buckets to replicated object storage once it has Ankra Storage.One of rgw, ankra-s3-single |
bucket_prefixrequired | string | null | On ankra-s3-single, every bucket of the account must start with it (its buckets share one namespace). Null on rgw. |
durabilityrequired | string | How many copies the store that holds the account's objects keeps. single_copy on ankra-s3-single: one copy on one host, lost with that host's disks, so keep a second copy of what matters elsewhere. On rgw what the zone's Ankra Storage replicates: replicated (three copies on three hosts), degraded (two) or single_copy (one host).One of replicated, degraded, single_copy |
next_cursorrequired | 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_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl 'https://cloud.ankra.app/v1/object-storage' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Enable S3-compatible object storage in a zone#
/v1/object-storage- Operation
enable_object_storage- Credentials
- API token, Portal session
- Requires
- Permission
operate
Idempotent; an enabled zone answers its current key. €0.015 per GiB stored per month.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
Idempotency-Key | header | string | A key the client chooses for this create, for example a UUID. The same create sent again with the same key within 24 hours answers the first one's answer with Idempotent-Replayed: true and creates nothing. 409 with reason: idempotency_key_in_progress while the first request is still running (try again shortly), with reason: idempotency_key_outcome_unknown when the first request answered 5xx or never finished (the create may or may not exist: list the resource before creating again with a new key), or with reason: idempotency_key_answer_not_stored when the create succeeded but its answer could not be kept (read the resource). 422 with reason: idempotency_key_reused when the key was used with a different request, 400 when the key is not 1 to 255 visible ASCII characters. Only a 4xx answer frees a key before the 24 hours. |
Request bodyapplication/json
| Field | Type | Description |
|---|---|---|
zonerequired | string |
Responses
201The zone's object storage and its S3 key.application/json · ObjectStorageWithCredentials
| Field | Type | Description |
|---|---|---|
object_storagerequired | ObjectStorage | |
idrequired | string | |
zonerequired | string | |
endpointrequired | string | The S3 endpoint, an https URL on the zone's DNS name (path-style URLs, SigV4 with any region). |
certificate_authorityrequired | string | null | PEM of the private CA that signed the endpoint's certificate, for clients to verify it with; null when a public CA signed it or the endpoint is plain HTTP. |
access_key_idrequired | string | |
quota_bytesrequired | integer | |
used_bytesrequired | integer | |
object_countrequired | integer | |
usage_measured_atrequired | string (date-time) | null | |
created_atrequired | string (date-time) | |
backendrequired | string | rgw is replicated object storage on Ankra Storage; ankra-s3-single, the single-node S3 server, serves a zone without Ankra Storage, and migrate_object_storage moves the buckets to replicated object storage once it has Ankra Storage.One of rgw, ankra-s3-single |
bucket_prefixrequired | string | null | On ankra-s3-single, every bucket of the account must start with it (its buckets share one namespace). Null on rgw. |
durabilityrequired | string | How many copies the store that holds the account's objects keeps. single_copy on ankra-s3-single: one copy on one host, lost with that host's disks, so keep a second copy of what matters elsewhere. On rgw what the zone's Ankra Storage replicates: replicated (three copies on three hosts), degraded (two) or single_copy (one host).One of replicated, degraded, single_copy |
credentialsrequired | ObjectStorageCredentials | |
access_key_idrequired | string | |
secret_access_keyrequired | string |
- 400The request is invalid;
detailsays why. - 401Not signed in, or the credential is invalid or expired.
- 402The account may not create this.
reasonispayment_method_requiredwhile it has no default payment method and its credit does not cover the create: the credit left must cover one month, at monthly list prices, of everything the account already runs plus what the create adds (add a payment method throughPOST /v1/account/billing/setup-session, or free what the account no longer needs);owner_approval_requiredwhile its owner has not approved paid usage and no credit is left; oraccount_suspendedwhile an invoice is overdue past the grace period (pay it) or Ankra staff suspended the account (contact support). Aprepaidaccount (linked to an Ankra platform organisation) is refused withpayment_method_requiredwhile it has no card, and withcredit_requiredonce it has one but its credit does not cover the create: Cloud never charges its card, so only a top-up on the Ankra platform lifts it, andtop_up_urlnames that page when Cloud knows it.GET /v1/account/billingreports the samestanding. Forpayment_method_requiredandcredit_required,detailnames what the create costs, the credit left and the committed monthly spend only to a principal that may read billing (billing.read, and for an API token a scope that includes it); anyone else is told only that the credit does not cover it. - 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 409The resource's state does not allow this now.
- 422The
Idempotency-Keywas already used with a different request (reason: idempotency_key_reused). - 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - 503No capacity or address is free in the zone right now (
reason: capacity_unavailable, with availability wording indetail), or a host did not answer; try another plan or zone, or try again later. - defaultAny other error, usually 500.
Example
curl -X POST 'https://cloud.ankra.app/v1/object-storage' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"zone": "string"
}'Show the zone's S3 key (audited)#
/v1/object-storage/{zone}/credentials- Operation
get_object_storage_credentials- Credentials
- API token, Portal session
- Requires
- Permission
operate - Note
- Reveals a credential or a live view; read-only support sessions are refused.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
zonerequired | path | string |
Responses
200The S3 key.application/json
| Field | Type | Description |
|---|---|---|
credentialsrequired | ObjectStorageCredentials | |
access_key_idrequired | string | |
secret_access_keyrequired | string |
- 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - 503No capacity or address is free in the zone right now (
reason: capacity_unavailable, with availability wording indetail), or a host did not answer; try another plan or zone, or try again later. - defaultAny other error, usually 500.
Example
curl 'https://cloud.ankra.app/v1/object-storage/<zone>/credentials' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Move the zone's buckets from the single-node S3 server to replicated object storage#
/v1/object-storage/{zone}/migrate- Operation
migrate_object_storage- Credentials
- API token, Portal session
- Requires
- Permission
operate
A zone without Ankra Storage serves S3 from a single-node server, where every bucket of the account starts
with its bucket_prefix. Such a zone moves to its replicated object storage (backend rgw) as a whole, which
Ankra staff start: every account keeps its key, its endpoint and its bucket names. This moves one account left on
the single-node server once the zone no longer runs that server: a user with the same key, a copy of every
bucket (objects the replicated store already holds with the same size are skipped, so the operation resumes),
then the switch. 409 while the zone's single-node server still serves its endpoint.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
zonerequired | path | string |
Responses
202The buckets are being moved.application/json
| Field | Type | Description |
|---|---|---|
object_storagerequired | ObjectStorage | |
idrequired | string | |
zonerequired | string | |
endpointrequired | string | The S3 endpoint, an https URL on the zone's DNS name (path-style URLs, SigV4 with any region). |
certificate_authorityrequired | string | null | PEM of the private CA that signed the endpoint's certificate, for clients to verify it with; null when a public CA signed it or the endpoint is plain HTTP. |
access_key_idrequired | string | |
quota_bytesrequired | integer | |
used_bytesrequired | integer | |
object_countrequired | integer | |
usage_measured_atrequired | string (date-time) | null | |
created_atrequired | string (date-time) | |
backendrequired | string | rgw is replicated object storage on Ankra Storage; ankra-s3-single, the single-node S3 server, serves a zone without Ankra Storage, and migrate_object_storage moves the buckets to replicated object storage once it has Ankra Storage.One of rgw, ankra-s3-single |
bucket_prefixrequired | string | null | On ankra-s3-single, every bucket of the account must start with it (its buckets share one namespace). Null on rgw. |
durabilityrequired | string | How many copies the store that holds the account's objects keeps. single_copy on ankra-s3-single: one copy on one host, lost with that host's disks, so keep a second copy of what matters elsewhere. On rgw what the zone's Ankra Storage replicates: replicated (three copies on three hosts), degraded (two) or single_copy (one host).One of replicated, degraded, single_copy |
operationrequired | Operation | |
idrequired | string | |
kindrequired | string | One of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify |
server_idrequired | string | null | |
storage_idrequired | string | null | |
backup_idrequired | string | null | |
template_idrequired | string | null | |
router_idrequired | string | null | |
floating_ip_idrequired | string | null | |
node_id | string | Set on node maintenance operations (operator only); absent otherwise. |
load_balancer_id | string | null | Set on the operations that create and delete a load balancer. |
database_id | string | null | Set on the operations that create and delete a managed database. |
edge_id | string | null | Set on the operations that sync and delete a network edge. |
vpn_gateway_id | string | null | Set on the operations that sync and delete a VPN gateway. |
snapshot_id | string | null | Set on the operations that create and delete a snapshot, and on a storage.create that clones one. |
kubernetes_cluster_id | string | null | Set on the operations of a managed Kubernetes cluster. |
node_pool_id | string | null | Set on the operations of a Kubernetes node pool. |
kubernetes_host_id | string | Set on a regional host cluster bootstrap (operator only); absent otherwise. |
statusrequired | string | One of pending, running, succeeded, failed, cancelled |
steprequired | string | Machine name of the current step, e.g. create_disk or transfer_cross_zone. |
step_indexrequired | integer | |
step_countrequired | integer | |
errorrequired | string | Empty unless the operation failed. |
created_atrequired | string (date-time) | |
started_atrequired | string (date-time) | null | |
finished_atrequired | string (date-time) | null | |
deadline_atrequired | string (date-time) | |
actor | string | Who asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations. |
progress | MigrationProgress | Present on GET /v1/operations/{id} while a server.migrate drives a live transfer. |
staterequired | string | One of reserved, detached, preparing, sending, switched, aborting |
source_node_idrequired | string | |
target_node_idrequired | string | |
phaserequired | string | How far the nodes report the current attempt.One of , preparing, transferring, completed, failed |
attemptrequired | integer | Which send this is under the convergence policy, from 1. |
iterationrequired | integer | Memory passes so far in the current attempt. |
transferred_bytesrequired | integer | |
total_bytesrequired | integer | 0 when the hypervisor does not report it. |
dirty_bytes_per_secondrequired | integer | |
downtime_millisecondsrequired | integer | The pause the guest took at handover, once completed. |
detailrequired | string | |
reported_atrequired | string (date-time) | null | The reporting node's clock. |
events | array of OperationEvent | Present on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first. |
atrequired | string (date-time) | |
kindrequired | string | For example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed. |
messagerequired | string | |
datarequired | object |
- 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 409The resource's state does not allow this now.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - 503No capacity or address is free in the zone right now (
reason: capacity_unavailable, with availability wording indetail), or a host did not answer; try another plan or zone, or try again later. - defaultAny other error, usually 500.
Example
curl -X POST 'https://cloud.ankra.app/v1/object-storage/<zone>/migrate' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Replace the zone's S3 key; the old one stops working at once#
/v1/object-storage/{zone}/rotate-keys- Operation
rotate_object_storage_keys- Credentials
- API token, Portal session
- Requires
- Permission
operate
Parameters
| Name | In | Type | Description |
|---|---|---|---|
zonerequired | path | string |
Responses
200The zone's object storage and its new S3 key.application/json · ObjectStorageWithCredentials
| Field | Type | Description |
|---|---|---|
object_storagerequired | ObjectStorage | |
idrequired | string | |
zonerequired | string | |
endpointrequired | string | The S3 endpoint, an https URL on the zone's DNS name (path-style URLs, SigV4 with any region). |
certificate_authorityrequired | string | null | PEM of the private CA that signed the endpoint's certificate, for clients to verify it with; null when a public CA signed it or the endpoint is plain HTTP. |
access_key_idrequired | string | |
quota_bytesrequired | integer | |
used_bytesrequired | integer | |
object_countrequired | integer | |
usage_measured_atrequired | string (date-time) | null | |
created_atrequired | string (date-time) | |
backendrequired | string | rgw is replicated object storage on Ankra Storage; ankra-s3-single, the single-node S3 server, serves a zone without Ankra Storage, and migrate_object_storage moves the buckets to replicated object storage once it has Ankra Storage.One of rgw, ankra-s3-single |
bucket_prefixrequired | string | null | On ankra-s3-single, every bucket of the account must start with it (its buckets share one namespace). Null on rgw. |
durabilityrequired | string | How many copies the store that holds the account's objects keeps. single_copy on ankra-s3-single: one copy on one host, lost with that host's disks, so keep a second copy of what matters elsewhere. On rgw what the zone's Ankra Storage replicates: replicated (three copies on three hosts), degraded (two) or single_copy (one host).One of replicated, degraded, single_copy |
credentialsrequired | ObjectStorageCredentials | |
access_key_idrequired | string | |
secret_access_keyrequired | string |
- 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - 503No capacity or address is free in the zone right now (
reason: capacity_unavailable, with availability wording indetail), or a host did not answer; try another plan or zone, or try again later. - defaultAny other error, usually 500.
Example
curl -X POST 'https://cloud.ankra.app/v1/object-storage/<zone>/rotate-keys' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"