-
Notifications
You must be signed in to change notification settings - Fork 9.7k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Backport of Write-only argument GA into v1.11 (#36598)
- Loading branch information
1 parent
30cd4e0
commit 70607de
Showing
7 changed files
with
134 additions
and
60 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,73 +1,66 @@ | ||
| --- | ||
| page_title: Ephemeral resources | ||
| description: Learn how to use ephemeral resource blocks and write-only arguments to manage temporary data that Terraform does not store in state. | ||
| description: Learn how to keep sensitive resource data out of state and plan files in Terraform with ephemeral resource blocks and write-only arguments. | ||
| --- | ||
|
|
||
| # Ephemerality in resources | ||
|
|
||
| Managing infrastructure often requires creating and handling temporary sensitive values, such as passwords, that you may not want Terraform to persist outside of the current operation. Terraform provides two tools for resources to manage data you do not want to store in state or plan files: the `ephemeral` resource block and ephemeral write-only arguments on specific resources. | ||
| Managing infrastructure often requires creating and handling sensitive values that you may not want Terraform to persist outside of the current operation. Terraform provides two tools for resources to manage data you do not want to store in state or plan files: the `ephemeral` resource block and ephemeral write-only arguments on specific resources. | ||
|
|
||
| ## Ephemeral resources | ||
|
|
||
| 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. | ||
| Ephemeral resources are Terraform resources that are essentially temporary. Ephemeral resources have a unique lifecycle, and Terraform does not store information about ephemeral resources in state or plan files. Each `ephemeral` block describes one or more ephemeral resources, such as a temporary password or connection to another system. | ||
|
|
||
| In your configuration, you can only reference an `ephemeral` block in [other ephemeral contexts](/terraform/language/resources/ephemeral/reference#reference-ephemeral-resources). | ||
|
|
||
| ### Lifecycle | ||
|
|
||
| The lifecycle of an ephemeral resource is different from resources and data sources. When Terraform provisions ephemeral resources, it performs the following steps: | ||
| The lifecycle of an `ephemeral` resource is different from other 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. | ||
|
|
||
| 1. 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. | ||
| to periodically renew it. For example, if Terraform renews a Vault secret `ephemeral` resource, the Vault provider calls Vault's lease renewal API endpoint to extend the expiration time. | ||
|
|
||
| 1. Once Terraform no longer needs an ephemeral resource, Terraform closes | ||
| it. This happens after the providers that depend on a certain ephemeral resource | ||
| it. This happens after the providers that depend on an 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. | ||
|
|
||
| ### Configuration model | ||
|
|
||
| To learn more about the `ephemeral` block, refer to the [Ephemeral resource reference](/terraform/language/resources/ephemeral/reference). | ||
| To learn more about the `ephemeral` resource block, refer to the [Ephemeral resource reference](/terraform/language/resources/ephemeral/reference). | ||
|
|
||
| ## Write-only arguments | ||
|
|
||
| -> **Public Beta**: Write-only arguments are in public beta and available in Terraform v1.11 and later. Public beta features and APIs are subject to change. | ||
| Terraform's managed resources, defined by `resource` blocks, can include ephemeral arguments, called **write-only arguments**. Write-only arguments are only available during the current Terraform operation, and Terraform does not store them in state or plan files. | ||
|
|
||
| Terraform resources can include ephemeral arguments, also known as attributes, for data that only needs to exist temporarily. An ephemeral argument on a resource is called a "write-only argument". Write-only arguments can help store generated sensitive data for the current Terraform operation, such as a short-lived password, token, or session identifier. | ||
| Use write-only arguments to securely pass temporary values to resources during a Terraform operation without worrying about Terraform persisting those values. For example, the `aws_db_instance` resource has a write-only `password_wo` argument that accepts a database password: | ||
|
|
||
| Write-only arguments are only available during runtime, and Terraform omits them from state and plan files. On a new Terraform operation, a write-only argument always start as `null` before Terraform overwrites it with a new value from your configuration. | ||
|
|
||
| Write-only arguments are unique among other ephemeral constructs in Terraform because you can assign both ephemeral and non-ephemeral data as the value of a write-only argument. | ||
|
|
||
|
|
||
| <!-- TODO for GA: Update with a code sample when we have one --> | ||
|
|
||
| <!-- TODO for GA: Update once we have a working provider example | ||
|
|
||
| Terraform sends write-only arguments to the provider every time it needs to create or update that argument's resource in your configuration. For example, the `aws_db_instance` resource type has a write-only `password` argument: | ||
| <CodeBlockConfig highlight="11"> | ||
|
|
||
| ```hcl | ||
| resource "aws_db_instance" "main" { | ||
| instance_class = "db.t3.micro" | ||
| username = "admin" | ||
| # This write-only argument is ephemeral, meaning it is not saved in state. | ||
| password = ephemeral.aws_secretsmanager_secret_version.example.secret_string["exampleKey"] | ||
| ephemeral "random" "password" { | ||
| length = 16 | ||
| } | ||
| ephemeral "aws_secretsmanager_secret_version" "example" { | ||
| secret_id = data.aws_secretsmanager_secret.example.id | ||
| resource "aws_db_instance" "test" { | ||
| instance_class = "db.t5.micro" | ||
| allocated_storage = "5" | ||
| engine = "postgres" | ||
| username = "admin" | ||
| skip_final_snapshot = true | ||
| password_wo = ephemeral.random.password.value | ||
| password_wo_version = 1 | ||
| } | ||
| ``` | ||
|
|
||
| Every time Terraform creates or updates the `aws_db_instance` resource, Terraform sends the `password` argument to the `aws` provider. The provider then uses the value of the `password` argument, then discards that value and never stores it in state. | ||
|
|
||
| </CodeBlockConfig> | ||
|
|
||
| To learn more about write-only arguments, refer to the [Use write-only arguments](/terraform/language/resources/ephemeral/write-only). | ||
| When Terraform creates the `aws_db_instance` resource, Terraform sends the `password_wo` argument to the `aws` provider. The `aws` provider then uses the `password_wo` value to configure the database instance, and then Terraform discards the password value without ever storing it. | ||
|
|
||
| --> | ||
| To learn more about using write-only arguments, refer to the [Use write-only arguments](/terraform/language/resources/ephemeral/write-only). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
122 changes: 102 additions & 20 deletions
122
website/docs/language/resources/ephemeral/write-only.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,44 +1,126 @@ | ||
| --- | ||
| page_title: Use write-only arguments | ||
| description: Learn how to use write-only arguments to set temporary values that can only be overwritten and are not stored in Terraform's state. | ||
| description: Learn how to use write-only arguments to set temporary values that are not stored in Terraform's state or plan files. | ||
| --- | ||
|
|
||
| <!-- THIS IS HIDDEN FOR NOW - TODO FOR GA: unhide when we have a code snippet to share and I can add more details --> | ||
|
|
||
| # Use write-only arguments | ||
|
|
||
| Terraform resources can include ephemeral arguments, also known as attributes, for data that only needs to exist temporarily. An ephemeral argument on a resource is called a "write-only argument". Write-only arguments can help store generated sensitive data for the current Terraform operation, such as a short-lived password, token, or session identifier. | ||
| Write-only arguments let you securely pass temporary values to Terraform's managed resources during an operation without persisting those values to state or plan files. Use write-only arguments to handle sensitive data such as passwords, API tokens, and other secrets. | ||
|
|
||
| ## Background | ||
|
|
||
| Write-only arguments complement [other ephemeral values](/terraform/language/resources/ephemeral/reference#reference-ephemeral-resources) in Terraform, letting you securely pass sensitive data throughout your configuration without ever storing it in Terraform's artifacts. For example, you can generate a random password using an `ephemeral` resource then pass it to a write-only argument on another `resource` block. The provider uses the write-only argument value to configure the resource, then Terraform discards the value without storing it. | ||
|
|
||
| > **Hands-on**: Declare a write-only argument in the [Upgrade RDS major version](/terraform/tutorials/aws/rds-upgrade) tutorial. | ||
| Unlike other ephemeral constructs in Terraform, such as ephemeral resources or variables, write-only arguments accept both ephemeral and non-ephemeral values. | ||
|
|
||
| ## Requirements | ||
|
|
||
| To use write-only arguments, you must use Terraform v.1.11 or later and use a resource that supports write-only arguments. | ||
|
|
||
| ## Declare a write-only argument | ||
|
|
||
| Providers indicate in the Terraform registry whether an argument is write-only. For example, the `aws` provider's `aws_db_instance` resource has a write-only `password_wo` argument. The `password_wo` argument accepts a value to use as the database password: | ||
|
|
||
| <CodeBlockConfig highlight="7"> | ||
|
|
||
| ```hcl | ||
| resource "aws_db_instance" "test" { | ||
| instance_class = "db.t5.micro" | ||
| allocated_storage = "5" | ||
| engine = "postgres" | ||
| username = "admin" | ||
| skip_final_snapshot = true | ||
| password_wo = <ephemeral or non-ephemeral value> | ||
| password_wo_version = 1 | ||
| } | ||
| ``` | ||
|
|
||
| </CodeBlockConfig> | ||
|
|
||
| Write-only arguments accept both ephemeral and non-ephemeral values. For example, you could also use a string as the value of a write-only argument: | ||
|
|
||
| ```hcl | ||
| resource "aws_db_instance" "test" { | ||
| instance_class = "db.t5.micro" | ||
| allocated_storage = "5" | ||
| engine = "postgres" | ||
| username = "admin" | ||
| skip_final_snapshot = true | ||
| password_wo = "my-password-here" | ||
| password_wo_version = 1 | ||
| } | ||
| ``` | ||
|
|
||
| However, we recommend using write-only arguments for passing ephemeral values to resources. If you use a non-ephemeral value, Terraform stores that value or hard-codes it in your configuration. For example, you can use an `ephemeral` resource to generate a random password and pass it to the `password_wo` write-only argument: | ||
|
|
||
| <CodeBlockConfig highlight="11"> | ||
|
|
||
| ```hcl | ||
| ephemeral "random" "password" { | ||
| length = 16 | ||
| } | ||
| resource "aws_db_instance" "test" { | ||
| instance_class = "db.t5.micro" | ||
| allocated_storage = "5" | ||
| engine = "postgres" | ||
| username = "admin" | ||
| skip_final_snapshot = true | ||
| password_wo = ephemeral.random.password.value | ||
| password_wo_version = 1 | ||
| } | ||
| ``` | ||
|
|
||
| -> **Public Beta**: Write-only arguments are in public beta and available in Terraform v1.11 and later. Public beta features and APIs are subject to change. | ||
| </CodeBlockConfig> | ||
|
|
||
| During a Terraform operation, the provider uses the `password_wo` value to configure the database instance, and then Terraform discards that value without storing it in the plan or state file. | ||
|
|
||
| ## Introduction | ||
| ## Update write-only arguments with versions | ||
|
|
||
| Write-only arguments are only available during runtime, and Terraform omits them from state and plan files. On a new Terraform operation, a write-only argument always start as `null` before Terraform overwrites it with a new value from your configuration. | ||
| Terraform does not store write-only arguments in state files, so Terraform has no way of knowing if a write-only argument value has changed. Because Terraform cannot track write-only argument values, it sends write-only arguments to the provider during every operation. | ||
|
|
||
| Write-only arguments are unique among other ephemeral constructs in Terraform because you can assign both ephemeral and non-ephemeral data as the value of a write-only argument. | ||
| Terraform also cannot create plan diffs for write-only arguments because it does not store those values in plan files. However, providers typically include version arguments alongside write-only arguments. Terraform stores version arguments in state, and can track if a version argument changes. | ||
|
|
||
| <!-- TODO: Update with a code sample when we have one | ||
| Providers implement version arguments to let practitioners track write-only argument values and control when a provider uses those write-only arguments. The implementation of write-only arguments and their version arguments is provider-specific, so consult the Registry for more details about your specific provider. | ||
|
|
||
| ## Define a write-only value | ||
| For example, the `aws_db_instance` resource has an accompanying `password_wo_version` argument for the `password_wo` write-only argument: | ||
|
|
||
| ## Set a write-only value | ||
| <CodeBlockConfig highlight="11-12"> | ||
|
|
||
| Example of setting an ephemeral value: | ||
| ```hcl | ||
| resource "aws_db_instance" "test" { | ||
| instance_class = "db.t5.micro" | ||
| allocated_storage = "5" | ||
| engine = "postgres" | ||
| username = "admin" | ||
| skip_final_snapshot = true | ||
| password_wo = "old-password-here" | ||
| password_wo_version = 1 | ||
| } | ||
| ``` | ||
|
|
||
| Example of setting a non-ephemeral value: | ||
| </CodeBlockConfig> | ||
|
|
||
| Add guidance on avoiding acciedentally leaking a non-ephemeral value in a write-only argument. | ||
| The provider uses the write-only argument value when creating the `aws_db_instance` resource and Terraform stores the `password_wo_version` argument value in state. | ||
|
|
||
| --> | ||
| To trigger an update of a write-only argument, increment the version argument's value in your configuration: | ||
|
|
||
| <!-- TODO: Update with provider code samples when we have them | ||
| ```hcl | ||
| ## Provider examples | ||
| resource "aws_db_instance" "main" { | ||
| instance_class = "db.t5.micro" | ||
| allocated_storage = "5" | ||
| engine = "postgres" | ||
| username = "admin" | ||
| password_wo = "new-password-here" | ||
| password_wo_version = 2 | ||
| } | ||
| ``` | ||
|
|
||
| ### Vault example | ||
| When you increment the `password_wo_version` argument, Terraform notices that change in its plan and notifies the `aws` provider. The `aws` provider then uses the new `password_wo` value to update the `aws_db_instance` resource. | ||
|
|
||
| ### AWS example | ||
| <!--- TODO: add Vault example once the provider supports write-only args ---> | ||
|
|
||
| --> | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters