Ephemeral resources are a newer Terraform feature (announced at HashiDays 2025) that solves a long-standing problem: how to use secrets during a Terraform run without storing them in state. Database passwords, API tokens, session credentials — values you need during apply but don’t want persisted anywhere.
The Problem
With regular resources and data sources, everything goes into state:
# ❌ This stores the password in terraform.tfstate!
resource "random_password" "db" {
length = 32
}
# ❌ This stores the secret value in state too!
data "aws_secretsmanager_secret_version" "db" {
secret_id = "prod/database/password"
}
Anyone with state access can read these values. Even with state encryption, the secret persists longer than needed.
Ephemeral Resources
Ephemeral resources exist only during the Terraform operation. They’re never written to state:
# ✅ Password generated but NOT stored in state
ephemeral "random_password" "db" {
length = 32
}
# Use it in a resource that needs it
resource "aws_db_instance" "main" {
identifier = "production"
engine = "postgres"
password = ephemeral.random_password.db.result # Used during apply, not stored
}
How Ephemeral Resources Work
- Created at the start of a
planorapplyoperation - Used by other resources that reference them
- Destroyed when the operation completes
- Never stored in state, plan files, or logs
terraform apply
├── Create ephemeral resources (in memory only)
├── Use values in resource configurations
├── Apply changes to real resources
└── Ephemeral values discarded ← Gone forever
Ephemeral vs Data Sources
| Feature | Data Source | Ephemeral Resource |
|---|---|---|
| Stored in state | ✅ Yes | ❌ No |
| Available after apply | ✅ Yes (in state) | ❌ No |
| Refreshed on plan | ✅ Yes | ✅ Yes |
| Suitable for secrets | ⚠️ Secret in state | ✅ Never persisted |
| Can trigger updates | ✅ Yes | ❌ No |
| Use case | Read external data | Temporary secrets/tokens |
# Data source — value stored in state
data "aws_secretsmanager_secret_version" "db" {
secret_id = "prod/db/password"
}
# terraform.tfstate contains the password 😬
# Ephemeral — value NOT stored in state
ephemeral "aws_secretsmanager_secret_version" "db" {
secret_id = "prod/db/password"
}
# terraform.tfstate does NOT contain the password ✅
Use Cases
Database Passwords
ephemeral "random_password" "db" {
length = 32
special = true
override_special = "!#$%&*()-_=+[]{}<>:?"
}
resource "aws_db_instance" "main" {
identifier = "production"
engine = "postgres"
engine_version = "16.3"
instance_class = "db.r6g.large"
password = ephemeral.random_password.db.result
# Store the password in Secrets Manager for apps to read
# But it's NOT in Terraform state
}
resource "aws_secretsmanager_secret_version" "db" {
secret_id = aws_secretsmanager_secret.db.id
secret_string = ephemeral.random_password.db.result
}
Short-Lived API Tokens
ephemeral "vault_generic_secret" "api_token" {
path = "secret/data/api-token"
}
resource "aws_lambda_function" "api" {
function_name = "api-handler"
# ...
environment {
variables = {
API_TOKEN = ephemeral.vault_generic_secret.api_token.data["token"]
}
}
}
Session Credentials
ephemeral "aws_sts_session_token" "deploy" {
duration_seconds = 900 # 15 minutes
}
# Use temporary credentials for a specific provider
provider "aws" {
alias = "deploy"
region = "us-east-1"
access_key = ephemeral.aws_sts_session_token.deploy.access_key
secret_key = ephemeral.aws_sts_session_token.deploy.secret_key
token = ephemeral.aws_sts_session_token.deploy.session_token
}
CI/CD Pipeline Secrets
ephemeral "aws_secretsmanager_secret_version" "deploy_key" {
secret_id = "ci/deploy-key"
}
resource "null_resource" "deploy" {
provisioner "local-exec" {
command = "deploy.sh"
environment = {
DEPLOY_KEY = ephemeral.aws_secretsmanager_secret_version.deploy_key.secret_string
}
}
}
Restrictions
Ephemeral values have intentional restrictions:
# ❌ Cannot use in outputs (would leak the value)
output "password" {
value = ephemeral.random_password.db.result # Error!
}
# ❌ Cannot use in local values (locals persist in memory across operations)
locals {
password = ephemeral.random_password.db.result # Error!
}
# ✅ Can only use in resource arguments and provisioners
resource "aws_db_instance" "main" {
password = ephemeral.random_password.db.result # OK
}
Provider Support
Ephemeral resources require provider support. In 2026:
- hashicorp/random —
ephemeral "random_password",ephemeral "random_id" - hashicorp/aws —
ephemeral "aws_secretsmanager_secret_version", STS tokens - hashicorp/vault —
ephemeral "vault_generic_secret" - More providers adding support throughout 2026
Check your provider’s documentation for available ephemeral resources.
Hands-On Courses
- Terraform for Beginners on CopyPasteLearn
- Terraform By Example — practical code examples
Conclusion
Ephemeral resources solve the “secrets in state” problem. Use them for passwords, API tokens, session credentials, and any value that should exist only during terraform apply. They’re never written to state, plan files, or logs. If you’re currently using data sources to fetch secrets, switching to ephemeral resources is the most impactful security improvement you can make to your Terraform workflow.