Keeping Secrets Out of State with Ephemeral Values and Write only Arguments

So far you’ve used important Terraform security controls: marking variables as sensitive, keeping secrets in environment variables, encrypting remote state, and integrating external secret managers. Those are essential defenses — but one risk often remains: secret values still appear in the Terraform state file. Even when remote state is encrypted, anyone with backend access (or permission to run Terraform) can often read the decrypted state. Sensitive variables hide values from CLI and UI output, and external secret managers centralize secret storage — but secret values can still be written into state. For example, a simplified Terraform state JSON may include the same secret in both outputs and resource attributes:

{
  "version": 4,
  "terraform_version": "1.12.0",
  "serial": 1,
  "lineage": "example-lineage",
  "outputs": {
    "database_password_output": {
      "value": "MySuperSecretPassword123!",
      "type": "string",
      "sensitive": true
    }
  },
  "resources": [
    {
      "mode": "managed",
      "type": "aws_db_instance",
      "name": "main",
      "provider": "provider[\"registry.terraform.io/hashicorp/aws\"]",
      "instances": [
        {
          "schema_version": 0,
          "attributes": {
            "password": "MySuperSecretPassword123!"
          }
        }
      ]
    }
  ]
}

That secret in state is exactly the exposure we want to eliminate. This guide explains how to keep secrets entirely out of state using ephemeral values and write-only arguments, when to use them, and their limitations.

What are ephemeral values?

Ephemeral values exist only in memory during Terraform execution (init, plan, apply). They are never written to plan or state files. Each run computes ephemeral values when needed and then discards them from memory after use. Provider plugins, language extensions, or newer Terraform features may support marking variables or data fetches as ephemeral (for example, ephemeral = true). Availability and syntax vary by provider and Terraform version — always consult the provider docs and Terraform release notes for exact, up-to-date support. Illustrative variable declaration (check your provider/version for exact syntax):

variable "database_password" {
  description = "Password for the database"
  type        = string
  sensitive   = true
  ephemeral   = true
}

Combining sensitive = true and ephemeral = true provides two benefits:

sensitive hides the value from CLI and UI output.
ephemeral (where supported) prevents the value from being written to plan or state files.

You can use ephemeral values in several Terraform contexts where supported: locals, provider blocks, ephemeral-style resources or data fetches, ephemeral variables/outputs for modules, provisioner blocks (rare and often discouraged), and write-only arguments on managed resources. Not every provider or resource supports ephemeral features — check provider docs.

A presentation slide titled "Where Can I Use Ephemeral Values?" with purple cards listing examples like Local Values, Provider Blocks, Ephemeral Resources, Ephemeral Variables, Ephemeral Outputs, Provisioner Blocks, and Write-Only Arguments.

Ephemeral values are not universally supported. The main restriction is that ephemeral values cannot be used for ordinary resource arguments that must be persisted to state. Always verify provider support and syntactic details in the provider documentation or Terraform release notes.

Ephemeral values cannot be used in regular resource arguments

Managed resource instances must persist between Terraform phases, so ephemeral values are invalid in ordinary persisted resource attributes. In implementations that enforce this restriction, using an ephemeral variable in a persistent resource argument triggers an error:

# Does NOT work — ephemeral value used in a persisted resource attribute
resource "azurerm_mssql_server" "db" {
  administrator_login_password = var.db_password    # var.db_password is ephemeral
  # ...
}

Console error (illustrative):

Error: Invalid use of ephemeral value

Ephemeral values are not valid in resource arguments,
because resource instances must persist between Terraform phases.

This limitation is precisely why some providers implement write-only arguments: they let you pass ephemeral secrets into a resource for create/update operations without persisting the secret in state.

Provider blocks and ephemeral variables

Provider blocks frequently accept credentials and tokens. Provider configuration is not persisted to resource state the same way resource attributes are, so ephemeral variables are a good fit for provider credentials when supported. Illustrative example:

variable "github_owner" {
  type        = string
  description = "GitHub org"
}

variable "github_token" {
  type        = string
  description = "GitHub token"
  sensitive   = true
  ephemeral   = true
}

provider "github" {
  owner = var.github_owner
  token = var.github_token
}

Here var.github_token exists in memory long enough to authenticate the provider and is then discarded. This reduces exposure in logs, plan files, and state — if the provider and runtime implement ephemeral handling as shown.

Ephemeral resources

Some providers and extensions offer an ephemeral block type (or provider-specific constructs) that behaves like a data fetch but stores retrieved secrets only in memory. Ephemeral fetches are opened and closed during execution; logs or debug output may indicate when an ephemeral fetch occurred. Compare a regular data source (can be recorded in state) with an ephemeral-style resource (not stored). Example syntax is provider-dependent:

# Regular data source (can be recorded in state)
data "azurerm_key_vault_secret" "db" {
  name         = "database-password"
  key_vault_id = var.key_vault_id
}

# Ephemeral resource (NOT stored in state) — illustrative syntax
ephemeral "azurerm_key_vault_secret" "db" {
  name         = "database-password"
  key_vault_id = var.key_vault_id
}

When you need Terraform to fetch a secret at runtime without persisting it, use an ephemeral-style fetch where supported. Typical use cases:

Fetching secrets from HashiCorp Vault or other secret managers without writing them to state.
Reading temporary credentials used only for a single operation.
Retrieving dynamic tokens that frequently change (even between plan and apply).

