Managing sensitive values in Terraform has historically been a challenging task. Before Terraform 1.11, sensitive data such as API keys, passwords, and tokens were persistently stored in the Terraform plan artifacts and state files. This meant that users had to enforce strict security measures to safeguard their state files from unauthorized access. To mitigate this risk and enhance security, Terraform introduced ephemeral values, ephemeral resources, and write-only arguments. These features allow Terraform practitioners to work with sensitive data securely, ensuring that confidential information does not persist beyond its immediate use.
Understanding Ephemerality in Terraform
Ephemerality in computing refers to the transient nature of data—values that exist temporarily and are discarded once their purpose has been fulfilled.
In Terraform, ephemerality is a powerful security mechanism designed to manage sensitive data without leaving a trace.
This is achieved through new language constructs that track values only at runtime, ensuring that sensitive information does not persist in the state file or Terraform plan artifact.
Terraform classifies ephemerality into three key constructs:
- Ephemeral Resources – Temporary resources that are provisioned and utilized during the execution phase but do not persist in state files.
- Ephemeral Input Variables – Input values that exist solely for runtime execution and do not persist beyond the operation.
- Write-Only Arguments – Attributes that accept sensitive values but prevent their exposure in Terraform state files.
By leveraging these ephemeral constructs, Terraform enhances security, minimizes risk, and ensures that secrets are handled safely without compromising the integrity of the infrastructure.
Ephemeral Resources
Ephemeral resources in Terraform are short-lived entities designed to facilitate secure operations, such as retrieving secrets or establishing secure connections, without persisting any sensitive data in state files. These resources are instrumental in handling sensitive values without leaving a footprint.
How Ephemeral Resources Work
Ephemeral resources are executed at both the plan and apply stages. However, they require that all their dependencies exist before execution. If an ephemeral resource attempts to retrieve a value from a non-existent secrets manager, Terraform will return an error.
Terraform can also defer the execution of ephemeral resources until the apply stage if any of its input arguments reference values that are unknown during the plan stage. This ensures proper sequencing and execution of dependent resources.
Example: Creating an Ephemeral Password
ephemeral "random_password" "db_password" {
length = 16
}
This example generates a temporary password using a cryptographic random number generator. The password is available for use but does not persist beyond execution.
Write-Only Arguments
Write-only arguments are attributes used in Terraform configurations that accept sensitive values but are never stored in Terraform state files or plan artifacts. These arguments are typically implemented in Terraform providers to handle confidential data such as passwords, API tokens, and encryption keys securely.
Example: Using Write-Only Arguments with AWS Secrets Manager
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
}
In this configuration:
- The ephemeral random password is generated dynamically.
- The password is stored in AWS Secrets Manager without persisting in Terraform state.
- The secret_string_wo attribute ensures the secret is used securely without exposure.
Write-Only Version Arguments
Terraform does not store write-only arguments in state files, meaning that their values cannot be tracked directly. As a result, Terraform always sends write-only arguments to the provider during every operation.
To manage updates for write-only arguments, Terraform providers typically include write-only version arguments, such as password_wo_version. These version arguments enable users to update write-only values by incrementing the version number.
Example: Managing Write-Only Argument Updates
resource "aws_db_instance" "example" {
instance_class = "db.t3.micro"
allocated_storage = "5"
engine = "postgres"
username = "example"
skip_final_snapshot = true
password_wo = ephemeral.aws_secretsmanager_secret_version.db_password.secret_string
password_wo_version = aws_secretsmanager_secret_version.db_password.secret_string_wo_version
}
Best Practices for Write-Only Versioning
- Synchronize version arguments across multiple write-only attributes to prevent inconsistencies.
- Use versioning to control when sensitive values should be updated.
- Store secrets in a secure secrets manager before referencing them in Terraform.
Deferring Ephemeral Resources
Terraform intelligently defers the execution of ephemeral resources when their input arguments depend on values that are only known during or after the plan stage. This ensures that ephemeral resources are evaluated at the right time and prevents premature execution.
Example: Secure AWS RDS Instance Provisioning
ephemeral "random_password" "db_password" {
length = 16
override_special = "!#$%&*()-_=+[]{}<>:?"
}
resource "aws_secretsmanager_secret" "db_password" {
name = "db-password"
}
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
}
ephemeral "aws_secretsmanager_secret_version" "db_password" {
secret_id = aws_secretsmanager_secret_version.db_password.secret_id
}
This approach ensures that:
- Terraform first generates an ephemeral random password.
- The password is securely stored in AWS Secrets Manager.
- The AWS RDS instance references the stored password securely.
Lifecycle of Ephemeral Resources
Ephemeral resources follow a unique lifecycle in Terraform:
- Opening – The ephemeral resource is accessed when required.
- Renewing – If the resource needs to be accessed for an extended period, it may be periodically renewed.
- Closing – The ephemeral resource is terminated once it is no longer needed.
Some ephemeral resources implement renewal and closing logic, such as handling secure tunnels or leasing credentials from Vault. Others, like temporary password generators, do not require additional lifecycle management.
Persisting Ephemeral Secrets
While ephemeral values are designed to be transient, there are cases where persistence is necessary. When using ephemeral random passwords, it is best practice to store them securely in a secrets manager before referencing them. This prevents accidental loss while maintaining security best practices.
Conclusion
Terraform’s introduction of ephemeral values, ephemeral resources, and write-only arguments significantly improves the secure handling of sensitive data.
By leveraging these constructs, infrastructure as code (IaC) practitioners can confidently manage secrets without persistent exposure, mitigating security risks.
For more details, refer to the official Terraform documentation on ephemeral resources and write-only arguments.
