Terraform Ephemeral Resources

Terraform 1.10 introduced a groundbreaking concept called ephemeral resources. An ephemeral resource is not persisted to the state file. Take a moment to let that sink in!
Ephemeral resources address a long-standing issue: secret values being stored in the state file as plaintext. With ephemeral resources, your secrets are no longer at risk if the state file is compromised. This solution is particularly valuable for enhancing the security of sensitive data.

Initially, only a few providers support ephemeral resources. As of now, these include:

• Microsoft Azure (azurerm):
  
  
  • azurerm_key_vault_secret
  • azurerm_key_vault_certificate
• Kubernetes (kubernetes):
  • kubernetes_token_request
  • kubernetes_certificate_signing_request

This list is expected to expand over time.Declaring an Ephemeral ResourceEphemeral resources introduce a new root-level block in HCL: the ephemeral block. Its syntax resembles a regular resource block:

ephemeral "<resource type>" "<resource name>" {
  # attributes, meta-arguments, nested blocks
}

ephemeral "<resource type>" "<resource name>"
{
# attributes, meta-arguments, nested blocks
}
Similar to normal resources, supported attributes and nested blocks vary based on the resource type.

Using an Ephemeral ResourceReferencing an ephemeral resource is analogous to referencing a data source. Such references use the ephemeral. prefix.
For example:

ephemeral "azurerm_key_vault_secret" "secret" {
  # attributes
}
You can access its attributes using ephemeral.azurerm_key_vault_secret.secret.<attribute>.

Ephemeral resources can only be used in contexts where their values are not stored in the state file. Supported contexts include:

• Other ephemeral resource blocks
  
  
• Local values
  
  
• Ephemeral variable and output blocks (discussed below)
• Provider configurations within provider blocks
• Provisioner and connection blocks in regular resources

These restrictions ensure the security and temporary nature of ephemeral resources. For example, referencing an ephemeral resource in a state-persisted context would defeat its purpose.
When used in local values, ephemeral references implicitly create ephemeral local values. You cannot explicitly declare ephemeral locals; they are only derived through ephemeral references.

Example: Using Ephemeral Resources

# Read secrets from AWS Secrets Manager
ephemeral "aws_secretsmanager_secret_version" "secret" {
  secret_id = "<secret id>"
}

locals {
  # Decode the JSON secret value
  credentials = jsondecode(ephemeral.aws_secretsmanager_secret_version.db.secret_string)
}

# Configure the PostgreSQL provider using the credentials
provider "postgresql" {
  host     = "<postgres endpoint>"
  port     = 5432
  username = local.credentials["username"]
  password = local.credentials["password"]
}
In this example, the ephemeral resource aws_secretsmanager_secret_version retrieves a PostgreSQL database password. The password is JSON-decoded into a local value and used to configure the PostgreSQL provider—all without persisting the sensitive data in the state file.
Supported Meta-ArgumentsEphemeral resources support the following meta-arguments:

• depends_on: Define explicit dependencies
• count: Create multiple identical ephemeral resources
• for_each: Create one ephemeral resource for each value in a set or map
• provider: Use a provider alias
• lifecycle: Hook into the resource lifecycle

However, ephemeral resources do not support the provisioner meta-argument—a best practice you should generally avoid anyway.

The Lifecycle of an Ephemeral ResourceEphemeral resources behave differently from regular resources and data sources. They are opened (or read) when Terraform needs their values and closed when those values are no longer required. The specifics of opening and closing depend on the resource type.
For instance, in HashiCorp Vault, opening a secret means obtaining a lease, and closing it means explicitly ending that lease. Most importantly, ephemeral resources ensure that their values are never stored in the state file.

Summary
Ephemeral resources, variables, and outputs are a powerful addition to Terraform. They eliminate the risk of sensitive values being stored as plaintext in the state file, addressing a long-standing security concern.
While the state file will still contain other sensitive information, such as a complete map of your infrastructure, ephemeral resources significantly reduce its sensitivity. By leveraging these new capabilities, you can build more secure and robust Terraform configurations.
Ephemeral resources mark a significant step forward in Terraform’s evolution, and their adoption is expected to grow rapidly in the coming years.