Guides / Storage
Store objects in a bucket
Use a bucket to keep files and other blobs, up to 32 MiB each, under names you choose. In this guide you create one and then read and write objects over HTTPS with an API token.
We encrypt every object before it is stored, and we do not store object names in readable form either.
1. Create a bucket
kubectl apply -f - <<EOF
apiVersion: storage.etorm.com/v1alpha1
kind: Bucket
metadata: {name: docs}
spec:
description: team documents
EOF
kubectl get bucket docs -o jsonpath='{.status.phase} {.status.path}{"\n"}'
# Ready /v1/<project>/docs
In the console, open Storage, then Bucket, and choose New. Bucket names are DNS labels.
2. Write, read, list and delete objects
The endpoint is https://storage.etorm.com and the path is the bucket's status.path plus the object's key. The token is any Etorm API token that may use the bucket (see Sign in and get kubectl access and Automate with a service account).
B=https://storage.etorm.com/v1/acme-prod/docs
H="Authorization: Bearer $ETORM_TOKEN"
curl -X PUT -H "$H" -H 'Content-Type: text/plain' --data-binary @report.txt "$B/finance/q3.txt"
curl -H "$H" "$B/finance/q3.txt" # the object
curl -I -H "$H" "$B/finance/q3.txt" # size, type and ETag only
curl -H "$H" "$B?prefix=finance/&limit=50" # {"objects":[…],"cursor":…}
curl -X DELETE -H "$H" "$B/finance/q3.txt" # 204, also if it was not there
- A key is 1 to 1 024 bytes of UTF-8 and may contain
/. There are no directories.prefixmatches the start of a key. ETagis the SHA-256 of the object's bytes.If-None-Match: *on a write makes it create-only (412if the key exists).- Listing returns at most
limitobjects (default 100, up to 200) and acursorto continue. The order is not sorted by key. To find an object whose key you know, ask for that key directly. - Errors come back as the same
Statusobjects as the rest of the API:401no token,403not allowed,404no such bucket or object,413too large.
Decide who can read and write
Access follows the roles of the project, applied to the objects part of buckets:
| Request | Needs |
|---|---|
| read an object | get |
| list a bucket | list |
| write a new key | create |
| replace an existing key | create and update |
| delete | delete |
The built-in role storage-reader can read and list. storage-admin and editor can do everything. Give a teammate or a service account read access to the project's buckets with a role binding (see Give a teammate access). There are no public buckets.
Clean up by deleting the bucket
kubectl delete bucket docs
Deleting a bucket makes every object in it unreadable at once, for everyone, including a new bucket created later with the same name. Copy what you need first.
Limits
An object can be up to 32 MiB, and the limit is the same for every bucket. Each request writes one object. There are no ranges and no multipart upload. There are no S3-style signed requests either, so use an API token.
Next
Give a teammate access to the buckets, or let a process read and write them.