Terraform Security and Governance · Topic 1 of 3

Secrets, Ephemeral Values and Rotation

Terraform Professional (002): keep secrets out of state with ephemeral values and write-only arguments, protect state, and rotate secrets safely.

  • 5 min
  • Includes a diagram
In a nutshell
  • Sensitive values are still stored in state and plan files.
  • Ephemeral values and write-only arguments are never stored in state or plan files.
  • A root module output cannot be ephemeral; a child module output can.

What it is

A secret can leak from four places: configuration in version control, CLI output, the plan file and the state file. Good practice is to never hardcode a secret, fetch it at run time from a secrets manager, keep it out of state where the provider allows, and protect state where it does not.

Rotation is the other half of the job. When a secret changes, you must know how the new value reaches the resource, and what Terraform will do on the next plan.

How it works

Where a value ends up

A secret marked sensitive or passed to a normal resource argument is stored in plan and state. An ephemeral value passed to a write-only argument such as password_wo is never stored in plan or state.

TechniqueHidden in outputIn plan and stateSince
sensitive = trueYesYes0.14
ephemeral = true on a variable or child module outputOnly if also sensitiveNo1.10
ephemeral blockOnly if marked sensitiveNo1.10
Write-only argument such as password_woNot applicableNo1.11

sensitive only redacts display, and anything derived from a sensitive value is also redacted. terraform output -json and -raw still print sensitive values in plain text.

Ephemeral values can only flow into certain places: locals, ephemeral variables, child module ephemeral outputs, write-only arguments, other ephemeral blocks, provider configuration, and provisioner and connection blocks. Anywhere else, such as a normal resource argument or a root module output, is an error.

Reading from a secrets manager

A data source returns the current secret, but its result is written to state. An ephemeral block reads the same secret without storing it, if the provider offers one.

ephemeral "vault_kv_secret_v2" "db" {
  mount = "kv"
  name  = "prod/db"
}

resource "aws_db_instance" "main" {
  # other arguments omitted
  password_wo         = tostring(ephemeral.vault_kv_secret_v2.db.data.password)
  password_wo_version = 2
}
Secret in Vaultephemeral blockTerraform runwrite only argumentProvidersets the passwordStateholds only the version

Rotation patterns

SituationWhat happensWhat to do
Write-only argumentTerraform stores nothing to compareIncrease password_wo_version so the new value is sent
Value read by a data sourceRead again on each plan, so dependents show an updateRun plan and apply; the value stays in state
Another system rotates a normal argumentThe plan proposes setting it backUse ignore_changes
Replace an object when something changesNeeds a managed resource referenceUse replace_triggered_by, with terraform_data wrapping a plain value

Trace the ignore_changes case with this configuration.

resource "aws_db_instance" "main" {
  # other arguments omitted
  password = var.initial_password

  lifecycle {
    ignore_changes = [password]
  }
}

On create, Terraform uses var.initial_password, because ignore_changes applies to updates only. After a manager rotates the password, the next plan proposes no password change. The initial value is still in state, so this suits a throwaway bootstrap value only.

To record an out-of-band change in state without touching the object, run terraform apply -refresh-only, which replaces terraform refresh.

Protecting state and plan files

  • Store state in a remote backend, restrict access and track access with audit logs.
  • Encrypt at rest: set encrypt on the S3 backend; HCP Terraform encrypts state at rest and uses TLS in transit.
  • For control of the key, HCP Terraform Premium offers hold your own key, which encrypts state and plan files with your own key management system.
  • Never commit state, and treat saved plan files as secrets.

How the exam asks about this

  • "A scan finds the database password in state although the variable is marked sensitive." Use an ephemeral value with a write-only argument; sensitive only hides output.
  • "The password changed in Vault, and the write-only argument did not update." Increase the version argument, such as password_wo_version.
  • "A rotation tool changes a password, and every plan tries to change it back." Add ignore_changes for that argument.

What to remember for the exam

  • Sensitive values are still stored in state and plan files.
  • Ephemeral values and write-only arguments are never stored in state or plan files.
  • A root module output cannot be ephemeral; a child module output can.
  • A data source that reads a secret writes it to state; an ephemeral block does not.
  • ignore_changes affects updates only, never the initial create.
  • Provider support varies, so check the registry for ephemeral blocks and write-only arguments.
Watch out

Changing only the value passed to a write-only argument does nothing on its own. Terraform keeps no copy to compare, so the provider sees a new value only when the matching version argument changes.

Common mistakes

Treating sensitive as encryption. The argument changes what is displayed, not what is stored. Anyone who can read the state file can read the value.

Assuming a secrets manager keeps the value out of state. Vault protects the source, but a data source copies the result into state. Use an ephemeral block to avoid the copy.

Passing an ephemeral value to a normal argument. Terraform raises an error, because that argument would be saved in state. Use the write-only argument, such as password_wo rather than password.

Check yourself

  • Does marking a variable as sensitive keep it out of the state file?

    No. It only redacts the value from CLI and UI output, and the value is still stored in state and plan files.

  • How do you send a rotated password through a write-only argument?

    Pass the new value and change the companion version argument, such as password_wo_version, so the provider receives it during apply.

  • Which block reads a Vault secret without saving it in state?

    An ephemeral block, such as ephemeral "vault_kv_secret_v2", whose result can flow into a write-only argument.

Topic 1 of 3 in Terraform Security and Governance

Test yourself on Terraform Security and Governance

The full HashiCorp Terraform Infrastructure Engineer Professional question bank has 600 questions, with timed practice exams and an explanation for every answer.

This study guide is independent and is not affiliated with, endorsed by, or sponsored by HashiCorp. Vendor names, certification names and exam codes are trademarks of their respective owners and are used for identification only.