Where state lives

The installation's state storage is set once, at install time. Firstlume always encrypts each version before writing it, and the object key holds only ids, never the name of a stack or a unit. Metadata and locks always stay in Postgres.

Settings

Variable	Default
`FIRSTLUME_STATE_STORAGE`	`postgres`	`postgres` or `s3` (any S3-compatible service, tested with Garage)
`FIRSTLUME_STATE_S3_ENDPOINT`		for example `http://garage.garage.svc:3900`
`FIRSTLUME_STATE_S3_BUCKET`
`FIRSTLUME_STATE_S3_REGION`	`garage`
`FIRSTLUME_STATE_S3_PREFIX`		to share a bucket
`FIRSTLUME_STATE_S3_ACCESS_KEY_ID`, `FIRSTLUME_STATE_S3_SECRET_ACCESS_KEY`		the key must be able to read, write, delete and list in the bucket
`FIRSTLUME_STATE_S3_PATH_STYLE`	`true`	Garage needs path-style
`FIRSTLUME_STATE_KEEP_VERSIONS`	`0`	versions kept per unit; `0` keeps them all
`FIRSTLUME_STATE_MAX_MIB`	`64`	maximum size of one version

With Helm

Use controlPlane.state.storage: s3 and controlPlane.state.s3.*, with the key in an existing Secret:

controlPlane:
  state:
    storage: s3
    keepVersions: 0
    maxMiB: 64
    s3:
      endpoint: http://garage.garage.svc:3900
      bucket: firstlume-state
      region: garage
      pathStyle: true
      existingSecret: firstlume-state-s3   # keys access-key-id and secret-access-key

Startup check

With s3, the server writes, reads and deletes a test object when it starts. If that fails, it doesn't start and says why: endpoint down, credential refused, bucket missing, or a key without permission.

Changing storage doesn't move the versions already written.

Using the `s3` backend directly on Garage

Garage (tested on v2.4.1) ignores conditional writes (If-None-Match). So the use_lockfile option of Terraform's s3 backend doesn't lock anything there: one apply runs right over another's lock. With Firstlume's backend, the lock lives in Postgres and works with any storage.

One organization, its own bucket

By default, every organization's state goes to this storage. An organization can use a bucket of its own instead. See The organization's bucket.

Settings

With Helm

Startup check

Using the s3 backend directly on Garage

One organization, its own bucket

Using the `s3` backend directly on Garage