diff --git a/website/docs/plugin/framework/data-sources/timeouts.mdx b/website/docs/plugin/framework/data-sources/timeouts.mdx index 8536bc4c2..c0005a0ec 100644 --- a/website/docs/plugin/framework/data-sources/timeouts.mdx +++ b/website/docs/plugin/framework/data-sources/timeouts.mdx @@ -36,6 +36,15 @@ resource "timeouts_example" "example" { } ``` +Import the [timeouts module](https://github.com/hashicorp/terraform-plugin-framework-timeouts). + +```go +import ( + /* ... */ + "github.com/hashicorp/terraform-plugin-framework-timeouts/datasource/timeouts" +) +```` + You can use this module to mutate the `schema.Schema` as follows: ```go diff --git a/website/docs/plugin/framework/migrating/attributes-blocks/blocks.mdx b/website/docs/plugin/framework/migrating/attributes-blocks/blocks.mdx index a4541dbdc..0195e2a68 100644 --- a/website/docs/plugin/framework/migrating/attributes-blocks/blocks.mdx +++ b/website/docs/plugin/framework/migrating/attributes-blocks/blocks.mdx @@ -14,6 +14,38 @@ This page explains how to migrate nested blocks that are not computed (i.e., do [Blocks with Computed Fields](/plugin/framework/migrating/attributes-blocks/blocks-computed) for more details about migrating nested blocks that contain fields that are computed. +The following table describes the mapping between [SDK Schema Fields](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk/helper/schema#Schema) and the Framework. + +| SDK Schema Field | Framework | +|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Type | [ListNestedBlock](/plugin/framework/migrating/attributes-blocks/blocks), [SetNestedBlock](/plugin/framework/migrating/attributes-blocks/blocks) | +| ConfigMode | Schema must be explictly defined using [Attributes](/plugin/framework/migrating/attributes-blocks/attribute-schema) and [Blocks](/plugin/framework/migrating/attributes-blocks/blocks) | +| Required | [listvalidator.IsRequired](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/listvalidator#IsRequired), [setvalidator.IsRequired](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/setvalidator#IsRequired) | +| Optional | N/A - no implementation required | +| Computed | [Blocks with Computed Fields](/plugin/framework/migrating/attributes-blocks/blocks-computed) | +| ForceNew | [RequiresReplace](/plugin/framework/migrating/attributes-blocks/force-new) on `PlanModifiers` field on attribute within block or implementation of [ResourceWithModifyPlan](/plugin/framework/migrating/resources/plan-modification#framework) interface | +| DiffSuppressFunc | [PlanModifiers](/framework/migrating/resources/plan-modification#framework) field on attribute within block or implementation of [ResourceWithModifyPlan](/plugin/framework/migrating/resources/plan-modification#framework) interface | +| DiffSuppressOnRefresh | [Read](/plugin/framework/migrating/resources/crud) method on resource | +| Default | [PlanModifiers](/framework/migrating/resources/plan-modification#framework) field on attribute within block or implementation of [ResourceWithModifyPlan](/plugin/framework/migrating/resources/plan-modification#framework) interface | +| DefaultFunc | [PlanModifiers](/framework/migrating/resources/plan-modification#framework) field on attribute within block or implementation of [ResourceWithModifyPlan](/plugin/framework/migrating/resources/plan-modification#framework) interface | +| Description | `Description` field on block | +| InputDefault | N/A - no longer valid | +| StateFunc | Requires implementation of bespoke logic before storing state, for instance in resource [Create method](plugin/framework/migrating/resources/crud#framework-1) | +| Elem | `NestedObject` within block | +| MaxItems | Use [listValidator.SizeAtMost](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/listvalidator#SizeAtMost) or [setvalidator.SizeAtMost](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/setvalidator#SizeAtMost) on `Validators` field on `ListNestedBlock` or `SetNestedBlock` | +| MinItems | Use [listValidator.SizeAtLeast](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/listvalidator#SizeAtLeast) or [setvalidator.SizeAtLeast](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/setvalidator#SizeAtLeast) on `Validators` field on `ListNestedBlock` or `SetNestedBlock` | +| Set | N/A - no implementation required | | +| ComputedWhen | N/A - no longer valid | +| ConflictsWith | [Predefined Validators](/plugin/framework/migrating/attributes-blocks/validators-predefined) | +| ExactlyOneOf | [Predefined Validators](/plugin/framework/migrating/attributes-blocks/validators-predefined) | +| AtLeastOneOf | [Predefined Validators](/plugin/framework/migrating/attributes-blocks/validators-predefined) | +| RequiredWith | [Predefined Validators](/plugin/framework/migrating/attributes-blocks/validators-predefined) | +| Deprecated | `DeprecationMessage` field on attribute within block | +| ValidateFunc | [Predefined Validators](/plugin/framework/migrating/attributes-blocks/validators-predefined) and [Custom Validators](/plugin/framework/migrating/attributes-blocks/validators-custom) | +| ValidateDiagFunc | [Predefined Validators](/plugin/framework/migrating/attributes-blocks/validators-predefined) and [Custom Validators](/plugin/framework/migrating/attributes-blocks/validators-custom) | +| Sensitive | N/A - only supported on attributes | + + ## Nested Block Example The following example shows a nested block in Terraform resource configuration. The `subject` nested diff --git a/website/docs/plugin/framework/migrating/attributes-blocks/fields.mdx b/website/docs/plugin/framework/migrating/attributes-blocks/fields.mdx index 672a77b90..5ec726309 100644 --- a/website/docs/plugin/framework/migrating/attributes-blocks/fields.mdx +++ b/website/docs/plugin/framework/migrating/attributes-blocks/fields.mdx @@ -9,6 +9,38 @@ description: >- 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. +The following table describes the mapping between [SDK Schema Fields](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk/helper/schema#Schema) and the Framework. + +| SDK Schema Field | Framework | +|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Type | [Attribute Types](/plugin/framework/migrating/attributes-blocks/types) | +| ConfigMode | Schema must be explictly defined using [Attributes](/plugin/framework/migrating/attributes-blocks/attribute-schema) and [Blocks](/plugin/framework/migrating/attributes-blocks/blocks) | +| Required | `Required` field on attribute | +| Optional | `Optional` field on attribute | +| Computed | `Computed` field on attribute | +| ForceNew | [RequiresReplace](/plugin/framework/migrating/attributes-blocks/force-new) on `PlanModifiers` field on attribute or implementation of [ResourceWithModifyPlan](/plugin/framework/migrating/resources/plan-modification#framework) interface | +| DiffSuppressFunc | [PlanModifiers](/framework/migrating/resources/plan-modification#framework) field on attribute or implementation of [ResourceWithModifyPlan](/plugin/framework/migrating/resources/plan-modification#framework) interface | +| DiffSuppressOnRefresh | [Read](/plugin/framework/migrating/resources/crud) method on resource | +| Default | [PlanModifiers](/framework/migrating/resources/plan-modification#framework) field on attribute or implementation of [ResourceWithModifyPlan](/plugin/framework/migrating/resources/plan-modification#framework) interface | +| DefaultFunc | [PlanModifiers](/framework/migrating/resources/plan-modification#framework) field on attribute or implementation of [ResourceWithModifyPlan](/plugin/framework/migrating/resources/plan-modification#framework) interface | +| Description | `Description` field on attribute | +| InputDefault | N/A - no longer valid | +| StateFunc | Requires implementation of bespoke logic before storing state, for instance in resource [Create method](plugin/framework/migrating/resources/crud#framework-1) | +| Elem | `ElementType` on [ListAttribute](/plugin/framework/migrating/attributes-blocks/types), [MapAttribute](/plugin/framework/migrating/attributes-blocks/types) or [SetAttribute](/plugin/framework/migrating/attributes-blocks/types). Refer to [Blocks](/plugin/framework/migrating/attributes-blocks/blocks) if `schema.Resource` is present in `Elem`. | +| MaxItems | Use [listValidator.SizeAtMost](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/listvalidator#SizeAtMost), [mapvalidator.SizeAtMost](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/mapvalidator#SizeAtMost) or [setvalidator.SizeAtMost](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/setvalidator#SizeAtMost) on `Validators` field on list, map or set attribute | +| MinItems | Use [listValidator.SizeAtLeast](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/listvalidator#SizeAtLeast), [mapvalidator.SizeAtLeast](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/mapvalidator#SizeAtLeast) or [setvalidator.SizeAtLeast](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/setvalidator#SizeAtLeast) on `Validators` field on list, map or set attribute | +| Set | N/A - no implementation required | | +| ComputedWhen | N/A - no longer valid | +| ConflictsWith | [Predefined Validators](/plugin/framework/migrating/attributes-blocks/validators-predefined) | +| ExactlyOneOf | [Predefined Validators](/plugin/framework/migrating/attributes-blocks/validators-predefined) | +| AtLeastOneOf | [Predefined Validators](/plugin/framework/migrating/attributes-blocks/validators-predefined) | +| RequiredWith | [Predefined Validators](/plugin/framework/migrating/attributes-blocks/validators-predefined) | +| Deprecated | `DeprecationMessage` field on attribute | +| ValidateFunc | [Predefined Validators](/plugin/framework/migrating/attributes-blocks/validators-predefined) and [Custom Validators](/plugin/framework/migrating/attributes-blocks/validators-custom) | +| ValidateDiagFunc | [Predefined Validators](/plugin/framework/migrating/attributes-blocks/validators-predefined) and [Custom Validators](/plugin/framework/migrating/attributes-blocks/validators-custom) | +| Sensitive | `Sensitive` field on attribute | + + This page explains how to migrate the required, optional, computed, and sensitive attribute fields from SDKv2 to the Framework. 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 086af2721..4f326b827 100644 --- a/website/docs/plugin/framework/migrating/attributes-blocks/validators-predefined.mdx +++ b/website/docs/plugin/framework/migrating/attributes-blocks/validators-predefined.mdx @@ -13,6 +13,20 @@ the Framework documentation for details. Refer to the [Attributes - Custom Validators](/plugin/framework/migrating/attributes-blocks/validators-custom) page in this guide to learn how to implement custom validators. +The following table describes the mapping between predefined validators in SDKv2 and the Framework. You should use an +attribute validator for [per-attribute validation](/plugin/framework/validation#attribute-validation), or a +[data source validator](/plugin/framework/data-sources/validate-configuration), +[provider validator](plugin/framework/providers/validate-configuration) or +[resource validator](/plugin/framework/resources/validate-configuration) for declaring validation at the level of the +data source, provider or resource, respectively. + +| SDK Attribute Field | Framework Attribute Validator | Framework Data Source Validator | Framework Provider Validator | Framework Resource Validator | +|---------------------|---------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| AtLeastOneOf | {TYPE}validator.AtLeastOneOf() | [datasourcevalidator.AtLeastOneOf()](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/datasourcevalidator#AtLeastOneOf) | [providervalidator.AtLeastOneOf()](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/providervalidator#AtLeastOneOf) | [resourcevalidator.AtLeastOneOf()](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/resourcevalidator#AtLeastOneOf) | +| ConflictsWith | {TYPE}validator.ConflictsWith() | [datasourcevalidator.Conflicting()](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/datasourcevalidator#Conflicting) | [providervalidator.Conflicting()](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/providervalidator#Conflicting) | [resourcevalidator.Conflicting()](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/resourcevalidator#Conflicting) | +| ExactlyOneOf | {TYPE}validator.ExactlyOneOf() | [datasourcevalidator.ExactlyOneOf()](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/datasourcevalidator#ExactlyOneOf) | [providervalidator.ExactlyOneOf()](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/providervalidator#ExactlyOneOf) | [resourcevalidator.ExactlyOneOf()](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/resourcevalidator#ExactlyOneOf) | +| RequiredWith | {TYPE}validator.AlsoRequires() | [datasourcevalidator.RequiredTogether()](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/datasourcevalidator#RequiredTogether) | [providervalidator.RequiredTogether()](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/providervalidator#RequiredTogether) | [resourcevalidator.RequiredTogether()](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/resourcevalidator#RequiredTogether) | + This page explains how to migrate a predefined validator from SDKv2 to the Framework. ## SDKv2 diff --git a/website/docs/plugin/framework/migrating/data-sources/timeouts.mdx b/website/docs/plugin/framework/migrating/data-sources/timeouts.mdx index 3effca34d..9728c9099 100644 --- a/website/docs/plugin/framework/migrating/data-sources/timeouts.mdx +++ b/website/docs/plugin/framework/migrating/data-sources/timeouts.mdx @@ -34,6 +34,15 @@ resource "timeouts_example" "example" { } ``` +Import the [timeouts module](https://github.com/hashicorp/terraform-plugin-framework-timeouts). + +```go +import ( + /* ... */ + "github.com/hashicorp/terraform-plugin-framework-timeouts/datasource/timeouts" +) +```` + You can use this module to mutate the `schema.Schema` as follows: ```go diff --git a/website/docs/plugin/framework/migrating/resources/timeouts.mdx b/website/docs/plugin/framework/migrating/resources/timeouts.mdx index 82186a1b0..c52e76ed4 100644 --- a/website/docs/plugin/framework/migrating/resources/timeouts.mdx +++ b/website/docs/plugin/framework/migrating/resources/timeouts.mdx @@ -34,6 +34,15 @@ resource "timeouts_example" "example" { } ``` +Import the [timeouts module](https://github.com/hashicorp/terraform-plugin-framework-timeouts). + +```go +import ( + /* ... */ + "github.com/hashicorp/terraform-plugin-framework-timeouts/resource/timeouts" +) +```` + You can use this module to mutate the `schema.Schema` as follows: ```go diff --git a/website/docs/plugin/framework/resources/timeouts.mdx b/website/docs/plugin/framework/resources/timeouts.mdx index 56ea50a28..094f49894 100644 --- a/website/docs/plugin/framework/resources/timeouts.mdx +++ b/website/docs/plugin/framework/resources/timeouts.mdx @@ -36,6 +36,15 @@ resource "timeouts_example" "example" { } ``` +Import the [timeouts module](https://github.com/hashicorp/terraform-plugin-framework-timeouts). + +```go +import ( + /* ... */ + "github.com/hashicorp/terraform-plugin-framework-timeouts/resource/timeouts" +) +```` + You can use this module to mutate the `schema.Schema` as follows: ```go