By Sebastian Stadil — 22 May 2025

Understanding ephemerality in Terraform

Ephemerality in Terraform represents a significant advancement in infrastructure-as-code security, introduced in Terraform v1.10 (November 2024) to solve a critical security challenge: preventing sensitive information from being stored in plaintext within Terraform state files. This feature enables secure handling of credentials, tokens, and other sensitive data without compromising the advantages of infrastructure as code.

What ephemerality means in Terraform resources

Ephemerality in Terraform refers to temporary values or resources that exist only during runtime execution and are deliberately not persisted in Terraform's state or plan files. This concept fundamentally changes how Terraform handles sensitive information.

The core principles of ephemerality include:

Temporary existence: Ephemeral values only exist during the current Terraform operation
Non-persistence guarantee: Terraform ensures these values will never be written to state files or plan artifacts
Security by design: Addresses the longstanding challenge of sensitive data management
Runtime-only visibility: Values are accessible only during execution and within specific contexts

Unlike regular Terraform resources which maintain state between operations, ephemeral resources are recreated each time they're needed. This makes them ideal for handling sensitive information like database passwords, API keys, and authentication tokens that should never be stored in plaintext.

Ephemeral blocks: purpose, syntax, and functionality

Ephemeral blocks were introduced in Terraform v1.10 as a new resource mode alongside managed resources and data sources. They declare temporary resources that exist only during execution phases.

Syntax of ephemeral blocks

ephemeral "<resource_type>" "<resource_name>" {
  <attributes>
  <meta-arguments>
}

This syntax resembles standard resource blocks but with the ephemeral keyword indicating its temporary nature.

Purpose and functionality

Ephemeral blocks serve several key purposes:

Secure handling of sensitive information without state persistence
Temporarily accessing external data (like secrets from a vault)
Opening and managing connections to external systems during operations
Generating one-time values needed during an operation

Technical implementation

Ephemeral resources participate in Terraform's dependency graph similar to standard resources but with a unique lifecycle:

Opening: When Terraform needs an ephemeral resource's value, it "opens" the resource by executing its logic to fetch or generate data
Renewing: For ephemeral resources that may expire during an operation (like temporary tokens), Terraform can periodically renew them
Closing: Once no longer needed, Terraform explicitly "closes" the resource, allowing proper cleanup

This lifecycle is contained entirely within a single Terraform operation, with no persistence between operations.

Write-only arguments in Terraform

Write-only arguments, introduced in Terraform v1.11 (early 2025), complement ephemeral resources by providing a way to use sensitive values in standard resource blocks while maintaining security.

Definition and characteristics

Write-only arguments are managed resource attributes that:

Can only be written to, not read
Are never persisted in state or plan files
Accept both ephemeral and non-ephemeral values
Follow a naming convention with the _wo suffix

Implementation example

resource "aws_db_instance" "example" {
  instance_class = "db.t3.micro"
  allocated_storage = "5"
  engine = "postgres"
  username = "example"
  skip_final_snapshot = true
  
  # Write-only password argument
  password_wo = ephemeral.random_password.db_password.result
  password_wo_version = 1
}

Versioning mechanism