Provider authors decide which data sources/resources have ephemeral equivalents and the exact syntax. Not every data source has an ephemeral counterpart — consult the provider documentation.

Write-only arguments — using ephemeral values with regular resources

Write-only arguments allow you to pass ephemeral values to Terraform-managed resources for creation or updates without recording the secret in state or plan files. The exact argument names and behavior are provider-defined. A common provider pattern is a pair of arguments: a write-only secret field and an integer *_wo_version (or similarly named) version field. The version field lets Terraform detect that a change was intended so it can trigger an update without needing to read the secret back from state. Illustrative example:

resource "aws_db_instance" "test" {
  instance_class        = "db.t3.micro"
  allocated_storage     = 5
  engine                = "postgres"
  username              = "example"
  skip_final_snapshot   = true

  # write-only secret and version (provider-specific names)
  password_wo           = var.ephemeral_pass
  password_wo_version   = 1
}

High-level flow:

Terraform (or the provider plugin) retrieves secrets into RAM (for example via an ephemeral fetch).
Terraform uses those secrets to create or update the resource, sending the secret to the provider’s API.
Terraform writes non-secret resource metadata to state, but does not store the secret value.
After the operation completes, Terraform flushes the secret from memory.

A diagram titled "Write-Only Arguments" showing Terraform retrieving secrets from a secrets manager into RAM and using them to build Google Cloud resources (Cloud Spanner) without writing the secrets to the state file. It highlights three steps: retrieve secrets (ephemeral), build infrastructure (resource block), and do not store secrets in state.

Side-by-side comparison — normal vs write-only: Regular resource (secret stored in state):

resource "aws_db_instance" "test" {
  instance_class        = "db.t3.micro"
  allocated_storage     = 5
  engine                = "postgres"
  skip_final_snapshot   = true
  username              = "db-admin"
  password              = var.database_password   # persists to state
}

Write-only resource (secret not stored in state, illustrative syntax):

resource "aws_db_instance" "test" {
  instance_class        = "db.t3.micro"
  allocated_storage     = 5
  engine                = "postgres"
  skip_final_snapshot   = true
  username              = "db-admin"
  password_wo           = var.ephemeral_pass
  password_wo_version   = 1
}

Quick reference: when to use which pattern

Pattern	Purpose	Example use cases
Ephemeral variable	Keep a sensitive value in RAM only during execution	Provider credentials, transient tokens
Ephemeral data/resource	Fetch secret into memory without writing to state	Vault secrets, short-lived credentials
Write-only arguments	Pass ephemeral secret to a managed resource without persisting it	Database passwords, service account keys during creation

Key points to remember

Ephemeral values exist only in memory and — where the provider/runtime supports them — are never written to plan or state files.
Write-only arguments (provider-defined) let you pass ephemeral secrets to regular managed resources without persisting the secret value in state.
A version or change-detection argument usually accompanies write-only fields so Terraform can detect updates.
Provider and Terraform version support varies. Not all providers or resources support ephemeral resources or write-only arguments — consult provider documentation for exact syntax and behavior.

Ephemeral values and write-only arguments are powerful tools for keeping secrets out of state, but availability and argument names depend on provider support and Terraform version. Always check the provider’s documentation and release notes for supported write-only fields and ephemeral resource types.

Recommended defense-in-depth strategy

Putting these techniques together produces a robust approach to secret management in Terraform:

Mark sensitive variables with sensitive = true to hide values in CLI and UI output.
Use environment variables and external secret managers (e.g., HashiCorp Vault) to avoid committing secrets to version control.
Encrypt remote state and restrict backend access to minimize who can read state.
Use ephemeral fetches or provider-supported ephemeral constructs to retrieve secrets at runtime.
When supported by the provider, use write-only arguments to pass secrets to resources without recording them in state.

Recommended patterns for integrating HashiCorp Vault and other secret managers into production Terraform workflows are an important follow-up topic. For provider-specific guidance and current support status, consult:

Terraform documentation and release notes: https://github.com/hashicorp/terraform/releases
Terraform Registry and provider docs: https://registry.terraform.io/
HashiCorp Vault documentation: https://developer.hashicorp.com/vault

Course Introduction

Preparing Your Environment

Terraform Foundations

The Core Terraform Workflow

Terraform CLI

Terraform File Structure and Organization

Terraform Configuration - Fundamentals

Understading and Managing Terraform State

Marking Code Reusable

Refactoring Terraform State

Terraform Modules

Managing Resource Behavior and Dependencies

Securing Terraform Configurations

Terraform Troubleshooting

HCP Terraform

Keeping Secrets Out of State with Ephemeral Values and Write only Arguments

What are ephemeral values?

Ephemeral values cannot be used in regular resource arguments

Provider blocks and ephemeral variables

Ephemeral resources

Write-only arguments — using ephemeral values with regular resources

Quick reference: when to use which pattern

Key points to remember

Recommended defense-in-depth strategy

Watch Video

​What are ephemeral values?

​Ephemeral values cannot be used in regular resource arguments

​Provider blocks and ephemeral variables

​Ephemeral resources

​Write-only arguments — using ephemeral values with regular resources

​Quick reference: when to use which pattern

​Key points to remember

​Recommended defense-in-depth strategy

Watch Video

What are ephemeral values?

Ephemeral values cannot be used in regular resource arguments

Provider blocks and ephemeral variables

Ephemeral resources

Write-only arguments — using ephemeral values with regular resources

Quick reference: when to use which pattern

Key points to remember

Recommended defense-in-depth strategy