Changing your backends safely

Lumaft ties everything it retains to a backend identity — the id you gave the record — and to a stack identity — backend plus layout plus project plus stack name. Change either and Lumaft, deliberately, starts a new history rather than guessing that the new thing is the old thing. This page says exactly what each change does so nothing surprises you a year later.

The one rule

A backend id is permanent. Retention fences, integration-token scopes, permalinks, filters, and coverage records all key on it. Choose ids you will never want to rename (platform-prod, not bucket-2), and never reuse an id for different state.

Adding a backend

Add the record to the backends file and restart. Observation begins immediately after bootstrap; coverage for every stack in it starts now. Update history the bucket still holds is copied in on the first five-minute cycle, as far back as the bucket kept it. Anything the backend pruned before today was never observed and will not appear.

Nothing about existing backends changes.

Disabling a backend

Set "enabled": false and restart.

• The record stays visible in the console with its state.
• Observation stops: no S3 requests, no new evidence.
• Everything already retained stays, and retention keeps running against it. Summaries and change detail expire on their normal windows.
• Stacks keep their last snapshot, labelled as last available.

Disable rather than remove when you may want the history back or you intend to forget it later; forget requires the backend to be disabled or removed first.

Removing a backend

Delete the record and restart. The behavior is the same as disabling: cached projections and retained evidence remain, retention keeps expiring them, and nothing is purged automatically. The difference is that the record no longer appears as configuration.

To actually delete what Lumaft retained, use Data & Retention: an exact-stack purge for each stack, or forget for the replay identity after payload has expired. Both are previewed, confirmed with a backup attestation, and written to Deletion history.

Re-adding a backend, or renaming its id

This is the change that surprises people. Removing a backend and adding it back — or changing its id — produces a new backend identity, even if the bucket, prefix, and layout are the same.

What follows from that:

• Coverage restarts. The new identity's collection start is today. Its stacks show Before coverage began for everything earlier, even though the old identity's history is still retained.
• Old history stays under the old identity until retention expires it. It does not move.
• Expired history comes back. Lumaft stops re-admitting expired evidence through a fence keyed on the backend identity. A new identity has no fence, so history that had reached the end of its retention window and been deleted is observed again from your bucket as new evidence, with a fresh retention clock. This is not recovery of deleted data — Lumaft re-reads it from a source that always had it — but "Lumaft deletes this after N days" is only true for as long as the backend keeps the identity it was observed under.
• Integration tokens stop matching. A token scoped to production/*/* no longer covers a backend now called prod. Issue new tokens.
• Runner configuration changes. LUMAFT_BACKEND_ID in every pipeline must be updated.
• Permalinks and saved filters referencing the old id still resolve to the old history.

Treat removing and re-adding a backend as restarting retention for everything it covers, and prefer disabling.

Changing a backend's bucket, prefix, or region

Editing bucket, prefix, region, or endpoint on an existing id makes that identity observe different state. Lumaft does not stop you, and it does not merge or separate the histories for you: evidence from before and after the edit sits under one identity.

Unless the change is a pure relocation of exactly the same state (the bucket was renamed, the objects are byte-identical), do this instead:

1. Add a new record with a new id for the new location.
2. Set the old record "enabled": false and keep it for its history.
3. Update token scopes and LUMAFT_BACKEND_ID in runners.

Migrating from the legacy layout to project-scoped

Pulumi's pulumi state upgrade migrates a DIY backend from the deprecated legacy layout to the project-scoped layout, in place. From Lumaft's side this is a layout change, and layout is part of both the backend record and the stack identity:

1. Before the migration, take a backup of Lumaft and note the old backend's id.
2. Run the Pulumi migration.
3. Add a new record with "layout": "project-scoped" and a new id. Keep the old record with "layout": "legacy" and "enabled": false.
4. Restart. Stacks appear under the new backend with coverage starting now; their pre-migration history remains under the old backend, filterable by its id.
5. Update runner configuration: LUMAFT_BACKEND_ID and LUMAFT_STACK_LAYOUT (or --layout).
6. Reissue integration tokens scoped to the new id.

Do not edit the old record's layout in place: the legacy stacks' history and the project-scoped stacks would then share one identity while being different stack identities to Lumaft, and the old record's checkpoint reads would fail because the objects moved.

Renaming, moving, or deleting a stack

Rotating backend credentials

• Roles and profiles (ECS task role, EC2 instance profile, web identity): rotate at the provider; the SDK refreshes automatically. No restart.
• Static keys in the environment: update the secret and restart the container.
• Bucket policy changes take effect at the next observation cycle. A failure is isolated to that backend and shows in its diagnostic.

Forgetting a source

After payload expires, Lumaft keeps a compact replay fence per source so pruned evidence cannot be replayed into history. Forget retires those fences for a backend — and it requires that backend to be disabled or removed first, because Lumaft cannot prove narrower per-source revocation while the backend is still being observed.

1. Disable the backend ("enabled": false) and restart.
2. Revoke, or let expire, every integration token whose scope matches the backend's stacks.
3. Wait for payload to expire under retention, or purge the stacks explicitly.
4. In Data & Retention, preview forget, attest to your backup, confirm, and keep the action reference to read completion after a reload.

Forget also removes retained whole-state copies for the backend if state capture was enabled. Your bucket and your own backups are outside its scope.

Before any change: a checklist

• Export the evidence you must keep for each affected stack and window (Operations → Export evidence). Exports are the only record that survives every case above.
• Take a cold backup of Lumaft.
• Write down the old id, layout, and prefix.
• Decide: disable (keep history, allow forget later) or remove (same, but gone from configuration).
• List integration tokens scoped to the old id; plan their successors.
• Update LUMAFT_BACKEND_ID and LUMAFT_STACK_LAYOUT in every runner.
• After the restart, confirm the new backend's diagnostic and that Evidence coverage shows the expected collection start.