Sensitive Data, Ephemeral Values and Write-Only Arguments

A value becomes sensitive in four ways.

Expressions that use a sensitive value are sensitive too: an interpolation, a join, an attribute of an object that is built from it. A for expression over a sensitive collection is sensitive as a whole. This propagation is deliberately conservative, so a SHA-256 hash of a secret or the one harmless field of a decoded JSON document is still marked. The nonsensitive() function removes the mark when, and only when, you know from the properties of your system that the derived value is safe. Terraform raises an error if you call it on a value that is not sensitive, because the call would be redundant. The functions are described in Functions.

Source: Terraform Docs — variable block reference and Terraform Docs — output block reference.

If a sensitive value reaches an output that is not marked sensitive, Terraform stops with an error and asks you to add sensitive = true. This is a protection against leaking by accident, and it is also why people sprinkle nonsensitive() over their code until the error goes away. Doing so removes exactly the protection the error offered.

The sensitive argument is a display control. The official pages for the variable and output blocks say the same thing in different words, and together they list the limits.

Source: Terraform Docs — Manage sensitive data in your configuration, Terraform Docs — output block reference and Terraform Docs — Sensitive data in state.

A frequent related mistake concerns the random_password resource. Its result is sensitive in the plan, which makes people think it is protected. It is stored in clear text in the state, as the provider’s own documentation recommends moving away from: the page for the managed resource tells users that when the target resource has a write-only attribute for the password, the ephemeral variant of random_password should be used instead, "to avoid storing the password in the plan or state file". The comparison is in random_password: resource versus ephemeral equivalent.

Sometimes a human or a script needs the value. The commands that print it are explicit, so their use is visible in a review of the pipeline.

Source: Terraform Docs — terraform output.

The commented output is illustrative. Whether an output prints (sensitive value) depends on how it is declared. Never run these commands in a job whose log is public, and prefer an output that exposes the location of a secret (a secret name or ARN) over one that exposes the secret itself.

The Terraform documentation lists the ephemeral contexts. A reference to an ephemeral value outside of one is a plan-time error, and the error message names the context that was violated.

Source: Terraform Docs — Manage sensitive data in your configuration and Terraform Docs — ephemeral block reference.

The OpenTofu documentation lists the same set (ephemeral resources, variables, outputs, locals, providers, provisioners, resource connection blocks and write-only attributes) and adds one restriction that matters in practice: an ephemeral value cannot be used in count or for_each, because those decide which resource instances exist, and instances are stored. The same applies to lifecycle { enabled }.

Setting ephemeral = true on a variable block keeps the value out of state and plan. It is the right choice for a credential that a provider needs only during the run. The variables-outputs-and-locals page describes the argument in the context of the other variable arguments; the points that matter here are these.

Run it with the secret supplied from the environment, not from a file in the repository.

Source: Terraform Docs — variable block reference and AWS provider — aws_db_instance.

An important consequence of the example: Terraform no longer knows the password after the apply. If you need it later, for example to hand it to reviews-api, you must obtain it from where you stored it (the secret manager), not from the state. Section Reading and writing secrets with a secret manager shows the full loop.

An output block can set ephemeral = true to pass a value between modules without writing it to state or plan. Three rules apply.

A common use is a module that reads a credential from a secret manager and hands it to the root module, so the root module can configure a provider or fill a write-only argument without the value being stored.

Source: Terraform Docs — output block reference and AWS provider — ephemeral aws_secretsmanager_secret_version.

The module is called as usual, and the root module uses module.reviews_secret.db_password only in one of the ephemeral contexts.

Source: Terraform Docs — Ephemerality.

A locals block may hold ephemeral values, and a local that references one becomes ephemeral itself. This is handy to shape a secret before use. The Terraform documentation shows deriving a connection string from an ephemeral secret and using it in a provider block.

Source: Terraform Docs — ephemeral block reference and PostgreSQL provider — configuration.

The PostgreSQL provider shown is a community provider (cyrilgdn/postgresql); its host, port, username, password and sslmode provider arguments come from its own documentation, and the required_providers entry is omitted here for brevity.

An ephemeral resource is a resource that exists only during one operation. Terraform opens it when it needs the result, keeps it alive as long as something uses it, and closes it. It is the ephemeral counterpart of a data source: a way to read or to produce a value, but one whose attributes are never persisted. The official reference states it directly: Terraform does not store ephemeral resources in state or plan files.

The syntax mirrors a resource or data block with a different keyword. Each provider defines its own ephemeral resource types; a provider that has none cannot be used with the block.

Source: Terraform Docs — ephemeral block reference.

The block is referenced as ephemeral.<TYPE>.<LABEL>, with the prefix ephemeral. that distinguishes it from a managed resource of the same type. The following table lists the meta-arguments the documentation describes.

Source: Terraform Docs — ephemeral block reference.

Because Terraform stores null for the argument, it cannot see that you changed the value, so it can never show a difference for it in a plan. Provider authors therefore pair each write-only argument with a normal argument that is stored in the state, usually named with the suffix _version. The convention is: the write-only argument ends in _wo and its companion adds _version. To rotate the secret you change the value and increment the version. The change of the version is visible to Terraform, the plan shows an update, and the provider reads the new write-only value and applies it.

Source: Terraform Docs — Write-only arguments and AWS provider — aws_db_instance.

The documentation is careful to say that the implementation of write-only arguments and of their version arguments is provider specific. The provider SDK guide describes two patterns: a version attribute, as in password_wo_version, and a keepers map as in the Random provider, where any change to the map makes the provider use the write-only value. Never assume a _version argument exists. Read the provider page.

The table lists the arguments verified for this page. All of them are "write-only" in the provider documentation, and each is paired with the version argument shown.

