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

Decide who can read and write

Access follows the roles of the project, applied to the objects part of buckets:

RequestNeeds
read an objectget
list a bucketlist
write a new keycreate
replace an existing keycreate and update
deletedelete

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.