From 92b2e3a2912788f8a8f9e529c63d8ece31d02fe7 Mon Sep 17 00:00:00 2001 From: Selena Goods Date: Mon, 17 Mar 2025 12:39:10 -0400 Subject: [PATCH 1/3] Add ephemeral resource best practices --- .../hashicorp-provider-design-principles.mdx | 11 +++++++++++ .../docs/plugin/best-practices/sensitive-state.mdx | 12 ++++++++++++ website/docs/plugin/framework-benefits.mdx | 1 + 3 files changed, 24 insertions(+) diff --git a/website/docs/plugin/best-practices/hashicorp-provider-design-principles.mdx b/website/docs/plugin/best-practices/hashicorp-provider-design-principles.mdx index 9665683b3..2d1e6aea3 100644 --- a/website/docs/plugin/best-practices/hashicorp-provider-design-principles.mdx +++ b/website/docs/plugin/best-practices/hashicorp-provider-design-principles.mdx @@ -79,3 +79,14 @@ 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 sensitive API object, such as an API token or secret, which will be +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 diff --git a/website/docs/plugin/best-practices/sensitive-state.mdx b/website/docs/plugin/best-practices/sensitive-state.mdx index 9698a76d2..3b9eb0e21 100644 --- a/website/docs/plugin/best-practices/sensitive-state.mdx +++ b/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 + + + + Ephemeral resource support is only available in the [Terraform Plugin Framework](/terraform/plugin/framework) + + + +[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 diff --git a/website/docs/plugin/framework-benefits.mdx b/website/docs/plugin/framework-benefits.mdx index 8b158d27b..c256491a7 100644 --- a/website/docs/plugin/framework-benefits.mdx +++ b/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. From 5fb3f09a445f3223348bf4bde34286f9759c8c0c Mon Sep 17 00:00:00 2001 From: Selena Goods Date: Mon, 17 Mar 2025 15:38:07 -0400 Subject: [PATCH 2/3] Update website/docs/plugin/best-practices/hashicorp-provider-design-principles.mdx Co-authored-by: Austin Valle --- .../best-practices/hashicorp-provider-design-principles.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/plugin/best-practices/hashicorp-provider-design-principles.mdx b/website/docs/plugin/best-practices/hashicorp-provider-design-principles.mdx index 2d1e6aea3..27edac8d9 100644 --- a/website/docs/plugin/best-practices/hashicorp-provider-design-principles.mdx +++ b/website/docs/plugin/best-practices/hashicorp-provider-design-principles.mdx @@ -82,7 +82,7 @@ The benefits of this practice include: ## Ephemeral Resources should represent a single sensitive API object -A Terraform ephemeral resource should be a declarative representation of a single sensitive API object, such as an API token or secret, which will be +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. created and/or retrieved from the API during the Open operation. The benefits of this practice include: From c42acbaf7656a189a33452e1dd6b4447bbae39ea Mon Sep 17 00:00:00 2001 From: Selena Goods Date: Mon, 17 Mar 2025 16:10:04 -0400 Subject: [PATCH 3/3] Update website/docs/plugin/best-practices/hashicorp-provider-design-principles.mdx Co-authored-by: Austin Valle --- .../best-practices/hashicorp-provider-design-principles.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/website/docs/plugin/best-practices/hashicorp-provider-design-principles.mdx b/website/docs/plugin/best-practices/hashicorp-provider-design-principles.mdx index 27edac8d9..d67c3743b 100644 --- a/website/docs/plugin/best-practices/hashicorp-provider-design-principles.mdx +++ b/website/docs/plugin/best-practices/hashicorp-provider-design-principles.mdx @@ -83,7 +83,6 @@ The benefits of this practice include: ## 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. -created and/or retrieved from the API during the Open operation. The benefits of this practice include: