Changing your backends safely

Marolum 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 Marolum, 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 Marolum 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

Removing and re-adding the same configured id does not create a new identity or reset its retention fences. Reuse that id only for the same state; disabling is simpler when observation will resume later. Explicit forget is a separate deletion act.

Choosing a new id creates a new backend identity, even if the bucket, prefix and layout are the same. For that new-id reconnect:

• 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.
• Retained operation history stays under the old backend identity until its retention window ends. It does not move to the new identity.
• Expired history comes back. Marolum 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 (Marolum re-reads it from a source that always had it), but "Marolum 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. MAROLUM_BACKEND_ID in every pipeline must be updated.
• Operation permalinks and bookmarked Operations filters keep their original target. They continue to show retained operation history you are authorized to read. See the resource-history link limits below for individual resources.

Treat a new-id reconnect as a separate retention history. Do not rename an id to bypass expiry or reuse an old id for different state.

Changing a backend's bucket, prefix, or region

Editing bucket, prefix, region, or endpoint on an existing id makes that identity observe different state. Marolum 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 MAROLUM_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 Marolum'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 Marolum 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 new coverage. Retained pre-migration operation history remains under the old backend and can be filtered by its id. Resource history does not follow resources across the layout and backend identity change.
5. Update runner configuration: MAROLUM_BACKEND_ID and MAROLUM_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 Marolum, and the old record's checkpoint reads would fail because the objects moved.

Renaming, moving, or deleting a stack

Resource-history links

Resource-history access is limited to stack identities represented in Marolum's current inventory and permitted by your access. A saved link to a resource removed from an existing stack can still show its retained transition summaries while that stack remains available to you. A resource-history link for an old stack identity can instead show Not found after a rename, move, or stack removal. That response does not establish that the retained data was deleted, and it does not redirect to the new identity.

Operation history has a separate access scope. Use Operations with the original backend, layout, project and stack filters to find retained operation records. Export the evidence you need before making a change.

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, Marolum 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 Marolum 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 Marolum.
• 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 MAROLUM_BACKEND_ID and MAROLUM_STACK_LAYOUT in every runner.
• After the restart, confirm the new backend's diagnostic and that Evidence coverage shows the expected collection start.