AnkraDocs
Console

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#

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

200 response fields
FieldTypeDescription
itemsrequiredarray of ObjectStorage
idrequiredstring
zonerequiredstring
endpointrequiredstringThe S3 endpoint, an https URL on the zone's DNS name (path-style URLs, SigV4 with any region).
certificate_authorityrequiredstring | nullPEM 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_idrequiredstring
quota_bytesrequiredinteger
used_bytesrequiredinteger
object_countrequiredinteger
usage_measured_atrequiredstring (date-time) | null
created_atrequiredstring (date-time)
backendrequiredstringrgw 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_prefixrequiredstring | nullOn ankra-s3-single, every bucket of the account must start with it (its buckets share one namespace). Null on rgw.
durabilityrequiredstringHow 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_cursorrequirednull
  • 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).
  • 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

bash
curl 'https://cloud.ankra.app/v1/object-storage' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Enable S3-compatible object storage in a zone#

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

Parameters
NameInTypeDescription
Idempotency-KeyheaderstringA 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

Request body fields
FieldTypeDescription
zonerequiredstring

Responses

201The zone's object storage and its S3 key.application/json · ObjectStorageWithCredentials

201 response fields
FieldTypeDescription
object_storagerequiredObjectStorage
idrequiredstring
zonerequiredstring
endpointrequiredstringThe S3 endpoint, an https URL on the zone's DNS name (path-style URLs, SigV4 with any region).
certificate_authorityrequiredstring | nullPEM 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_idrequiredstring
quota_bytesrequiredinteger
used_bytesrequiredinteger
object_countrequiredinteger
usage_measured_atrequiredstring (date-time) | null
created_atrequiredstring (date-time)
backendrequiredstringrgw 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_prefixrequiredstring | nullOn ankra-s3-single, every bucket of the account must start with it (its buckets share one namespace). Null on rgw.
durabilityrequiredstringHow 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
credentialsrequiredObjectStorageCredentials
access_key_idrequiredstring
secret_access_keyrequiredstring
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 402The account may not create this. reason is payment_method_required while 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 through POST /v1/account/billing/setup-session, or free what the account no longer needs); owner_approval_required while its owner has not approved paid usage and no credit is left; or account_suspended while an invoice is overdue past the grace period (pay it) or Ankra staff suspended the account (contact support). A prepaid account (linked to an Ankra platform organisation) is refused with payment_method_required while it has no card, and with credit_required once 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, and top_up_url names that page when Cloud knows it. GET /v1/account/billing reports the same standing. For payment_method_required and credit_required, detail names 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_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 Idempotency-Key was 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 in detail), or a host did not answer; try another plan or zone, or try again later.
  • defaultAny other error, usually 500.

Example

bash
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)#

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

Parameters
NameInTypeDescription
zonerequiredpathstring

Responses

200The S3 key.application/json

200 response fields
FieldTypeDescription
credentialsrequiredObjectStorageCredentials
access_key_idrequiredstring
secret_access_keyrequiredstring
  • 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.
  • 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 in detail), or a host did not answer; try another plan or zone, or try again later.
  • defaultAny other error, usually 500.

Example

bash
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#

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

Parameters
NameInTypeDescription
zonerequiredpathstring

Responses

202The buckets are being moved.application/json

202 response fields
FieldTypeDescription
object_storagerequiredObjectStorage
idrequiredstring
zonerequiredstring
endpointrequiredstringThe S3 endpoint, an https URL on the zone's DNS name (path-style URLs, SigV4 with any region).
certificate_authorityrequiredstring | nullPEM 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_idrequiredstring
quota_bytesrequiredinteger
used_bytesrequiredinteger
object_countrequiredinteger
usage_measured_atrequiredstring (date-time) | null
created_atrequiredstring (date-time)
backendrequiredstringrgw 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_prefixrequiredstring | nullOn ankra-s3-single, every bucket of the account must start with it (its buckets share one namespace). Null on rgw.
durabilityrequiredstringHow 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
operationrequiredOperation
idrequiredstring
kindrequiredstringOne 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_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 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.
  • 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 in detail), or a host did not answer; try another plan or zone, or try again later.
  • defaultAny other error, usually 500.

Example

bash
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#

POST/v1/object-storage/{zone}/rotate-keys
Operation
rotate_object_storage_keys
Credentials
API token, Portal session
Requires
Permission operate

Parameters

Parameters
NameInTypeDescription
zonerequiredpathstring

Responses

200The zone's object storage and its new S3 key.application/json · ObjectStorageWithCredentials

200 response fields
FieldTypeDescription
object_storagerequiredObjectStorage
idrequiredstring
zonerequiredstring
endpointrequiredstringThe S3 endpoint, an https URL on the zone's DNS name (path-style URLs, SigV4 with any region).
certificate_authorityrequiredstring | nullPEM 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_idrequiredstring
quota_bytesrequiredinteger
used_bytesrequiredinteger
object_countrequiredinteger
usage_measured_atrequiredstring (date-time) | null
created_atrequiredstring (date-time)
backendrequiredstringrgw 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_prefixrequiredstring | nullOn ankra-s3-single, every bucket of the account must start with it (its buckets share one namespace). Null on rgw.
durabilityrequiredstringHow 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
credentialsrequiredObjectStorageCredentials
access_key_idrequiredstring
secret_access_keyrequiredstring
  • 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.
  • 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 in detail), or a host did not answer; try another plan or zone, or try again later.
  • defaultAny other error, usually 500.

Example

bash
curl -X POST 'https://cloud.ankra.app/v1/object-storage/<zone>/rotate-keys' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"