Merge pull request #860 from hashicorp/SBGoods/ephemeral-resource-best-practices

Add ephemeral resource sections to provider best practices

Author: SBGoods

website/docs/plugin/best-practices/hashicorp-provider-design-principles.mdx

@@ -79,3 +79,13 @@ The benefits of this practice include:
 - Ensuring Terraform can statically validate the entire configuration anywhere
 - Preventing practitioner issues should the environment change between Terraform commands
 - Preventing practitioner issues should networking or a service become unavailable
+
+## Ephemeral Resources should represent a single sensitive API object
+
+A Terraform ephemeral resource should be a declarative representation of a single API object that doesn't require Terraform to store it's data between runs, such as sensitive data like an API token or secret. This ephemeral data is created and/or retrieved from the API during the Open operation.
+
+The benefits of this practice include:
+
+- Maximizing predictability and minimizing the blast radius of open/close operations
+- Enabling composition of related or dependent components in new and innovative ways
+- Preventing maintainer burden of managing multiple underlying components

website/docs/plugin/best-practices/sensitive-state.mdx

@@ -12,6 +12,18 @@ it's inevitable that [sensitive information will find its way into
 Terraform](/terraform/language/state/sensitive-data) in these circumstances. There are a
 couple of recommended approaches for managing sensitive state in Terraform.
 
+## Using Ephemeral Resources
+
+<Highlight>
+
+    Ephemeral resource support is only available in the [Terraform Plugin Framework](/terraform/plugin/framework)
+
+</Highlight>
+
+[Ephemeral resources](/terraform/language/v1.10.x/resources/ephemeral) allow Terraform to reference external data, while
+guaranteeing that this data will not be persisted in plan or state. When working with a sensitive API object such as an API token or secret,
+model that object using an ephemeral resource whenever possible.
+
 ## Using `Sensitive` Flag functionality
 
 When working with a field that contains information likely to be considered

website/docs/plugin/framework-benefits.mdx

@@ -256,5 +256,6 @@ Additional new and improved features in the framework include:
 - **Validation Capabilities**: The framework exposes many more configuration validation integration points than the SDK. It is also extensible with provider-defined types that implement validation in the type itself.
 - **Functions**: The framework supports provider-defined functions which are exposed for practitioner configurations.
 - **Enhanced Import and Planning Capabilities**: The framework enables additional import and plan handling capabilities not available in SDKv2.
+- **Ephemeral Resources**: The framework supports ephemeral resources which do not store data in the Terraform plan or state artifacts.
 
 Refer to [Framework Feature Comparison](/terraform/plugin/framework/migrating/benefits) for a continued list of features, details, and examples.