Ephemeral resource configuration reference

This topic provides reference information for the ephemeral block.

Introduction

Ephemeral resources are Terraform resources that are essentially temporary. Ephemeral resources have a unique lifecycle, and Terraform does not store them in its state. Each ephemeral block describes one or more ephemeral resources, such as a temporary password or connection to another system.

An ephemeral block declares an ephemeral resource of a specific type with a specific local name, much like a resource block. Terraform uses an ephemeral resource's name to refer to that resource in the same module, but an ephemeral resource's name has no meaning outside that module's scope.

Lifecycle

The lifecycle of an ephemeral resource is different from resources and data sources. When Terraform provisions ephemeral resources, it performs the following steps:

1. If Terraform needs to access the result of an ephemeral resource, it opens that ephemeral resource. For example, if Terraform opens an ephemeral resource for a Vault secret, the Vault provider obtains a lease and returns a secret.

2. If Terraform needs access to the ephemeral resource for longer than the remote system's enforced expiration time, Terraform asks the provider to renew it periodically. For example, if Terraform renews a Vault secret ephemeral resource, the Vault provider then calls Vault's lease renewal API endpoint to extend the expiration time.

3. Once Terraform no longer needs an ephemeral resource, Terraform closes it. This happens after the providers that depend on a certain ephemeral resource complete all of their work for the current Terraform run phase. For example, closing a Vault secret ephemeral resource means the Vault provider explicitly ends the lease, allowing Vault to immediately revoke the associated credentials.

Terraform follows these lifecycle steps for each instance of an ephemeral resource in a given configuration.

Dependency graph

Ephemeral resources form nodes in Terraform's dependency graph, which interact similarly as resources and data sources. For example, when a resource or data source depends on an attribute of an ephemeral resource, Terraform automatically provisions the ephemeral resource first.

Configuration model

Most of the arguments within the body of an ephemeral block are specific to the ephemeral resource you are defining. As with resources and data sources, each provider in the Terraform Registry includes documentation for the ephemeral resources it supports, if any. An ephemeral resource type's documentation lists which arguments are available and how you should format your resource's values.

The following list outlines general field hierarchy, language-specific data types, and requirements in the ephemeral block.

• ephemeral: map
  • attributes
  • meta-arguments

Complete configuration

An ephemeral block has the following form:

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

Referencing ephemeral resources

You can only reference ephemeral resources in specific ephemeral contexts or Terraform throws an error. The following are valid contexts for referencing ephemeral resources:

• In another ephemeral resource
• In local values
• In ephemeral variables
• In ephemeral outputs
• Configuring providers in the provider block
• In provisioner and connection blocks

Meta-arguments

You can use the following meta-arguments with ephemeral resources to change the behavior of those resources. The following meta-arguments work the same way for resources, data sources, and ephemeral resources:

• depends_on, for specifying hidden dependencies
• count, for creating multiple resource instances according to a count
• for_each, to create multiple instances according to a map or set of strings
• provider, for selecting a non-default provider configuration
• lifecycle, for lifecycle customizations

Ephemeral resources do not support the provisioner meta-argument.

Example

The following example configures the postgresql provider with credentials from an ephemeral resource. Since these credentials are managed by an ephemeral resource, Terraform does not store them in your state or plan files.

ephemeral "aws_secretsmanager_secret_version" "db_master" {
  secret_id = data.aws_db_instance.example.master_user_secret[0].secret_arn
}

locals {
  credentials = jsondecode(ephemeral.aws_secretsmanager_secret_version.db_master.secret_string)
}

provider "postgresql" {
  host     = data.aws_db_instance.example.address
  port     = data.aws_db_instance.example.port
  username = local.credentials["username"]
  password = local.credentials["password"]
}