Skip to content
AletheiaAletheiaAletheia docs

Terraform state sources

A state source is a specific location Aletheia is allowed to read Terraform or OpenTofu state from. Nothing is read until you designate one.

This is the deliberate shape of the feature: state files describe your whole estate and can contain sensitive values, so access is opt-in per location rather than inferred from bucket permissions.

Adding one

Section titled “Adding one”

Go to Administration → State sources (/admin/state-sources) and add a source. You supply:

  • The AWS account that owns the bucket, chosen from your connected accounts.
  • The bucket and the key or prefix to read.

Aletheia reads it through the same read-only role you already deployed for that account. There is no second credential.

The permission it needs

Section titled “The permission it needs”

Reading state requires s3:GetObject on the state objects. The customer role template denies s3:GetObject broadly and carves out an exception for the buckets you name, so designating a state source is what grants the access — not a blanket read of every bucket.

If you deployed the role before state sources existed, the deployed template is behind and state sync will fail with an access error until you upgrade it. The connection page tells you when your template is out of date and what the newer version adds. See Connect your AWS accounts.

Sync

Section titled “Sync”

Aletheia re-reads designated state on a schedule, and you can trigger a sync by hand.

Each read compares the object’s content hash against the last one processed. Unchanged state is skipped, so a frequent schedule on a stable estate costs almost nothing.

What a sync produces:

  1. The state is parsed and its resource entries extracted, with their addresses and identifiers.
  2. Values marked sensitive in the state are redacted before storage. Aletheia stores the shape of your state, not its secrets.
  3. Mapping re-runs, and each affected resource’s management state is recalculated.

Aletheia parses the state format directly. It does not run terraform, and it never holds a state lock.

Choosing what to designate

Section titled “Choosing what to designate”

Point at the state for the roots you care about. A prefix covering many state files is fine, and is usually less work than naming each object.

Coverage is what turns unknown into a real answer. A resource whose scope no state source covers cannot be judged managed or unmanaged, so the honest answer is unknown — and adding the source is what resolves it.

Removing one

Section titled “Removing one”

Delete a state source to stop reading it. Mappings that rested on it lose their evidence and fall back to unknown on the next reconciliation, which is the correct result: the evidence is genuinely gone.

Where to go next

Section titled “Where to go next”