Source: AWS provider — aws_db_instance, AWS provider — aws_secretsmanager_secret_version, AzureRM provider — azurerm_key_vault_secret, AzureRM provider — azurerm_postgresql_flexible_server, Google provider — google_secret_manager_secret_version, Google provider — google_sql_user and Vault provider — vault_kv_secret_v2.

Provider support grows with each release: the Vault and Google providers started with three write-only arguments each and added more later, and the AWS provider adds them resource by resource. The list above is a snapshot, not a catalogue. The Google provider’s guide notes that the arguments were chosen because they were already marked sensitive, and that sensitive arguments still end in state while write-only ones do not.

Terraform reports a diagnostic titled "Available Write-only Attribute Alternative" (the Terraform 1.12 release notes mention it when they fix duplicated reports of it). The provider SDK guide describes a validator that warns practitioners on Terraform 1.11 or later when a regular attribute such as password is set although its write-only counterpart password_wo could be used. Treat the warning as an instruction to migrate. OpenTofu prints (write-only attribute) for such arguments in plan and apply output.

Source: Terraform Docs — Write-only arguments (provider development) and Terraform Docs — Write-only arguments.

The AWS provider has an ephemeral resource, aws_secretsmanager_secret_version, which retrieves a secret version including its value. The arguments are secret_id (required; the ARN or the friendly name), version_id, version_stage (default AWSCURRENT) and region. Its attributes include secret_string, secret_binary, arn, version_id, version_stages and created_date. A second ephemeral resource, aws_secretsmanager_random_password, generates a password with the Secrets Manager service and exports it as random_password; its arguments include password_length, exclude_characters, exclude_punctuation and require_each_included_type.

The complete loop for the Bookshelf reviews database generates a password ephemerally, writes it to the secret with secret_string_wo, and applies the same value to the database with password_wo. Neither value reaches the state.

Source: Terraform Docs — Write-only arguments, AWS provider — aws_secretsmanager_secret_version and Random provider — ephemeral random_password.

There is a subtlety the example shows. The ephemeral password is generated again in each phase, and the plan itself does not store it. The two write-only arguments receive the value generated in the apply phase, so they agree with each other. They are only sent when their version arguments change, so after the first apply a later apply that does not change the versions sends nothing and leaves the stored secret untouched. To rotate, increment both versions in the same commit so that the secret and the database receive the same new password.

An application then reads the secret at run time (for example with the AWS SDK, or the Kubernetes External Secrets operator), and a later Terraform run that needs the value again, for example to configure a provider, reads it with the ephemeral resource of the previous section.

For RDS there is also a managed alternative that avoids the question: manage_master_user_password = true lets RDS create and rotate the master password in Secrets Manager. It cannot be combined with password or password_wo.

The AzureRM provider has the ephemeral resource azurerm_key_vault_secret, which requires Terraform 1.10 or later. It takes name and key_vault_id (both required) and an optional version (default: the current version), and exports value, expiration_date and not_before_date. The vault must be in the same subscription as the provider; for another subscription, configure an aliased provider. The managed resource azurerm_key_vault_secret has value_wo and value_wo_version.

The Terraform documentation shows the loop for a MySQL flexible server; the Bookshelf variant below uses the PostgreSQL flexible server that catalog-api needs.

Source: Terraform Docs — Write-only arguments, AzureRM provider — ephemeral azurerm_key_vault_secret and AzureRM provider — azurerm_key_vault_secret.

The azurerm_postgresql_flexible_server arguments version, sku_name, administrator_login and location are shown with the values from the provider’s own examples; the other arguments the resource needs for a real deployment (network configuration, storage, backups) are omitted. The ephemeral secret read is placed after the managed secret because it uses its name, which orders the graph.

The Google provider has the ephemeral resource google_secret_manager_secret_version. Its arguments are secret (required), project, version and is_secret_data_base64; the documented attributes are secret_data, name, create_time and destroy_time. The managed resource google_secret_manager_secret_version has the write-only argument secret_data_wo with secret_data_wo_version, and the provider’s own example passes the ephemeral value to a resource with a write-only argument, google_monitoring_uptime_check_config.

Source: Google provider — google_secret_manager_secret_version, Google provider — Use write-only arguments and Google provider — google_sql_user.

The replication { auto {} } block declares automatic replication for the secret. To read the secret later in a different configuration, use the ephemeral resource:

Source: Google provider — ephemeral google_secret_manager_secret_version.

The Vault provider added two ephemeral resources together with write-only arguments in its 5.x series: vault_kv_secret_v2 and vault_database_secret. The ephemeral vault_kv_secret_v2 takes mount and name (both required) and optional version and mount_id; it exports data (a map of the top-level keys; non-string values are serialized as JSON), data_json, created_time, custom_metadata, deletion_time and destroyed. Setting mount_id to the ID of the vault_mount resource defers the read to the apply, as the guide for the provider explains. The managed vault_kv_secret_v2 has the write-only data_json_wo with data_json_wo_version.

Source: Vault provider — ephemeral vault_kv_secret_v2, Vault provider — vault_kv_secret_v2 and Vault provider — Use write-only attributes.

The data_json_wo value in the example is deliberately a placeholder: in practice it comes from an ephemeral resource, an ephemeral variable or an out-of-band process, never from a literal in the code. The Vault provider’s own example for the PostgreSQL connection of the database secrets engine sets password_wo and password_wo_version inside the postgresql block of vault_database_secret_backend_connection, with the password read from the ephemeral vault_kv_secret_v2. The Vault provider itself has to authenticate to Vault, so prefer short-lived authentication over a static token, for the same reasons as in the rest of this page.