OpenTofu State Encryption Key Rotation Prompt
Rotate OpenTofu state-encryption keys safely using the `fallback` method so existing encrypted state can still be read while new writes use the new key — with zero downtime.
- Target user
- Engineers operating OpenTofu with state encryption enabled
- Difficulty
- Advanced
- Tools
- Claude, ChatGPT
The prompt
You are an OpenTofu expert who runs state encryption in production and knows that rotating the encryption key is a two-phase operation built on the `fallback` block: you bring the new key online as primary while keeping the old key as a decrypt-only fallback, run once to re-encrypt, then retire the old key. Done wrong, you lock yourself out of your own state.
I will provide:
- The current encryption method config (key provider: PBKDF2 passphrase, AWS KMS, GCP KMS, etc.)
- Why we're rotating ([ROTATION_REASON] — scheduled rotation, suspected exposure, key-provider migration)
- Whether multiple workspaces/state files share the key
Your job:
1. **Capture a safe baseline** — before touching anything, take a decryptable backup of current state (`tofu state pull`) and confirm you can still read it. State that an irrecoverable mistake here means lost state.
2. **Stage the new key as fallback** — show the `terraform { encryption { ... } }` block with the new key provider as the `method`/primary and the *old* key wired into `fallback`, so OpenTofu can still decrypt existing state but encrypts new writes with the new key. Explain the direction precisely (new = primary, old = fallback).
3. **Force the re-encryption pass** — describe the operation (a plan/apply or a state write) that rewrites the state under the new key, and how to confirm the state is now decryptable with only the new key.
4. **Retire the old key** — remove the `fallback` block once every shared state file has been re-encrypted, and verify a fresh run still works with the new key alone. Cover the multi-workspace case: don't drop the fallback until *all* of them are migrated.
5. **Rollback plan** — describe exactly how to restore from the baseline backup if any step fails mid-rotation.
Output as: (a) the backup/verification commands, (b) the encryption block for the fallback phase, (c) the re-encryption step, (d) the encryption block for the final single-key phase, (e) the per-workspace checklist and the rollback procedure.
This operation can permanently lock you out of state — verify each phase against a non-production state file first, and never remove the fallback until every state file is confirmed re-encrypted.
Why this prompt works
State encryption is one of OpenTofu’s flagship features, but the documentation and most write-ups stop at “turn it on.” Rotation — which is mandatory under any real key-management policy and urgent after a suspected exposure — is where teams get hurt, because the failure mode isn’t a bad plan, it’s permanently losing the ability to decrypt your own state. The prompt is organized around the only safe pattern for this: the two-phase fallback rotation, where the new key becomes primary while the old key stays available purely to decrypt existing state until everything is rewritten.
The detail the prompt insists on getting right is the direction of the fallback, because it’s easy to invert. New key as primary, old key as fallback, means new writes use the new key while old state remains readable; swap them and you’ve done nothing useful. It also drags out the multi-workspace reality that quick guides ignore: if several state files share a key, the old key cannot be retired until every one of them has been re-encrypted, and dropping the fallback early bricks the stragglers. Making the model produce a per-workspace checklist turns that from a known-after-the-fact disaster into a managed rollout.
Most importantly, the prompt treats this as a recoverable operation by design. A verified decryptable backup taken before any change, plus an explicit rollback procedure, plus a rehearsal against non-production state, are what let an engineer trust an AI-drafted rotation. The AI handles the fiddly encryption-block syntax and sequencing; the human verifies each phase against real state and keeps an escape hatch open the whole way through.