Since Terraform cannot track changes to write-only arguments (as they're not in state), they include a versioning mechanism:

Each write-only argument is paired with a version attribute (e.g., password_wo_version)
The version value is stored in state, while the actual sensitive value is not
To update a write-only argument, you increment its version number
The provider uses the version change to determine when to apply the new write-only value

Practical examples and use cases for ephemeral resources

AWS Secrets Manager example

This example demonstrates generating a random password, storing it in AWS Secrets Manager, and using it to configure a database:

# Generate ephemeral random password
ephemeral "random_password" "db_password" {
  length           = 16
  override_special = "!#$%&*()-_=+[]{}<>:?"
}

# Store the password in AWS Secrets Manager
resource "aws_secretsmanager_secret" "db_password" {
  name = "db_password"
}

# Set the secret value using write-only argument
resource "aws_secretsmanager_secret_version" "db_password" {
  secret_id         = aws_secretsmanager_secret.db_password.id
  secret_string_wo  = ephemeral.random_password.db_password.result
  secret_string_wo_version = 1
}

# Retrieve the password from Secrets Manager (ephemeral)
ephemeral "aws_secretsmanager_secret_version" "db_password" {
  secret_id = aws_secretsmanager_secret_version.db_password.secret_id
}

# Use the password to configure the database
resource "aws_db_instance" "example" {
  instance_class    = "db.t3.micro"
  allocated_storage = "5"
  engine            = "postgres"
  username          = "example"
  skip_final_snapshot = true
  
  # Use the ephemeral password (write-only argument)
  password_wo      = ephemeral.aws_secretsmanager_secret_version.db_password.secret_string
  password_wo_version = 1
}

Dynamic provider configuration

Using ephemeral resources to configure providers without storing credentials:

# Access credentials ephemerally
ephemeral "aws_secretsmanager_secret_version" "creds" {
  secret_id = aws_secretsmanager_secret.creds.id
}

# Parse credentials
locals {
  credentials = jsondecode(ephemeral.aws_secretsmanager_secret_version.creds.secret_string)
}

# Configure provider with ephemeral credentials
provider "postgresql" {
  host     = var.db_host
  port     = var.db_port
  username = local.credentials.username
  password = local.credentials.password
}

Temporary access tokens for deployment

Using ephemeral resources to generate temporary tokens for deployment processes:

ephemeral "google_service_account_access_token" "default" {
  target_service_account = google_service_account.default.email
  scopes                 = ["cloud-platform"]
  lifetime               = "3600s"
}

provider "kubernetes" {
  host  = "https://${google_container_cluster.example.endpoint}"
  token = ephemeral.google_service_account_access_token.default.access_token
}

Best practices and common patterns

Security best practices

Reference control: Only reference ephemeral resources in allowed contexts (provider blocks, locals, other ephemeral resources, write-only arguments)
Version management: For write-only arguments, maintain version numbers to control when updates occur
OIDC integration: Use OIDC for secure, tokenless authentication in CI/CD pipelines
Lifecycle monitoring: Ensure ephemeral resources are closed promptly to avoid lingering access

Implementation best practices

Dependency management: Model your configuration to ensure proper execution order with dependency graphs
Defer when needed: Use Terraform's deferring logic to handle values not known until apply time
Validation: Include validation in ephemeral resource blocks to ensure correct inputs
Error handling: Implement proper error handling for when ephemeral resources cannot be accessed

Common design patterns

Pattern 1: Ephemeral secret generation and storage

# 1. Generate ephemeral secret
ephemeral "random_password" "secret" {
  length = 16
}

# 2. Store in secure storage with write-only argument
resource "aws_secretsmanager_secret_version" "secret" {
  secret_id         = aws_secretsmanager_secret.secret.id
  secret_string_wo  = ephemeral.random_password.secret.result
  secret_string_wo_version = 1
}

# 3. Access secret ephemerally when needed
ephemeral "aws_secretsmanager_secret_version" "secret_retrieval" {
  secret_id = aws_secretsmanager_secret.secret.id
}

Pattern 2: Write-only resource configuration

# 1. Access sensitive data ephemerally
ephemeral "azurerm_key_vault_secret" "api_key" {
  name        = "api-key"
  key_vault_id = azurerm_key_vault.vault.id
}

# 2. Configure resource with write-only argument
resource "azurerm_function_app" "example" {
  # ... other configuration ...
  
  app_settings_wo = {
    "API_KEY" = ephemeral.azurerm_key_vault_secret.api_key.value
  }
  app_settings_wo_version = 1
}

How ephemeral resources differ from regular Terraform resources

The fundamental differences between ephemeral and standard resources include:

Aspect	Standard Resources	Ephemeral Resources
State Storage	Stored in state files	Never stored in state
Persistence	Persists between operations	Only exists during current operation
Planning	Used in plan calculations	Generated during both plan and apply phases
Referencing	Can be referenced anywhere	Can only be referenced in specific contexts
Updates	Updated based on configuration differences	Always freshly created in each phase

Dependency handling

Ephemeral resources participate in Terraform's dependency graph but with special handling:

They can depend on standard resources and data sources
Standard resources can depend on ephemeral resources in specific contexts (write-only arguments)
If an ephemeral resource depends on a value not known during planning, Terraform defers its execution to apply phase

Reference constraints

Ephemeral resources can only be referenced in specific contexts:

Other ephemeral resources
Provider configurations
Local values (which become ephemeral by association)
Provisioner blocks
Write-only arguments in managed resources

Limitations and considerations for ephemeral resources

Usage restrictions

Limited contexts: Ephemeral resources can only be referenced in specific ephemeral contexts
No persistence mechanism: By design, there's no way to reverse ephemerality or persist values once they're declared ephemeral
No provisioner support: Ephemeral resources don't support the provisioner meta-argument

Provider support limitations

Limited provider availability: Only select providers currently support ephemeral resources:
- AWS (aws_secretsmanager_secret_version, aws_lambda_invocation, aws_kms_secrets)
- Azure (azurerm_key_vault_secret, azurerm_key_vault_certificate)
- GCP (google_service_account_access_token, google_service_account_id_token)
- Kubernetes (kubernetes_token_request, kubernetes_certificate_signing_request)
- Random provider
Inconsistent implementation: Even HashiCorp's own Vault provider initially lacked ephemeral resource support

Technical constraints

Dependency requirements: Ephemeral resources require all their dependencies to exist at runtime
Handling unknown values: If an ephemeral resource references a value unknown at plan time, execution is deferred to apply time
Write-only limitations: Write-only arguments cannot be used with set attributes, set nested attributes, or set nested blocks

Recent developments in ephemeral functionality

Terraform 1.10 (November 2024)

Introduced the core concept of ephemeral resources:

Ephemeral resources: A new resource type that exists only during execution
Ephemeral input and output variables: Variables that can be marked as ephemeral
The ephemeralasnull function: Converts ephemeral values to non-ephemeral null values

Terraform 1.11 (Early 2025)

Expanded the ephemeral concept with write-only arguments:

Write-only arguments: Allow ephemeral values to be used in regular resource blocks
Version tracking for write-only arguments: A mechanism for controlled updates
End-to-end ephemerality: Complete flows without persisting sensitive data

Performance improvements

Refactored plan changes and reduced repeated decoding in resource state
Optimized plan and apply operations for large numbers of resource instances
Improvements to dependency resolution for ephemeral resources

Provider integration and implementation differences

Different cloud providers implement ephemeral resources with unique patterns tailored to their services:

AWS

Focuses on secrets management and invocation patterns:

Secrets Manager integration: aws_secretsmanager_secret_version for ephemeral access to secrets
Stateless execution: aws_lambda_invocation for invoking Lambda functions without storing responses
KMS integration: aws_kms_secrets for ephemeral decryption

Azure

Centers around key vault integration:

Key Vault secrets: azurerm_key_vault_secret for ephemeral access to secrets
Certificate management: azurerm_key_vault_certificate for certificate access without persistence

Google Cloud Platform

Emphasizes service account authentication:

Token generation: Resources for generating various token types
Key management: Service account key handling without persistence

Kubernetes

Focuses on authentication and certificate management:

Token requests: Generates short-lived authentication tokens
Certificate signing: Handles CSRs ephemerally

Real-world scenarios where ephemeral resources shine

End-to-end security for CI/CD pipelines

When combined with OIDC authentication:

Eliminates need for static credentials in CI/CD environments
Allows temporary access tokens for infrastructure provisioning
Integrates with cloud provider identity services
Leaves no sensitive data in artifacts or state files

Secrets rotation workflows

Ephemeral resources enable sophisticated secrets rotation:

Generate new credentials ephemerally
Store in secrets managers with write-only arguments
Retrieve and use ephemerally in dependent resources
Rotate by incrementing the version attribute

Ephemeral SSH tunnels

One of the most innovative applications:

Establishes secure tunnels to otherwise inaccessible resources during operations
Automatically closed once the operation completes
Enables secure connectivity without persistent credentials

Database credentials management

A common and powerful use case:

Generate secure database passwords ephemerally
Store them in a secrets manager without exposing in state
Retrieve them when needed to configure databases
Update credentials securely using the version mechanism

In conclusion, ephemerality in Terraform represents a major advancement in infrastructure-as-code security. By providing a mechanism to handle sensitive data without persisting it, Terraform has addressed one of the most significant security challenges in infrastructure automation. As more providers add support and the implementation continues to mature, ephemeral resources will likely become a standard pattern for sensitive data handling in Terraform deployments.