Beta outline for write-only fields (#36297)

website/data/language-nav-data.json

@@ -137,8 +137,22 @@
         "path": "resources/terraform-data"
       },
       {
-        "title": "Ephemeral Resources",
-        "path": "resources/ephemeral"
+        "title": "Ephemerality in Resources",
+         "routes": [
+          {
+            "title": "Overview",
+            "path": "resources/ephemeral"
+          },
+          {
+            "title": "Ephemeral block",
+            "path": "resources/ephemeral/reference"
+          },
+          {
+            "title": "Use Write-only Arguments",
+            "path": "resources/ephemeral/write-only",
+            "hidden": "true"
+          }
+        ]
       }
     ]
   },

website/docs/language/functions/terraform-applying.mdx

@@ -27,6 +27,7 @@ locals {
 
 The `terraform.applying` symbol is an ephemeral value, meaning it is only available during Terraform operations and Terraform does not write this value to plan or state files. Additionally, you can only reference `terraform.applying` in ephemeral contexts:
 
+* In a [write-only argument](/terraform/language/resources/ephemeral#write-only-arguments)
 * In [ephemeral variables](/terraform/language/values/variables#exclude-values-from-state)  
 * In [local values](/terraform/language/values/locals#ephemeral-values)  
 * In [ephemeral resources](/terraform/language/resources/ephemeral)  

website/docs/language/resources/ephemeral/index.mdx

@@ -0,0 +1,73 @@
+---
+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. 
+---
+
+# 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.
+
+## 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.
+
+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:
+
+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.
+
+1. 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.
+
+### Configuration model
+
+To learn more about the `ephemeral` 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 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 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:
+
+```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 "aws_secretsmanager_secret_version" "example" {
+  secret_id = data.aws_secretsmanager_secret.example.id
+}
+```
+
+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.
+
+
+To learn more about write-only arguments, refer to the [Use write-only arguments](/terraform/language/resources/ephemeral/write-only).
+
+-->

website/docs/language/resources/ephemeral.mdx → website/docs/language/resources/ephemeral/reference.mdx

@@ -1,6 +1,6 @@
 ---
 page_title: Ephemeral resource configuration reference
-description: Learn about ephemeral resource blocks that you can specify in Terraform configurations. Ephemeral resource blocks represent temporary resources that Terraform does not store in state.
+description: Learn to define ephemeral resource blocks in Terraform configurations. Ephemeral resource blocks represent temporary resources that Terraform does not store in state.
 ---
 
 # Ephemeral resource configuration reference
@@ -13,39 +13,15 @@ This topic provides reference information for the `ephemeral` block.
 
 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.
 
-<!-- After page exists, add: For information about how Terraform manages ephemeral resources, refer to
-[Epehemeral Values](/terraform/language/epehemeral-values). -->
-
-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. 
-
-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.
-
-1. 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
 
+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.
+
 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](https://registry.terraform.io/browse/providers) 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. 
@@ -65,12 +41,13 @@ ephemeral "<resource_type>" "<resource_name>" {
 }
 ```
 
-## Referencing ephemeral resources
+## Reference 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 a [write-only argument](/terraform/language/resources/ephemeral#write-only-arguments)
 * In another ephemeral resource
 * In [local values](/terraform/language/values/locals#ephemeral-values)
 * In [ephemeral variables](/terraform/language/values/variables#exclude-values-from-state)

website/docs/language/resources/ephemeral/write-only.mdx

@@ -0,0 +1,44 @@
+---
+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.
+---
+
+<!-- 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.
+
+-> **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.
+
+
+## Introduction
+
+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: Update with a code sample when we have one
+
+## Define a write-only value
+
+## Set a write-only value
+
+Example of setting an ephemeral value:
+
+Example of setting a non-ephemeral value:
+
+Add guidance on avoiding acciedentally leaking a non-ephemeral value in a write-only argument.
+
+-->
+
+<!-- TODO: Update with provider code samples when we have them
+
+## Provider examples
+
+### Vault example
+
+### AWS example
+
+-->
+

website/docs/language/values/outputs.mdx

@@ -131,6 +131,8 @@ output "secret_id" {
 Terraform has access to the value of `output` blocks during plan and apply operations. At the end of a plan or apply operation, Terraform does not persist the value of any ephemeral outputs.
 
 You can only reference ephemeral outputs in specific contexts or Terraform throws an error. The following are valid contexts for referencing ephemeral outputs:
+
+* In a [write-only argument](/terraform/language/resources/ephemeral#write-only-arguments)
 * In another child module's ephemeral `output` block
 * In [ephemeral variables](/terraform/language/values/variables#exclude-values-from-state)
 * In [ephemeral resources](/terraform/language/resources/ephemeral)

website/docs/language/values/variables.mdx

@@ -196,6 +196,8 @@ variable "session_token" {
 Ephemeral variables are available during the current Terraform operation, and Terraform does not store them in state or plan files. So, unlike [`sensitive`](#sensitive) inputs, Terraform ensures ephemeral values are not available beyond the lifetime of the current Terraform run.
 
 You can only reference ephemeral variables in specific contexts or Terraform throws an error. The following are valid contexts for referencing ephemeral variables:
+
+* In a [write-only argument](/terraform/language/resources/ephemeral#write-only-arguments)
 * Another ephemeral variable
 * In [local values](/terraform/language/values/locals#ephemeral-values)
 * In [ephemeral resources](/terraform/language/resources/ephemeral)