Skip to content
Forgeplane Docs

Terraform and OpenTofu managed state

Forgeplane-managed state coordinates the state contract for Terraform and OpenTofu runs. It ties a state identity to encrypted object storage, key-backed verification, and a database generation so stale executions cannot silently replace newer state. Ansible is execute-only and does not use this state path.

When enabled, an instance is the managed-state ownership boundary. This page describes Forgeplane’s state path and its recovery guarantees; it does not claim that every feature of every mature Terraform or OpenTofu backend is supported.

What Forgeplane manages

Section titled “What Forgeplane manages”
Part What it provides
Coordinator metadata State identity, instance ownership, current generation, status, and integrity metadata.
Encrypted object The state payload stored outside the coordinator database.
Key material The references and access needed to authenticate and decrypt the payload.
Run snapshot The state object, base generation, and status observed when a run starts.

A usable generation requires these parts to agree. The object-store blob is not authoritative by itself, and database metadata is not a substitute for the encrypted payload.

Storage model

Section titled “Storage model”

Managed state is one coordinated record across three required parts:

  • the coordinator database stores state identity, ownership, generation, status, and integrity metadata;
  • the object store holds the encrypted state payload;
  • configured key material authenticates and decrypts that payload.

Forgeplane keeps the state payload out of ordinary template inputs and only makes the decrypted state available on the bounded execution path. Review configuration for the storage and key settings used by your deployment.

Run admission and generations

Section titled “Run admission and generations”

At admission, a run captures its state_object_id, base state_generation, and state_status_at_start. Before committing an update, Forgeplane verifies that the base generation is still current. A stale run cannot overwrite a newer state generation.

The worker receives the decrypted state only for the bounded execution path. New state is authenticated, encrypted, stored, and then coordinated with its database generation before it becomes current.

The run snapshot is historical. Changing an environment, template, or later configuration does not rewrite the state context already admitted for that run. See Instances and Runs for the surrounding execution model.

Boundaries to keep clear

Section titled “Boundaries to keep clear”
  • Managed state applies to Terraform and OpenTofu. Ansible remains execute-only and does not use this state path.
  • A failed or cancelled run is not an automatic rollback. Selective Undo creates a new evidence-backed removal intent and a new execution; it does not relabel an earlier state generation as restored.
  • A missing or uncertain state layer is not permission to create an empty state, fall back to an older object, or overwrite the current generation.
  • Managed state is a state coordination and recovery contract. Do not treat this page as a promise of universal remote-state backend compatibility or cross-run behavior that the deployed release does not expose.

Fail-closed recovery

Section titled “Fail-closed recovery”

Forgeplane marks state recovery_required when it cannot prove that database metadata, the encrypted object, and key-backed verification describe one valid current generation. Managed-state mutation then stops. New runs must not guess, fall back to an older object, or overwrite the uncertain generation.

Recovery must identify and verify the intended current generation before normal admission resumes. A retry that finds an already verified object should complete idempotently rather than create another generation. The administrative recovery surface is described in the admin dashboard guide.

Backup and restore

Section titled “Backup and restore”

Back up the database, encrypted object store, and required key material as one recovery set. Restoring only the database or only object blobs can leave state unusable even when each restored system is internally healthy.

After restore, verify object identity, generation, integrity metadata, and key access before permitting state-changing runs. Keep a restore drill and key-rotation procedure aligned with the deployed release; replacing a referenced key without preserving its key ID can make encrypted data unrecoverable.

Before enabling in production

Section titled “Before enabling in production”
  1. Confirm that PostgreSQL metadata, encrypted state objects, and referenced key material are included in the same backup and restore procedure.
  2. Test a restore and verify identity, generation, integrity, and key access before allowing state-changing runs.
  3. Make sure operators understand that recovery_required stops managed-state mutation and requires explicit recovery.
  4. Review feature gates, approval workflows, and the deployed coordinator’s API contract before widening access.
Section titled “Related workflows”