Written by Albert Friedman
on 

Ephemeral secrets and state encryption: a practical intro to OpenTofu’s safer secret handling

OpenTofu has quickly evolved beyond being a drop-in Terraform fork — it’s adding features that rethink how secret and transient data are handled in infrastructure-as-code. Two recent additions are especially important for anyone managing secrets with Terraform-style workflows: built-in state encryption (available since early releases) and a new “ephemeral” model that avoids persisting confidential values to state at all (available in 1.11 beta/nightlies). This article explains what these features do, when to use each, and practical patterns and migration tips to get started safely. (linuxfoundation.org)

Why caring about state and secrets matters

OpenTofu’s two complementary approaches

How ephemeral values work (conceptual)

Simple ephemeral example (This is a compact illustration based on current OpenTofu docs — don’t run this in production without reading provider docs and release notes.)

ephemeral "aws_secretsmanager_random_password" "pw" {
  # provider-specific schema / args, if applicable
}

resource "kubernetes_secret_v1" "admin" {
  metadata {
    name      = "admin"
    namespace = "my-app"
  }

  # write-only attribute: send password into the secret, but don't store it in state
  data_wo = {
    username = "admin"
    password = ephemeral.aws_secretsmanager_random_password.pw.random_password
  }

  data_wo_revision = 1
  type             = "kubernetes.io/basic-auth"
}

Notes:

State encryption: when you still need persistence There are valid reasons to store secrets in state (e.g., long-lived credentials that must be tracked, or outputs that other stacks read via remote state). OpenTofu’s state encryption protects those values by encrypting the plan/state blobs client-side before they are sent to the backend. Key takeaways:

terraform {
  encryption {
    key_provider "external" "my_k" {
      command = ["op", "read", "op://my/statekey"]
    }

    method "aes_gcm" "state" {
      keys = key_provider.external.my_k
    }

    state {
      method = method.aes_gcm.state
    }
  }
}

Practical patterns — when to choose ephemeral vs encrypted state

Limitations and cautions

Migration and operational tips (safe steps)

  1. Back up state before you touch anything. Always. Use S3 versioning, DB snapshots, or copy local tfstate files. If something goes wrong, you’ll want to revert. The OpenTofu migration guides emphasize backup and careful testing. (opentofu.org)
  2. Try the ephemeral path in a disposable environment:
    • Build a small test module that generates a secret ephemeral, writes it into a secrets backend (Vault/SecretsManager/Kubernetes), and does not persist it in state.
    • Verify you can rotate and recover via the backend, not via OpenTofu state. (opentofu.org)
  3. If you must store values, enable state encryption and integrate an external key provider (KMS or command). Test key rotation and decryption in CI and long-lived workers. (opentofu.org)
  4. CI/CD considerations:
    • Ensure transient ephemeral operations in CI have access to the providers they need (e.g., credentials to fetch ephemeral tokens), but don’t leak them into logs. Use masked variables and restrict logs.
    • For global provider caches and parallel runs, OpenTofu 1.10+ improved provider cache locking to be safe in CI. If you run many parallel inits, use the global provider cache and the filesystem locking options. (opentofu.org)
  5. Read provider docs — provider authors decide whether to support ephemeral semantics. If your team depends on ephemeral, engage provider maintainers or submit PRs. (opentofu.org)

A short checklist before you go to production

Why this is a meaningful shift OpenTofu’s combination of ephemeral values and built-in state encryption is an explicit attempt to reduce the risk profile of IaC workflows:

Where to learn more and next steps

Closing thoughts Secrets are the most sensitive part of your infrastructure graph. OpenTofu’s ephemeral and write-only concepts represent a practical way to reduce the attack surface by not storing secrets when you don’t have to — while state encryption protects the cases where persistence is necessary. Start small: prototype ephemeral flows in a test workspace, validate your secret store workflows, and only then roll changes into critical workloads. And as always, back up your state before making changes. (opentofu.org)

Further reading and references

If you’d like, I can: