From 10ad42c77287e92988071e3605e7108f4fd4772b Mon Sep 17 00:00:00 2001 From: Brian Flad Date: Tue, 13 Dec 2022 14:05:21 -0500 Subject: [PATCH] Remove beta verbiage and state compatibility promises --- .changelog/578.txt | 3 +++ README.md | 10 ++-------- website/docs/plugin/framework/acctests.mdx | 2 -- .../docs/plugin/framework/data-sources/configure.mdx | 2 -- website/docs/plugin/framework/data-sources/index.mdx | 2 -- .../docs/plugin/framework/data-sources/timeouts.mdx | 2 -- .../framework/data-sources/validate-configuration.mdx | 2 -- website/docs/plugin/framework/debugging.mdx | 2 -- website/docs/plugin/framework/diagnostics.mdx | 2 -- .../framework/handling-data/accessing-values.mdx | 2 -- .../docs/plugin/framework/handling-data/attributes.mdx | 2 -- .../framework/handling-data/path-expressions.mdx | 2 -- website/docs/plugin/framework/handling-data/paths.mdx | 2 -- .../docs/plugin/framework/handling-data/schemas.mdx | 2 -- .../plugin/framework/handling-data/writing-state.mdx | 2 -- website/docs/plugin/framework/index.mdx | 2 -- .../migrating/attributes-blocks/attribute-schema.mdx | 2 -- .../migrating/attributes-blocks/blocks-computed.mdx | 2 -- .../framework/migrating/attributes-blocks/blocks.mdx | 2 -- .../migrating/attributes-blocks/default-values.mdx | 2 -- .../framework/migrating/attributes-blocks/fields.mdx | 2 -- .../migrating/attributes-blocks/force-new.mdx | 2 -- .../framework/migrating/attributes-blocks/types.mdx | 2 -- .../migrating/attributes-blocks/validators-custom.mdx | 2 -- .../attributes-blocks/validators-predefined.mdx | 2 -- .../plugin/framework/migrating/data-sources/index.mdx | 2 -- .../framework/migrating/data-sources/timeouts.mdx | 2 -- website/docs/plugin/framework/migrating/index.mdx | 2 -- .../plugin/framework/migrating/providers/index.mdx | 2 -- .../docs/plugin/framework/migrating/resources/crud.mdx | 2 -- .../plugin/framework/migrating/resources/import.mdx | 2 -- .../plugin/framework/migrating/resources/index.mdx | 2 -- .../migrating/resources/plan-modification.mdx | 2 -- .../framework/migrating/resources/state-upgrade.mdx | 2 -- .../plugin/framework/migrating/resources/timeouts.mdx | 2 -- .../docs/plugin/framework/migrating/schema/index.mdx | 2 -- website/docs/plugin/framework/migrating/testing.mdx | 2 -- website/docs/plugin/framework/provider-servers.mdx | 2 -- website/docs/plugin/framework/providers/index.mdx | 2 -- .../framework/providers/validate-configuration.mdx | 2 -- website/docs/plugin/framework/resources/configure.mdx | 2 -- website/docs/plugin/framework/resources/create.mdx | 2 -- website/docs/plugin/framework/resources/delete.mdx | 2 -- website/docs/plugin/framework/resources/import.mdx | 2 -- website/docs/plugin/framework/resources/index.mdx | 2 -- .../plugin/framework/resources/plan-modification.mdx | 2 -- .../docs/plugin/framework/resources/private-state.mdx | 2 -- website/docs/plugin/framework/resources/read.mdx | 2 -- .../docs/plugin/framework/resources/state-upgrade.mdx | 2 -- website/docs/plugin/framework/resources/timeouts.mdx | 2 -- website/docs/plugin/framework/resources/update.mdx | 2 -- .../framework/resources/validate-configuration.mdx | 2 -- website/docs/plugin/framework/validation.mdx | 2 -- 53 files changed, 5 insertions(+), 110 deletions(-) create mode 100644 .changelog/578.txt diff --git a/.changelog/578.txt b/.changelog/578.txt new file mode 100644 index 000000000..b1e711e4e --- /dev/null +++ b/.changelog/578.txt @@ -0,0 +1,3 @@ +```release-note:note +The Terraform Plugin Framework is now generally available with semantic versioning compatibility promises. +``` diff --git a/README.md b/README.md index eb74ed612..518fd0e06 100644 --- a/README.md +++ b/README.md @@ -16,15 +16,9 @@ terraform-plugin-framework is a module for building [Terraform providers](https: ## Status -terraform-plugin-framework has reached **Public Beta** phase. We are committed to moving forward with the module, but cannot guarantee any of its interfaces will not change as long as it is in version 0. We're waiting for additional feedback, usage, and maturity before we're comfortable committing to APIs with the same years-long support timelines that [terraform-plugin-sdk](https://github.com/hashicorp/terraform-plugin-sdk) brings. We do not expect practitioner experiences to break or change as a result of these changes, only the abstractions surfaced to provider developers. +terraform-plugin-framework has reached **General Availability** phase and follows [semantic versioning](https://semver.org/) for Go and Terraform compatibility promises. We recommend only using tagged releases of this Go module and examining the CHANGELOG when upgrading to a new release. Major version releases contain breaking changes to existing provider code. Minor version releases introduce new functionality. Patch version releases contain bug fixes or documentation updates. -Refer to [Which SDK Should I Use?](https://terraform.io/docs/plugin/which-sdk.html) for more information. - -We believe terraform-plugin-framework is a suitable and reliable module to build Terraform providers on, and encourage community members that can afford occasional breaking changes to build with it. terraform-plugin-framework will eventually become generally available with a new major version release, at which point its interfaces will be stable, but we need real-world use and feedback before we can be comfortable making those commitments. - -We recommend only using tagged releases of this module, and examining the CHANGELOG when upgrading to a new release. Breaking changes will only be made in minor versions; patch releases will always maintain backwards compatibility. - -We welcome and appreciate issues and PRs discussing both the design and implementation of this module. +Refer to [Which SDK Should I Use?](https://terraform.io/docs/plugin/which-sdk.html) for more information about benefits over [terraform-plugin-sdk](https://github.com/hashicorp/terraform-plugin-sdk). ## Terraform CLI Compatibility diff --git a/website/docs/plugin/framework/acctests.mdx b/website/docs/plugin/framework/acctests.mdx index 0ea910d7b..324744062 100644 --- a/website/docs/plugin/framework/acctests.mdx +++ b/website/docs/plugin/framework/acctests.mdx @@ -7,8 +7,6 @@ description: >- # Acceptance Tests --> **Note:** The Plugin Framework is in beta. - You can implement testing with the [acceptance test framework](/plugin/sdkv2/testing/acceptance-tests) shipped with SDKv2. Writing and running tests is similar to SDKv2 providers, with the following exceptions: diff --git a/website/docs/plugin/framework/data-sources/configure.mdx b/website/docs/plugin/framework/data-sources/configure.mdx index 39e24e31f..2cd749cc3 100644 --- a/website/docs/plugin/framework/data-sources/configure.mdx +++ b/website/docs/plugin/framework/data-sources/configure.mdx @@ -6,8 +6,6 @@ description: >- # Configure Data Sources --> **Note:** The Plugin Framework is in beta. - [Data sources](/plugin/framework/data-sources) may require provider-level data or remote system clients to operate correctly. The framework supports the ability to configure this data and/or clients once within the provider, then pass that information to data sources by adding the `Configure` method. ## Prepare Provider Configure Method diff --git a/website/docs/plugin/framework/data-sources/index.mdx b/website/docs/plugin/framework/data-sources/index.mdx index 5643f1b14..c15aea696 100644 --- a/website/docs/plugin/framework/data-sources/index.mdx +++ b/website/docs/plugin/framework/data-sources/index.mdx @@ -7,8 +7,6 @@ description: >- # Data Sources --> **Note:** The Plugin Framework is in beta. - [Data sources](/language/data-sources) are an abstraction that allow Terraform to reference external data. Unlike [managed resources](/language/resources), Terraform does not manage the lifecycle of the resource or data. Data sources are intended to have no side-effects. This page describes the basic implementation details required for supporting a data source within the provider. Further documentation is available for deeper data source concepts: diff --git a/website/docs/plugin/framework/data-sources/timeouts.mdx b/website/docs/plugin/framework/data-sources/timeouts.mdx index 3ff4123e6..3572aece2 100644 --- a/website/docs/plugin/framework/data-sources/timeouts.mdx +++ b/website/docs/plugin/framework/data-sources/timeouts.mdx @@ -6,8 +6,6 @@ description: >- # Timeouts --> **Note:** The Plugin Framework is in beta. - The reality of cloud infrastructure is that it typically takes time to perform operations such as booting operating systems, discovering services, and replicating state across network edges. As the provider developer you should take known delays in data source APIs into account in the `Read` function of the data source. Terraform supports configurable timeouts to assist in these situations. The Framework can be used in conjunction with the [terraform-plugin-framework-timeouts](https://github.com/hashicorp/terraform-plugin-framework-timeouts) module in order to allow defining timeouts in configuration and have them be available in the `Read` function. diff --git a/website/docs/plugin/framework/data-sources/validate-configuration.mdx b/website/docs/plugin/framework/data-sources/validate-configuration.mdx index 7b4ccedd7..6002089f3 100644 --- a/website/docs/plugin/framework/data-sources/validate-configuration.mdx +++ b/website/docs/plugin/framework/data-sources/validate-configuration.mdx @@ -6,8 +6,6 @@ description: >- # Validate Configuration --> **Note:** The Plugin Framework is in beta. - [Data sources](/plugin/framework/data-sources) support validating an entire practitioner configuration in either declarative or imperative logic. Feedback, such as required syntax or acceptable combinations of values, is returned via [diagnostics](/plugin/framework/diagnostics). This page describes implementation details for validating entire data source configurations, typically referencing multiple attributes. Further documentation is available for other configuration validation concepts: diff --git a/website/docs/plugin/framework/debugging.mdx b/website/docs/plugin/framework/debugging.mdx index 54bed928b..ef1f8351e 100644 --- a/website/docs/plugin/framework/debugging.mdx +++ b/website/docs/plugin/framework/debugging.mdx @@ -5,8 +5,6 @@ description: How to implement debugger support in Framework Terraform providers. # Debugging Framework Providers --> **Note:** The Plugin Framework is in beta. - This page contains implementation details for inspecting runtime information of a Terraform provider developed with Framework via a debugger tool by adjusting the [provider server](/plugin/framework/provider-servers) implementation. Review the top level [Debugging](/plugin/debugging) page for information pertaining to the overall Terraform provider debugging process and other inspection options, such as log-based debugging. ## Code Implementation diff --git a/website/docs/plugin/framework/diagnostics.mdx b/website/docs/plugin/framework/diagnostics.mdx index cc1d1d9a3..78933fce3 100644 --- a/website/docs/plugin/framework/diagnostics.mdx +++ b/website/docs/plugin/framework/diagnostics.mdx @@ -7,8 +7,6 @@ description: |- # Returning Errors and Warnings --> **Note:** The Plugin Framework is in beta. - Providers use `Diagnostics` to surface errors and warnings to practitioners, such as contextual messages returned from Terraform CLI at the end of command output: diff --git a/website/docs/plugin/framework/handling-data/accessing-values.mdx b/website/docs/plugin/framework/handling-data/accessing-values.mdx index e86e863b3..b07ce4911 100644 --- a/website/docs/plugin/framework/handling-data/accessing-values.mdx +++ b/website/docs/plugin/framework/handling-data/accessing-values.mdx @@ -7,8 +7,6 @@ description: |- # Accessing State, Config, and Plan --> **Note:** The Plugin Framework is in beta. - There are various points at which the provider needs access to the data from the practitioner's configuration, Terraform's state, or generated plan. The same patterns are used for accessing this data, regardless of diff --git a/website/docs/plugin/framework/handling-data/attributes.mdx b/website/docs/plugin/framework/handling-data/attributes.mdx index 03931b7ce..61a92d832 100644 --- a/website/docs/plugin/framework/handling-data/attributes.mdx +++ b/website/docs/plugin/framework/handling-data/attributes.mdx @@ -7,8 +7,6 @@ description: >- # Attribute Types --> **Note:** The Plugin Framework is in beta. - Attributes are the fields in a resource, data source, or provider. They hold the values that end up in state. Every attribute has an attribute type, which describes the constraints on the data the attribute can hold. When you access an diff --git a/website/docs/plugin/framework/handling-data/path-expressions.mdx b/website/docs/plugin/framework/handling-data/path-expressions.mdx index 83b1bd1fe..467fedf43 100644 --- a/website/docs/plugin/framework/handling-data/path-expressions.mdx +++ b/website/docs/plugin/framework/handling-data/path-expressions.mdx @@ -8,8 +8,6 @@ description: >- # Path Expressions --> **Note:** The Plugin Framework is in beta. - Path expressions are logic built on top of [paths](/plugin/framework/paths), which may represent one or more actual paths within a schema or schema-based data. Expressions enable providers to work outside the restrictions of absolute paths and steps. ## Usage diff --git a/website/docs/plugin/framework/handling-data/paths.mdx b/website/docs/plugin/framework/handling-data/paths.mdx index f3c602089..0ccbe0a42 100644 --- a/website/docs/plugin/framework/handling-data/paths.mdx +++ b/website/docs/plugin/framework/handling-data/paths.mdx @@ -7,8 +7,6 @@ description: >- # Paths --> **Note:** The Plugin Framework is in beta. - An exact location within a [schema](/plugin/framework/handling-data/schemas) or schema-based data such as [`tfsdk.Config`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/tfsdk#Config), [`tfsdk.Plan`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/tfsdk#Plan), or [`tfsdk.State`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/tfsdk#State), is referred to as a path. ## Usage diff --git a/website/docs/plugin/framework/handling-data/schemas.mdx b/website/docs/plugin/framework/handling-data/schemas.mdx index 48014a597..2279e01cc 100644 --- a/website/docs/plugin/framework/handling-data/schemas.mdx +++ b/website/docs/plugin/framework/handling-data/schemas.mdx @@ -7,8 +7,6 @@ description: >- # Schemas --> **Note:** The Plugin Framework is in beta. - Schemas specify the constraints of Terraform configuration blocks. They define what fields a provider, resource, or data source configuration block has, and give Terraform metadata about those fields. You can think of the schema as the "type information" or diff --git a/website/docs/plugin/framework/handling-data/writing-state.mdx b/website/docs/plugin/framework/handling-data/writing-state.mdx index a9adaf084..b18e57750 100644 --- a/website/docs/plugin/framework/handling-data/writing-state.mdx +++ b/website/docs/plugin/framework/handling-data/writing-state.mdx @@ -7,8 +7,6 @@ description: >- # Writing State --> **Note:** The Plugin Framework is in beta. - One of the primary jobs of a Terraform provider is to manage the provider's resources and data sources in the [Terraform state](/language/state). Writing values to state is something that provider developers will do frequently. diff --git a/website/docs/plugin/framework/index.mdx b/website/docs/plugin/framework/index.mdx index 0bae6b334..c1acecd10 100644 --- a/website/docs/plugin/framework/index.mdx +++ b/website/docs/plugin/framework/index.mdx @@ -6,8 +6,6 @@ description: |- # Terraform Plugin Framework --> **Note:** The Plugin Framework is in beta. - The plugin framework is a new way to develop Terraform Plugins on [protocol version 6](/plugin/how-terraform-works#protocol-version-6) or [protocol version 5](/plugin/how-terraform-works#protocol-version-5). It offers improvements and new features from [Terraform Plugin SDKv2](/plugin/sdkv2). ~> **Important**: [Which SDK Should I Use?](/plugin/which-sdk) explains the differences between [Teraform Plugin SDKv2](/plugin/sdkv2) and Terraform Plugin Framework to help you decide which option is right for your provider. diff --git a/website/docs/plugin/framework/migrating/attributes-blocks/attribute-schema.mdx b/website/docs/plugin/framework/migrating/attributes-blocks/attribute-schema.mdx index 37a303d43..63498ea50 100644 --- a/website/docs/plugin/framework/migrating/attributes-blocks/attribute-schema.mdx +++ b/website/docs/plugin/framework/migrating/attributes-blocks/attribute-schema.mdx @@ -6,8 +6,6 @@ description: >- # Attribute Schema --> **Note:** The Plugin Framework is in beta. - Attributes define how users can configure values for your Terraform provider, resources, and data sources. Refer to [Schemas - Attributes](/plugin/framework/handling-data/schemas#attributes) in the Framework documentation for details. diff --git a/website/docs/plugin/framework/migrating/attributes-blocks/blocks-computed.mdx b/website/docs/plugin/framework/migrating/attributes-blocks/blocks-computed.mdx index 5ca7564cf..32afdb0a0 100644 --- a/website/docs/plugin/framework/migrating/attributes-blocks/blocks-computed.mdx +++ b/website/docs/plugin/framework/migrating/attributes-blocks/blocks-computed.mdx @@ -6,8 +6,6 @@ description: >- # Blocks with Computed Fields --> **Note:** The Plugin Framework is in beta. - Some providers, resources, and data sources include repeatable nested blocks in their attributes. Some blocks contain fields with `Computed: true`, which means that the provider code can define the value or that it could come from the output of terraform apply (e.g., the ID of an EC2 instance). diff --git a/website/docs/plugin/framework/migrating/attributes-blocks/blocks.mdx b/website/docs/plugin/framework/migrating/attributes-blocks/blocks.mdx index a84dd55d7..0e2b4970b 100644 --- a/website/docs/plugin/framework/migrating/attributes-blocks/blocks.mdx +++ b/website/docs/plugin/framework/migrating/attributes-blocks/blocks.mdx @@ -6,8 +6,6 @@ description: >- # Blocks --> **Note:** The Plugin Framework is in beta. - Some providers, resources, and data sources include repeatable nested blocks in their attributes. These nested blocks typically represent separate objects that are related to (or embedded within) the containing object. diff --git a/website/docs/plugin/framework/migrating/attributes-blocks/default-values.mdx b/website/docs/plugin/framework/migrating/attributes-blocks/default-values.mdx index b0322793d..41d2013d0 100644 --- a/website/docs/plugin/framework/migrating/attributes-blocks/default-values.mdx +++ b/website/docs/plugin/framework/migrating/attributes-blocks/default-values.mdx @@ -7,8 +7,6 @@ description: >- # Default Values --> **Note:** The Plugin Framework is in beta. - Default values set a value for an attribute when the Terraform configuration does not provide one. In SDKv2, default values are set via fields on an attribute's schema. In the Framework, you set default values via plan modification. Refer to diff --git a/website/docs/plugin/framework/migrating/attributes-blocks/fields.mdx b/website/docs/plugin/framework/migrating/attributes-blocks/fields.mdx index 3dea7f97c..672a77b90 100644 --- a/website/docs/plugin/framework/migrating/attributes-blocks/fields.mdx +++ b/website/docs/plugin/framework/migrating/attributes-blocks/fields.mdx @@ -6,8 +6,6 @@ description: >- # Attribute Fields --> **Note:** The Plugin Framework is in beta. - A subset of attribute fields, such as required, optional, computed, or sensitive, define attribute behavior as boolean flags. Refer to [Schemas - Attributes](/plugin/framework/handling-data/schemas#required) in the Framework documentation for details. diff --git a/website/docs/plugin/framework/migrating/attributes-blocks/force-new.mdx b/website/docs/plugin/framework/migrating/attributes-blocks/force-new.mdx index 00d9837f0..c6336f1b2 100644 --- a/website/docs/plugin/framework/migrating/attributes-blocks/force-new.mdx +++ b/website/docs/plugin/framework/migrating/attributes-blocks/force-new.mdx @@ -6,8 +6,6 @@ description: >- # ForceNew --> **Note:** The Plugin Framework is in beta. - In Terraform, sometimes a resource must be replaced when the value of an attribute changes. In SDKv2, this is accomplished via the `ForceNew` field. In the Framework, you implement the same behavior via a `RequiresReplace` plan modifier. Refer to diff --git a/website/docs/plugin/framework/migrating/attributes-blocks/types.mdx b/website/docs/plugin/framework/migrating/attributes-blocks/types.mdx index 4495b764f..9439323fb 100644 --- a/website/docs/plugin/framework/migrating/attributes-blocks/types.mdx +++ b/website/docs/plugin/framework/migrating/attributes-blocks/types.mdx @@ -6,8 +6,6 @@ description: >- # Attribute Types --> **Note:** The Plugin Framework is in beta. - An attribute either contains a primitive type, such as an integer or a string, or contains other attributes. Attributes that contain other attributes are referred to as nested attributes. Refer to [Schemas - Attributes](/plugin/framework/schemas#type) in the Framework documentation for details. diff --git a/website/docs/plugin/framework/migrating/attributes-blocks/validators-custom.mdx b/website/docs/plugin/framework/migrating/attributes-blocks/validators-custom.mdx index f4684e28e..a3c6ef784 100644 --- a/website/docs/plugin/framework/migrating/attributes-blocks/validators-custom.mdx +++ b/website/docs/plugin/framework/migrating/attributes-blocks/validators-custom.mdx @@ -6,8 +6,6 @@ description: >- # Custom Validators --> **Note:** The Plugin Framework is in beta. - You can write custom validations that give users feedback about required syntax, types, and acceptable values in your provider. The Framework has a collection of [predefined validators](https://github.com/hashicorp/terraform-plugin-framework-validators). Refer to diff --git a/website/docs/plugin/framework/migrating/attributes-blocks/validators-predefined.mdx b/website/docs/plugin/framework/migrating/attributes-blocks/validators-predefined.mdx index 97d0c4183..086af2721 100644 --- a/website/docs/plugin/framework/migrating/attributes-blocks/validators-predefined.mdx +++ b/website/docs/plugin/framework/migrating/attributes-blocks/validators-predefined.mdx @@ -7,8 +7,6 @@ description: >- # Validators - Predefined --> **Note:** The Plugin Framework is in beta. - Attribute validators ensure that attributes do or do not contain specific values. You can use predefined validators for many use cases, or implement custom validators. Refer to [Schemas - Validators](/plugin/framework/handling-data/schemas#validators) in the Framework documentation for details. Refer to the diff --git a/website/docs/plugin/framework/migrating/data-sources/index.mdx b/website/docs/plugin/framework/migrating/data-sources/index.mdx index 8a01bbca7..e765da1ef 100644 --- a/website/docs/plugin/framework/migrating/data-sources/index.mdx +++ b/website/docs/plugin/framework/migrating/data-sources/index.mdx @@ -6,8 +6,6 @@ description: >- # Data Sources --> **Note:** The Plugin Framework is in beta. - Data sources let Terraform reference external data. Unlike resources, Terraform does not create, update, or delete data sources, and makes no attempt to modify the underlying API. Data Sources are a read-only resource type, so they only implement a subset of the operations that resources do. Refer to [Data Sources](/plugin/framework/data-sources) diff --git a/website/docs/plugin/framework/migrating/data-sources/timeouts.mdx b/website/docs/plugin/framework/migrating/data-sources/timeouts.mdx index 0204cd445..63ee856a2 100644 --- a/website/docs/plugin/framework/migrating/data-sources/timeouts.mdx +++ b/website/docs/plugin/framework/migrating/data-sources/timeouts.mdx @@ -6,8 +6,6 @@ description: >- # Timeouts --> **Note:** The Plugin Framework is in beta. - The Framework can be used in conjunction with the [terraform-plugin-framework-timeouts](https://github.com/hashicorp/terraform-plugin-framework-timeouts) module in order to allow defining timeouts in configuration and have them be available in `Read` functions. ## Specifying Timeouts in Configuration diff --git a/website/docs/plugin/framework/migrating/index.mdx b/website/docs/plugin/framework/migrating/index.mdx index f1578ee10..82d21d51f 100644 --- a/website/docs/plugin/framework/migrating/index.mdx +++ b/website/docs/plugin/framework/migrating/index.mdx @@ -6,8 +6,6 @@ description: >- # Overview --> **Note:** The Plugin Framework is in beta. - This guide helps you migrate a Terraform provider from SDKv2 to the plugin Framework. We recommend migrating because the Framework has abstractions that make it easier to use, and it represents the future of Terraform plugin development. Refer to [Which SDK should I Use?](/plugin/which-sdk) for more details. This guide provides information and examples for most common use cases, but it does not discuss every nuance of migration. You can ask additional migration questions in the [HashiCorp Discuss forum](https://discuss.hashicorp.com/c/terraform-providers/tf-plugin-sdk/43). To request additions or updates to this guide, submit issues or pull requests to the [`terraform-plugin-framework` repository](https://github.com/hashicorp/terraform-plugin-framework). diff --git a/website/docs/plugin/framework/migrating/providers/index.mdx b/website/docs/plugin/framework/migrating/providers/index.mdx index 114916124..a0350c742 100644 --- a/website/docs/plugin/framework/migrating/providers/index.mdx +++ b/website/docs/plugin/framework/migrating/providers/index.mdx @@ -6,8 +6,6 @@ description: >- # Provider --> **Note:** The Plugin Framework is in beta. - Providers are Terraform plugins that define resources and data sources for practitioners to use. You serve your providers with a provider server so they can interact with Terraform. diff --git a/website/docs/plugin/framework/migrating/resources/crud.mdx b/website/docs/plugin/framework/migrating/resources/crud.mdx index a4f97c895..b48b125a7 100644 --- a/website/docs/plugin/framework/migrating/resources/crud.mdx +++ b/website/docs/plugin/framework/migrating/resources/crud.mdx @@ -6,8 +6,6 @@ description: >- # CRUD functions --> **Note:** The Plugin Framework is in beta. - In Terraform, a resource represents a single instance of a given resource type. They modify a specific resource in the API and in Terraform's state through a set of Create, Read, Update, and Delete (CRUD) functions. A resource's CRUD functions implement the logic required to manage your resources with Terraform. Refer to diff --git a/website/docs/plugin/framework/migrating/resources/import.mdx b/website/docs/plugin/framework/migrating/resources/import.mdx index b93adcd22..65be1fc99 100644 --- a/website/docs/plugin/framework/migrating/resources/import.mdx +++ b/website/docs/plugin/framework/migrating/resources/import.mdx @@ -7,8 +7,6 @@ description: >- # Import --> **Note:** The Plugin Framework is in beta. - Practitioners can use the [`terraform import` command](/cli/commands/import) to let Terraform begin managing existing infrastructure by importing an existing resource into their Terraform project's state. A resource's importer function implements the logic to add a resource to Terraform's state. Refer to diff --git a/website/docs/plugin/framework/migrating/resources/index.mdx b/website/docs/plugin/framework/migrating/resources/index.mdx index 827ebee47..60b91af5b 100644 --- a/website/docs/plugin/framework/migrating/resources/index.mdx +++ b/website/docs/plugin/framework/migrating/resources/index.mdx @@ -6,8 +6,6 @@ description: >- # Resources --> **Note:** The Plugin Framework is in beta. - Resources are an abstraction that allow Terraform to manage infrastructure objects by defining create, read, update, and delete functionality that maps onto API operations. Resource schemas define what fields a resource has, give Terraform metadata about those fields, and define how the resource behaves. Refer to diff --git a/website/docs/plugin/framework/migrating/resources/plan-modification.mdx b/website/docs/plugin/framework/migrating/resources/plan-modification.mdx index 7255f0037..eaeb3caa6 100644 --- a/website/docs/plugin/framework/migrating/resources/plan-modification.mdx +++ b/website/docs/plugin/framework/migrating/resources/plan-modification.mdx @@ -6,8 +6,6 @@ description: >- # Plan Modification --> **Note:** The Plugin Framework is in beta. - Your provider can modify the Terraform plan to match the expected end state. This can include replacing unknown values with expected known values or marking a resource that must be replaced. Refer to [Plan Modification](/plugin/framework/resources/plan-modification) in the Framework documentation for details. diff --git a/website/docs/plugin/framework/migrating/resources/state-upgrade.mdx b/website/docs/plugin/framework/migrating/resources/state-upgrade.mdx index 1cc1b5307..a1c1c7996 100644 --- a/website/docs/plugin/framework/migrating/resources/state-upgrade.mdx +++ b/website/docs/plugin/framework/migrating/resources/state-upgrade.mdx @@ -7,8 +7,6 @@ description: >- # State Upgraders --> **Note:** The Plugin Framework is in beta. - When you update a resource's implementation in your provider, some changes may not be compatible with old versions. You can create state upgraders to automatically migrate resources provisioned with old schema configurations. Refer to [State Upgrade](/plugin/framework/resources/state-upgrade) in the Framework documentation for details. diff --git a/website/docs/plugin/framework/migrating/resources/timeouts.mdx b/website/docs/plugin/framework/migrating/resources/timeouts.mdx index eadc4204a..0c4a2fd7e 100644 --- a/website/docs/plugin/framework/migrating/resources/timeouts.mdx +++ b/website/docs/plugin/framework/migrating/resources/timeouts.mdx @@ -6,8 +6,6 @@ description: >- # Timeouts --> **Note:** The Plugin Framework is in beta. - The Framework can be used in conjunction with the [terraform-plugin-framework-timeouts](https://github.com/hashicorp/terraform-plugin-framework-timeouts) module in order to allow defining timeouts in configuration and have them be available in CRUD functions. ## Specifying Timeouts in Configuration diff --git a/website/docs/plugin/framework/migrating/schema/index.mdx b/website/docs/plugin/framework/migrating/schema/index.mdx index 1890dba75..8a9c93995 100644 --- a/website/docs/plugin/framework/migrating/schema/index.mdx +++ b/website/docs/plugin/framework/migrating/schema/index.mdx @@ -6,8 +6,6 @@ description: >- # Schema --> **Note:** The Plugin Framework is in beta. - Providers, resources, and data sources all use schema to define their attributes and behavior. Schemas specify the constraints of Terraform configuration blocks and how the provider, resource, or data source behaves. Refer to [Schemas](/plugin/framework/handling-data/schemas) in the Framework documentation for details. diff --git a/website/docs/plugin/framework/migrating/testing.mdx b/website/docs/plugin/framework/migrating/testing.mdx index 5422bf592..de676d7db 100644 --- a/website/docs/plugin/framework/migrating/testing.mdx +++ b/website/docs/plugin/framework/migrating/testing.mdx @@ -6,8 +6,6 @@ description: >- # Testing --> **Note:** The Plugin Framework is in beta. - During migration, you should [write tests](#testing-migration) to verify that the behaviour of your provider has not been altered by the migration itself. You will also need to [update](#provider-factories) your tests too. diff --git a/website/docs/plugin/framework/provider-servers.mdx b/website/docs/plugin/framework/provider-servers.mdx index cadf708e1..ba123b6a9 100644 --- a/website/docs/plugin/framework/provider-servers.mdx +++ b/website/docs/plugin/framework/provider-servers.mdx @@ -7,8 +7,6 @@ description: >- # Provider Servers --> **Note:** The Plugin Framework is in beta. - Before a [provider](/plugin/framework/providers) can be used with Terraform, it must implement a [gRPC server](https://grpc.io) that supports Terraform-specific connection and handshake handling on startup. The server must then implement the [Terraform Plugin Protocol](/plugin/how-terraform-works#terraform-plugin-protocol). The framework handles the majority of the server implementation details, however it is useful from a provider developer perspective to understand the provider server details at least at a high level. diff --git a/website/docs/plugin/framework/providers/index.mdx b/website/docs/plugin/framework/providers/index.mdx index b6cc70b3b..e3cfce0ed 100644 --- a/website/docs/plugin/framework/providers/index.mdx +++ b/website/docs/plugin/framework/providers/index.mdx @@ -8,8 +8,6 @@ description: >- # Providers --> **Note:** The Plugin Framework is in beta. - Providers are Terraform plugins that define [resources](/plugin/framework/resources) and [data sources](/plugin/framework/data-sources) for practitioners to use. Providers are wrapped by a [provider server](/plugin/framework/provider-servers) for interacting with Terraform. This page describes the basic implementation details required for defining a provider. Further documentation is available for deeper provider concepts: diff --git a/website/docs/plugin/framework/providers/validate-configuration.mdx b/website/docs/plugin/framework/providers/validate-configuration.mdx index b33fe856e..03f275534 100644 --- a/website/docs/plugin/framework/providers/validate-configuration.mdx +++ b/website/docs/plugin/framework/providers/validate-configuration.mdx @@ -6,8 +6,6 @@ description: >- # Validate Configuration --> **Note:** The Plugin Framework is in beta. - [Providers](/plugin/framework/providers) support validating an entire practitioner configuration in either declarative or imperative logic. Feedback, such as required syntax or acceptable combinations of values, is returned via [diagnostics](/plugin/framework/diagnostics). This page describes implementation details for validating entire provider configurations, typically referencing multiple attributes. Further documentation is available for other configuration validation concepts: diff --git a/website/docs/plugin/framework/resources/configure.mdx b/website/docs/plugin/framework/resources/configure.mdx index c11a5debd..0ad464ff8 100644 --- a/website/docs/plugin/framework/resources/configure.mdx +++ b/website/docs/plugin/framework/resources/configure.mdx @@ -6,8 +6,6 @@ description: >- # Configure Resources --> **Note:** The Plugin Framework is in beta. - [Resources](/plugin/framework/resources) may require provider-level data or remote system clients to operate correctly. The framework supports the ability to configure this data and/or clients once within the provider, then pass that information to resources by adding the `Configure` method. ## Prepare Provider Configure Method diff --git a/website/docs/plugin/framework/resources/create.mdx b/website/docs/plugin/framework/resources/create.mdx index 47ead3521..8634fc014 100644 --- a/website/docs/plugin/framework/resources/create.mdx +++ b/website/docs/plugin/framework/resources/create.mdx @@ -6,8 +6,6 @@ description: >- # Create Resources --> **Note:** The Plugin Framework is in beta. - Creation is part of the basic Terraform lifecycle for managing resources. During the [`terraform apply` command](/cli/commands/apply), Terraform calls the provider `ApplyResourceChange` RPC, in which the framework calls the [`resource.Resource` interface `Create` method](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/resource#Resource.Create). The request contains Terraform configuration and plan data. The response expects the applied Terraform state data, including any computed values. The data is defined by the [schema](/plugin/framework/schemas) of the resource. Other resource lifecycle implementations include: diff --git a/website/docs/plugin/framework/resources/delete.mdx b/website/docs/plugin/framework/resources/delete.mdx index 68334c055..98dce7615 100644 --- a/website/docs/plugin/framework/resources/delete.mdx +++ b/website/docs/plugin/framework/resources/delete.mdx @@ -6,8 +6,6 @@ description: >- # Delete Resources --> **Note:** The Plugin Framework is in beta. - Deletion is part of the basic Terraform lifecycle for managing resources. During the [`terraform apply` command](/cli/commands/apply), Terraform calls the provider `ApplyResourceChange` RPC, in which the framework calls the [`resource.Resource` interface `Delete` method](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/resource#Resource.Delete). The request contains Terraform prior state data. The response is only for returning diagnostics. The data is defined by the [schema](/plugin/framework/schemas) of the resource. Terraform 1.3 and later enables deletion planning, which resources can implement to return warning and error diagnostics. For additional information, refer to the [resource plan modification documentation](/plugin/framework/resources/plan-modification#resource-destroy-plan-diagnostics). diff --git a/website/docs/plugin/framework/resources/import.mdx b/website/docs/plugin/framework/resources/import.mdx index e1222e374..5060f9f0f 100644 --- a/website/docs/plugin/framework/resources/import.mdx +++ b/website/docs/plugin/framework/resources/import.mdx @@ -6,8 +6,6 @@ description: >- # Resource Import --> **Note:** The Plugin Framework is in beta. - Practitioners can use the [`terraform import` command](/cli/commands/import) to let Terraform begin managing existing infrastructure resources. Resources can implement the `ImportState` method, which must either specify enough Terraform state for the `Read` method to refresh [`resource.Resource`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/resource#Resource) or return an error. ## Define Resource ImportState Method diff --git a/website/docs/plugin/framework/resources/index.mdx b/website/docs/plugin/framework/resources/index.mdx index 373dfb644..29b0b9892 100644 --- a/website/docs/plugin/framework/resources/index.mdx +++ b/website/docs/plugin/framework/resources/index.mdx @@ -7,8 +7,6 @@ description: >- # Resources --> **Note:** The Plugin Framework is in beta. - [Resources](/language/resources) are an abstraction that allow Terraform to manage infrastructure objects, such as a compute instance, an access policy, or disk. Terraform assumes that every resource: - operates as a pure key/value store, with values getting returned exactly as they were written. diff --git a/website/docs/plugin/framework/resources/plan-modification.mdx b/website/docs/plugin/framework/resources/plan-modification.mdx index 3eb458f44..a177a6bb5 100644 --- a/website/docs/plugin/framework/resources/plan-modification.mdx +++ b/website/docs/plugin/framework/resources/plan-modification.mdx @@ -7,8 +7,6 @@ description: >- # Plan Modification --> **Note:** The Plugin Framework is in beta. - After [validation](/plugin/framework/validation) and before applying configuration changes, Terraform generates a plan that describes the expected values and behaviors of those changes. Providers can then tailor the plan to match the expected end state. For example, they may replace unknown values with expected known values or mark a resource that must be replaced. Users can perform this plan modification for an attribute or an entire resource. ## Plan Modification Process diff --git a/website/docs/plugin/framework/resources/private-state.mdx b/website/docs/plugin/framework/resources/private-state.mdx index 9b8caa43b..8c1412b45 100644 --- a/website/docs/plugin/framework/resources/private-state.mdx +++ b/website/docs/plugin/framework/resources/private-state.mdx @@ -7,8 +7,6 @@ description: >- # Private State Management --> **Note:** The Plugin Framework is in beta. - Resource private state is provider maintained data that is stored in Terraform state alongside the schema-defined data. Private state is never accessed or exposed by Terraform plans, however providers can use this data storage for advanced use cases. ## Usage diff --git a/website/docs/plugin/framework/resources/read.mdx b/website/docs/plugin/framework/resources/read.mdx index 35c88e24f..e005f6e21 100644 --- a/website/docs/plugin/framework/resources/read.mdx +++ b/website/docs/plugin/framework/resources/read.mdx @@ -6,8 +6,6 @@ description: >- # Read Resources --> **Note:** The Plugin Framework is in beta. - Read (refresh) is part of the basic Terraform lifecycle for managing resources. During the [`terraform apply`](/cli/commands/apply), [`terraform plan`](/cli/commands/plan), and [`terraform refresh`](/cli/commands/refresh) commands, Terraform calls the provider `ReadResource` RPC, in which the framework calls the [`resource.Resource` interface `Read` method](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/resource#Resource.Read). The `Read` method is also executed after [resource import](/plugin/framework/resources/import). The request contains Terraform prior state data. The response contains the refreshed state data. The data is defined by the [schema](/plugin/framework/schemas) of the resource. Other resource lifecycle implementations include: diff --git a/website/docs/plugin/framework/resources/state-upgrade.mdx b/website/docs/plugin/framework/resources/state-upgrade.mdx index 145fffe96..c0237708c 100644 --- a/website/docs/plugin/framework/resources/state-upgrade.mdx +++ b/website/docs/plugin/framework/resources/state-upgrade.mdx @@ -7,8 +7,6 @@ description: >- # State Upgrade --> **Note:** The Plugin Framework is in beta. - A resource schema captures the structure and types of the resource [state](/language/state). Any state data that does not conform to the resource schema will generate errors or may not be persisted properly. Over time, it may be necessary for resources to make breaking changes to their schemas, such as changing an attribute type. Terraform supports versioning of these resource schemas and the current version is saved into the Terraform state. When the provider advertises a newer schema version, Terraform will call back to the provider to attempt to upgrade from the saved schema version to the one advertised. This operation is performed prior to planning, but with a configured provider. -> Some versions of Terraform CLI will also request state upgrades even when the current schema version matches the state version. The framework will automatically handle this request. diff --git a/website/docs/plugin/framework/resources/timeouts.mdx b/website/docs/plugin/framework/resources/timeouts.mdx index cbe80c91c..1919f9c30 100644 --- a/website/docs/plugin/framework/resources/timeouts.mdx +++ b/website/docs/plugin/framework/resources/timeouts.mdx @@ -6,8 +6,6 @@ description: >- # Timeouts --> **Note:** The Plugin Framework is in beta. - The reality of cloud infrastructure is that it typically takes time to perform operations such as booting operating systems, discovering services, and replicating state across network edges. As the provider developer you should take known delays in resource APIs into account in the CRUD functions of the resource. Terraform supports configurable timeouts to assist in these situations. The Framework can be used in conjunction with the [terraform-plugin-framework-timeouts](https://github.com/hashicorp/terraform-plugin-framework-timeouts) module in order to allow defining timeouts in configuration and have them be available in CRUD functions. diff --git a/website/docs/plugin/framework/resources/update.mdx b/website/docs/plugin/framework/resources/update.mdx index ad407112c..e384636b8 100644 --- a/website/docs/plugin/framework/resources/update.mdx +++ b/website/docs/plugin/framework/resources/update.mdx @@ -6,8 +6,6 @@ description: >- # Update Resources --> **Note:** The Plugin Framework is in beta. - In-place update is part of the basic Terraform lifecycle for managing resources. During the [`terraform apply` command](/cli/commands/apply), Terraform calls the provider `ApplyResourceChange` RPC, in which the framework calls the [`resource.Resource` interface `Update` method](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/resource#Resource.Update). The request contains Terraform prior state, configuration, and plan data. The response contains updated state data. The data is defined by the [schema](/plugin/framework/schemas) of the resource. To ensure that Terraform plans replacement of a resource, rather than perform an in-place update, use the [`resource.RequiresReplace()` attribute plan modifier](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/resource#RequiresReplace) in the schema or implement [resource plan modification](/plugin/framework/resources/plan-modification). diff --git a/website/docs/plugin/framework/resources/validate-configuration.mdx b/website/docs/plugin/framework/resources/validate-configuration.mdx index c4870c852..86f2a8e88 100644 --- a/website/docs/plugin/framework/resources/validate-configuration.mdx +++ b/website/docs/plugin/framework/resources/validate-configuration.mdx @@ -6,8 +6,6 @@ description: >- # Validate Configuration --> **Note:** The Plugin Framework is in beta. - [Resources](/plugin/framework/resources) support validating an entire practitioner configuration in either declarative or imperative logic. Feedback, such as required syntax or acceptable combinations of values, is returned via [diagnostics](/plugin/framework/diagnostics). This page describes implementation details for validating entire resource configurations, typically referencing multiple attributes. Further documentation is available for other configuration validation concepts: diff --git a/website/docs/plugin/framework/validation.mdx b/website/docs/plugin/framework/validation.mdx index 11c4bc4af..e22c09ea1 100644 --- a/website/docs/plugin/framework/validation.mdx +++ b/website/docs/plugin/framework/validation.mdx @@ -5,8 +5,6 @@ description: How to validate configuration values using the provider development # Validation --> **Note:** The Plugin Framework is in beta. - The framework can return [diagnostics](/plugin/framework/diagnostics) feedback for values in provider, resource, and data source configurations. This allows you to write validations that give users feedback about required syntax, types, and acceptable values. This page describes single attribute and type validation concepts that can be used in any data source, provider, or resource schema. Further documentation is available for other configuration validation concepts: