Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation for mapping between SDKv2 and the Framework #660

Merged
merged 8 commits into from
Feb 10, 2023
Merged

Documentation for mapping between SDKv2 and the Framework #660

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
4bef283
Adding table to provide mapping between SDKv2 schema validators and f…
bendbennett Feb 8, 2023
3e5fa7f
Adding a table to provide mapping between SDK schema fields and Frame…
bendbennett Feb 9, 2023
6601435
Merge branch 'main' into bendbennett/issues-659
bendbennett Feb 9, 2023
d9714e1
Apply suggestions from code review
bendbennett Feb 10, 2023
5ed3c6b
Adding a table to provide mapping between SDK schema fields and Frame…
bendbennett Feb 10, 2023
f248110
Add import statements for usage of timeouts module (#659)
bendbennett Feb 10, 2023
b461ff8
Apply suggestions from code review
bendbennett Feb 10, 2023
bdf7ac9
Merge branch 'main' into bendbennett/issues-659
bendbennett Feb 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions website/docs/plugin/framework/migrating/attributes-blocks/blocks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,17 @@ 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.

Refer to [Attribute Fields](/plugin/framework/migrating/attributes-blocks/fields) for details regarding the relationship
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since there are a variety of differences between blocks and attributes, I think this page might warrant its own table. The prior SDK allowed developers to do unsupported things, like declare Sensitive on blocks (hashicorp/terraform-plugin-sdk#819) and we already have special callouts in paragraph form about Computed and Required. Therefore I think we should walk through the various fields and how they relate to blocks:

SDK Schema Field Framework
Computed Link to computed block page
Optional N/A - no implementation required
Required listvalidator.IsRequired() and setvalidator.IsRequired() (let's omit any discussion on single nested blocks, they weren't possible to declare before)
Sensitive N/A - only supported on attributes

etc. 😄

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Have added a table into the Blocks page.

between [SDK Schema Fields](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk/helper/schema#Schema) and
the Framework.

~> **Important:** `ListNestedBlock`, `SetNestedBlock` and `SingleNestedBlock` within the Framework do not have a field
for `Required` at the level of the block. However, the behaviour of `Required` can be replicated by using
[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) and
[objectvalidator.IsRequired](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/objectvalidator#IsRequired),
respectively.

## Nested Block Example

The following example shows a nested block in Terraform resource configuration. The `subject` nested
Expand Down
32 changes: 32 additions & 0 deletions website/docs/plugin/framework/migrating/attributes-blocks/fields.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 | [PlanModifiers](/framework/migrating/resources/plan-modification#framework) field on attribute or implementation of [ResourceWithModifyPlan](/plugin/framework/migrating/resources/plan-modification#framework) interface |
| 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) |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it might be good to call out that any schema.Resource in Elem should refer to the blocks documentation instead. 👍

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated to include call out.

| 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 is required | |
| ComputedWhen | [PlanModifiers](/framework/migrating/resources/plan-modification#framework) field on attribute or implementation of [ResourceWithModifyPlan](/plugin/framework/migrating/resources/plan-modification#framework) interface |
| 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.

Expand Down
14 changes: 14 additions & 0 deletions ...ite/docs/plugin/framework/migrating/attributes-blocks/validators-predefined.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down