The organization's bucket · Firstlume Docs

By default, every organization's state goes to the installation's storage. An organization can keep its state in an S3 bucket of its own instead. Firstlume is still the backend: the protocol, the locks, the versions, the tokens and the import don't change. Only the place where the object is written changes.

Configure it

curl -X PUT -H "Authorization: Bearer $ADMIN" -H "Content-Type: application/json" "$API/api/v1/orgs/$ORG/state-storage" -d '{
  "kind": "s3", "endpoint": "https://s3.example.com", "bucket": "infra", "region": "us-east-1",
  "folder": "firstlume", "access_key_id": "...", "secret_access_key": "..."
}'

region defaults to us-east-1, folder to firstlume and path_style to true. ca_cert is optional, for endpoints with a certificate from your own CA.

Firstlume tests the bucket before saving (it writes, reads and deletes an object) and says what failed. POST .../state-storage/check runs the same test without saving. With no body, it tests the current storage.

The secret key never comes back through the API. Sent empty, it keeps the stored one.

An http:// endpoint is only accepted with controlPlane.state.allowHTTPOrgStorage: true in Helm, for storage inside the cluster.

What goes in the bucket

Firstlume only uses the folder, and writes a .firstlume file there saying which organization it belongs to. A folder belonging to another organization is refused. The rest of the bucket isn't touched, not even by cleanup, so two organizations can share a bucket, each in its own folder.

Inside the folder, files use Firstlume's names: <folders>/<stack>/<unit>/v<number>-<id>.tfstate.enc.

firstlume/
  .firstlume
  infra/prod/cluster/
    zone-a/node01/app/
      v000012-0f2c91ab-….tfstate.enc
    access/
      v000004-91ab07de-….tfstate.enc
  dns/records/
    v000002-5d1e….tfstate.enc

Renaming doesn't move anything: new versions go to the new path.

Encrypted by default

With "encrypt": false and "plaintext_acknowledged": true, new versions are written as .tfstate, Terraform's JSON, readable with mc or aws s3.

Whoever can read the bucket can read the secrets in the state. Providers keep passwords, keys and tokens there. The installation's storage is always encrypted, and this option only exists for an organization's bucket.

Changing storage

A change of storage or mode applies to the writes that follow. Old versions are still read from where they are. {"kind": "installation"} goes back to the installation's storage. GET .../state-storage shows the current storage and the previous ones that still hold versions.

If the bucket goes down

State requests answer 503, and the run fails at Init with the reason. The server and the other organizations keep working.

Planned

Reading the bucket's credential from Vault
Moving existing versions to the current storage
A section for this in the organization's settings screen