Concepts
Object storage
S3-compatible object storage per zone, with its own endpoint and key in each zone, AWS Signature V4, a durability the API reports and per-GiB billing.
Object storage is S3-compatible storage in a zone. You enable it per zone: each zone has its own endpoint, and your account gets one access key there. Any S3 client works against it.
Quick start#
With the CLI, jq and the AWS CLI:
ankra-cloud object-storage enable se-sto1
eval "$(ankra-cloud object-storage env se-sto1)"
prefix=$(ankra-cloud object-storage list -o json \
| jq -r '.[] | select(.zone == "se-sto1") | .bucket_prefix // ""')
aws s3 mb "s3://${prefix}backups"
aws s3 cp ./dump.sql.gz "s3://${prefix}backups/"
enableis idempotent: enabling an enabled zone answers its current key.envprintsAWS_ENDPOINT_URL,AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEYandAWS_REGIONas shell exports. An AWS CLI that does not readAWS_ENDPOINT_URLtakes--endpoint-url "$AWS_ENDPOINT_URL".prefixis the zone's bucket prefix, empty where the zone needs none, so the same commands work in every zone.
The same over the API:
curl -X POST https://cloud.ankra.app/v1/object-storage \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
-H 'Content-Type: application/json' \
-d '{ "zone": "se-sto1" }'
The answer holds object_storage (the fields below) and credentials (access_key_id, secret_access_key).
GET /v1/object-storage lists every zone you enabled.
What a zone reports#
| Field | Meaning |
|---|---|
endpoint |
The zone's S3 endpoint, an HTTPS URL. Every zone has its own. |
certificate_authority |
The PEM of the private certificate authority that signed the endpoint's certificate. null when a public authority signed it. |
access_key_id |
The ID of your key in the zone. The secret comes with credentials. |
backend |
rgw or ankra-s3-single, see Buckets and the bucket prefix. |
bucket_prefix |
What every bucket name of yours must start with in this zone. null where the zone needs none. |
durability |
replicated, degraded or single_copy, see Durability. |
quota_bytes |
The most your account may store in the zone. |
used_bytes, object_count |
What your account stores in the zone, as measured at usage_measured_at. |
ankra-cloud object-storage list shows the same per zone.
Connecting a client#
- Endpoint and key. Use the zone's
endpointwith the zone's key. Each zone has its own. - Signature. Sign with AWS Signature V4. Any region name signs; the CLI sets
us-east-1. - Addressing. Use path-style URLs,
<endpoint>/<bucket>/<key>. Turn path-style on in clients that default to virtual-hosted-style. - Certificate. When
certificate_authorityis notnull, the client must trust it. Save the PEM to a file and pass it as--ca-bundleorAWS_CA_BUNDLE:
ankra-cloud object-storage list -o json \
| jq -r '.[] | select(.zone == "se-sto1") | .certificate_authority // empty' > ankra-cloud-se-sto1-ca.pem
export AWS_CA_BUNDLE=$PWD/ankra-cloud-se-sto1-ca.pem
Buckets and the bucket prefix#
backend |
Bucket names |
|---|---|
rgw |
Buckets live in a tenant of your own, so a name never clashes with another account's. bucket_prefix is null. |
ankra-s3-single |
Buckets of all accounts share one namespace. Every bucket name of yours must start with your bucket_prefix, for example 7f3a9c21d4e0-backups; other names are refused. |
Read the prefix from bucket_prefix in the API or from ankra-cloud object-storage list -o json.
ankra-cloud object-storage env <zone> prints it as a comment when the zone has one.
Durability#
Each zone reports how many copies of your objects it keeps. Check it before you rely on a zone.
durability |
Meaning |
|---|---|
replicated |
Three copies on three hosts. Losing one host loses no objects. |
degraded |
Two copies on two hosts. While one host is down, new objects are written to one copy. |
single_copy |
One copy on one host. Objects are lost with that host's disks. |
ankra-cloud object-storage list has a DURABILITY column. Before you enable a zone,
GET /v1/zones/{zone}/capabilities reports the same as object_storage_durability.
In a single_copy zone, keep a second copy of everything that matters yourself, for example with rclone sync to
object storage in another zone or at another provider.
Keys#
Your account has one key per zone. It opens every bucket of yours in that zone.
| Task | How |
|---|---|
| Show the key again | GET /v1/object-storage/{zone}/credentials, or ankra-cloud object-storage credentials <zone> |
| Rotate the key | POST /v1/object-storage/{zone}/rotate-keys, or ankra-cloud object-storage rotate-keys <zone> |
Rotating answers a new key, and the old key stops working at once, so update every client that uses it. Enabling, showing the key and rotating it need a token with a write scope and are recorded in the audit log; a read-only token cannot read the key.
Moving to replicated object storage#
A zone on ankra-s3-single moves to replicated object storage (backend: rgw) as a whole once it has it. Ankra starts
that move. You keep your key, your endpoint and your bucket names.
POST /v1/object-storage/{zone}/migrate moves an account that is still on ankra-s3-single after the zone has moved.
It copies every bucket, then switches the account over, and answers 202 with an operation to follow. It answers 409
while the zone has not moved yet, and when the account is already on rgw.
Pricing and quota#
Stored data costs €0.015 per GiB-month, billed per started GiB held per hour. Enabling a zone costs nothing until it holds data, and deleting your objects stops the charge. Usage is measured every five minutes.
quota_bytes is your account's limit in the zone, 1 TiB by default, and used_bytes is what it holds. Where
backend is rgw, the store enforces the limit. See Billing and credits for how usage is invoiced.
Tools#
| Tool | What it offers |
|---|---|
| CLI | ankra-cloud object-storage (alias s3): list, enable <zone>, credentials <zone>, rotate-keys <zone> and env <zone>. ankra-cloud api migrate_object_storage -p zone=<zone> starts a move. |
| MCP server | The tools list_object_storage, enable_object_storage, get_object_storage_credentials, rotate_object_storage_keys and migrate_object_storage. |
| Terraform | The resource and data source ankracloud_object_storage, with endpoint, the key, certificate_authority, backend, bucket_prefix, durability and quota_bytes as attributes. |
| Kubernetes | The COSI driver cosi.ankra.cloud, below. |
Kubernetes: the COSI driver#
cosi.ankra.cloud is a COSI driver in the
public repository ankraio/ankra-cloud-csi, with
its own chart, charts/ankra-cloud-cosi. A BucketClaim creates a bucket in the zone its BucketClass names. A
BucketAccess yields a Secret with the zone's endpoint and key. Install steps and manifests are in the repository.
What to know before you use it:
- One key per zone. Every
BucketAccessin a zone receives the same key, and that key opens every bucket of the account in the zone. Use separate accounts for workloads that must not see each other's objects. - Revoking does nothing. Deleting a
BucketAccessdeletes its Secret, but the key keeps working until you rotate it. - Bucket names. In a zone with a
bucket_prefix, the real bucket name is in the Bucket'sstatus.bucketID, after<zone>/, not in the Secret. - Certificate. The Secret has no field for a certificate authority. When the zone reports a
certificate_authority, the workload must trust it itself.