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 (next_cursor is always null).application/json

200 response fields
Field	Type	Description
`items`required	array of ObjectStorage
`id`required	string
`zone`required	string
`endpoint`required	string	The S3 endpoint, an https URL on the zone's DNS name (path-style URLs, SigV4 with any region).
`certificate_authority`required	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_id`required	string
`quota_bytes`required	integer
`used_bytes`required	integer
`object_count`required	integer
`usage_measured_at`required	string (date-time) \| null
`created_at`required	string (date-time)
`backend`required	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_prefix`required	string \| null	On ankra-s3-single, every bucket of the account must start with it (its buckets share one namespace). Null on `rgw`.
`durability`required	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_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/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.02 per GiB stored per month.

Request bodyapplication/json

Request body fields
Field	Type	Description
`zone`required	string

Responses

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

201 response fields
Field	Type	Description
`object_storage`required	ObjectStorage
`id`required	string
`zone`required	string
`endpoint`required	string	The S3 endpoint, an https URL on the zone's DNS name (path-style URLs, SigV4 with any region).
`certificate_authority`required	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_id`required	string
`quota_bytes`required	integer
`used_bytes`required	integer
`object_count`required	integer
`usage_measured_at`required	string (date-time) \| null
`created_at`required	string (date-time)
`backend`required	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_prefix`required	string \| null	On ankra-s3-single, every bucket of the account must start with it (its buckets share one namespace). Null on `rgw`.
`durability`required	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`
`credentials`required	ObjectStorageCredentials
`access_key_id`required	string
`secret_access_key`required	string

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).
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/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
Name	In	Type	Description
`zone`required	path	string

Responses

200The S3 key.application/json

200 response fields
Field	Type	Description
`credentials`required	ObjectStorageCredentials
`access_key_id`required	string
`secret_access_key`required	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_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.
503No capacity or address is free, or a host did not answer; 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. Once the zone has Ankra Storage, new accounts go to its replicated object storage (backend rgw); this moves an existing account there: 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. The endpoint and the key stay the same.

Parameters

Parameters
Name	In	Type	Description
`zone`required	path	string

Responses

202The buckets are being moved.application/json

202 response fields
Field	Type	Description
`object_storage`required	ObjectStorage
`id`required	string
`zone`required	string
`endpoint`required	string	The S3 endpoint, an https URL on the zone's DNS name (path-style URLs, SigV4 with any region).
`certificate_authority`required	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_id`required	string
`quota_bytes`required	integer
`used_bytes`required	integer
`object_count`required	integer
`usage_measured_at`required	string (date-time) \| null
`created_at`required	string (date-time)
`backend`required	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_prefix`required	string \| null	On ankra-s3-single, every bucket of the account must start with it (its buckets share one namespace). Null on `rgw`.
`durability`required	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`
`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.
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/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
Name	In	Type	Description
`zone`required	path	string

Responses

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

200 response fields
Field	Type	Description
`object_storage`required	ObjectStorage
`id`required	string
`zone`required	string
`endpoint`required	string	The S3 endpoint, an https URL on the zone's DNS name (path-style URLs, SigV4 with any region).
`certificate_authority`required	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_id`required	string
`quota_bytes`required	integer
`used_bytes`required	integer
`object_count`required	integer
`usage_measured_at`required	string (date-time) \| null
`created_at`required	string (date-time)
`backend`required	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_prefix`required	string \| null	On ankra-s3-single, every bucket of the account must start with it (its buckets share one namespace). Null on `rgw`.
`durability`required	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`
`credentials`required	ObjectStorageCredentials
`access_key_id`required	string
`secret_access_key`required	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_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.
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/object-storage/<zone>/rotate-keys' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"