Adding docs for migrating from SDKv2 to the Framework

website/data/plugin-framework-nav-data.json

@@ -79,5 +79,96 @@
   {
     "title": "Debugging",
     "path": "debugging"
+  },
+  {
+    "title": "Migrating from SDK",
+    "routes": [
+      {
+        "title": "Overview",
+        "path": "migrating"
+      },
+      {
+        "title": "Testing",
+        "path": "migrating/testing"
+      },
+      {
+        "title": "Schema",
+        "path": "migrating/schema"
+      },
+      {
+        "title": "Provider",
+        "path": "migrating/provider"
+      },
+      {
+        "title": "Resources",
+        "routes": [
+          {
+            "title": "Schema",
+            "path": "migrating/resources/schema"
+          },
+          {
+            "title": "CRUD Functions",
+            "path": "migrating/resources/crud"
+          },
+          {
+            "title": "Import",
+            "path": "migrating/resources/import"
+          },
+          {
+            "title": "Plan Modification",
+            "path": "migrating/resources/plan-modification"
+          },
+          {
+            "title": "State Upgraders",
+            "path": "migrating/resources/state-upgrade"
+          }
+        ]
+      },
+      {
+        "title": "Data Sources",
+        "path": "migrating/data-sources"
+      },
+      {
+        "title": "Attributes & Blocks",
+        "routes": [
+          {
+            "title": "Attribute Schema",
+            "path": "migrating/attributes-blocks/attribute-schema"
+          },
+          {
+            "title": "Attribute Types",
+            "path": "migrating/attributes-blocks/types"
+          },
+          {
+            "title": "Attribute Fields",
+            "path": "migrating/attributes-blocks/fields"
+          },
+          {
+            "title": "Default Values",
+            "path": "migrating/attributes-blocks/default-values"
+          },
+          {
+            "title": "Force New",
+            "path": "migrating/attributes-blocks/force-new"
+          },
+          {
+            "title": "Validators - Predefined",
+            "path": "migrating/attributes-blocks/validators-predefined"
+          },
+          {
+            "title": "Validators - Custom",
+            "path": "migrating/attributes-blocks/validators-custom"
+          },
+          {
+            "title": "Blocks",
+            "path": "migrating/attributes-blocks/blocks"
+          },
+          {
+            "title": "Blocks with Computed Fields",
+            "path": "migrating/attributes-blocks/blocks-computed"
+          }
+        ]
+      }
+    ]
   }
 ]

website/docs/plugin/framework/migrating/attributes-blocks/attribute-schema.mdx

@@ -0,0 +1,126 @@
+---
+page_title: 'Attribute Schema: Migrating from SDKv2 to the Framework'
+description: >-
+  Migrate attributes from SDKv2 to the plugin Framework
+---
+
+# Attribute Schema
+
+Attributes define how users can configure values for your Terraform provider, resources, and data sources. Refer to
+[Schemas - Attributes](/plugin/framework/schemas#attributes) in the Framework documentation for details.
+
+This page explains how to migrate an attribute from SDKv2 to the plugin Framework.
+
+## SDKv2
+In SDKv2, attributes are defined by the `Schema` field in the provider, resource, or data source schema. The `Schema`
+field maps each attribute name (string) to the attribute's `schema.Schema` struct. Both resources and data sources are
+defined using the `schema.Resource` struct.
+
+The following code shows a basic implementation of attribute schema for a provider in SDKv2.
+
+```go
+func ProviderExample() *schema.Provider {
+    return &schema.Provider{
+        Schema: map[string]*schema.Schema{
+            /* ... */
+},
+```
+
+In SDKv2, resource and data source attributes are defined the same way on their respective types.
+
+```go
+func resourceExample() *schema.Resource {
+    return &schema.Resource{
+        Schema: map[string]*schema.Schema{
+            /* ... */
+```
+## Framework
+
+In the Framework, you define attributes by setting the `Attributes` field on your provider, resource, or data type's
+schema, as returned by the `GetSchema` function. The `tfsdk.Schema` type returned by `GetSchema` includes an
+`Attributes` field that maps each attribute name (string) to the attribute's `tfsdk.Attribute` struct.
+
+The following code shows how to define an attribute for a resource with the Framework.
+
+```go
+func (d *resourceTypeExample) GetSchema(context.Context) (tfsdk.Schema, diag.Diagnostics) {
+    return tfsdk.Schema{
+        Attributes: map[string]tfsdk.Attribute{
+            "example": {
+                /* ... */
+```
+
+The Framework defines the `tfsdk.Attribute` struct as follows.
+
+```go
+type Attribute struct {
+    Type                attr.Type
+    Attributes          NestedAttributes
+    Description         string
+    MarkdownDescription string
+    Required            bool
+    Optional            bool
+    Computed            bool
+    Sensitive           bool
+    DeprecationMessage  string
+    Validators          []AttributeValidator
+    PlanModifiers       AttributePlanModifiers
+}
+```
+## Migration Notes
+Remember the following differences between SDKv2 and the Framework when completing the migration.
+
+- In SDKv2, attributes are defined by a map from attribute names to `schema.Schema` structs in the `Schema` field of
+your resource's schema. In the Framework, attributes are defined by a map from attribute names to `tfsdk.Attribute`
+structs in your resource's schema, which is returned by the `GetSchema` function.
+- There are several differences between the implementation of attributes in SDKv2 and the Framework. Refer to the other
+pages in the Attributes & Blocks section of this migration guide for more details.
+
+## Example
+
+The following examples show how to migrate portions of the
+[http](https://github.com/hashicorp/terraform-provider-http) provider.
+
+For a complete example, clone the
+`terraform-provider-http` repository and compare the `data_source.go` file in
+[v2.2.0](https://github.com/hashicorp/terraform-provider-http/blob/v2.2.0/internal/provider/data_source.go)
+and the `data_source_http.go` file in
+[v3.0.1](https://github.com/hashicorp/terraform-provider-http/blob/v3.0.1/internal/provider/data_source_http.go).
+
+
+### SDKv2
+
+The following example from the `data_source.go` file shows the implementation of the `url` attribute for the `http`
+data source.
+
+```go
+func dataSource() *schema.Resource {
+    return &schema.Resource{
+        /* ... */
+        Schema: map[string]*schema.Schema{
+            "url": {
+                Description: "The URL for the request. Supported schemes are `http` and `https`.",
+                Type:        schema.TypeString,
+                Required:    true,
+            },
+```
+
+
+### Framework
+
+The following shows the same section of provider code after the migration.
+
+This code implements the `url` attribute for the `http` data source with the Framework.
+
+```go
+func (d *httpDataSourceType) GetSchema(context.Context) (tfsdk.Schema, diag.Diagnostics) {
+    return tfsdk.Schema{
+        ...
+        Attributes: map[string]tfsdk.Attribute{
+            "url": {
+                Description: "The URL for the request. Supported schemes are `http` and `https`.",
+                Type:        types.StringType,
+                Required:    true,
+            },
+        ...
+```

website/docs/plugin/framework/migrating/attributes-blocks/blocks-computed.mdx

@@ -0,0 +1,107 @@
+---
+page_title: 'Computed Blocks: Migrating from SDKv2 to the Framework'
+description: >-
+  Migrate computed blocks from SDKv2 to attribute validators in the plugin Framework.
+---
+
+# Computed Blocks
+
+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). Refer to [Schemas - Blocks](/plugin/framework/FIXME) in the
+Framework documentation for details.
+
+This page explains how to migrate computed blocks from SDKv2 to the Framework. Refer to
+[Blocks](/plugin/framework/migrating/attributes-blocks/blocks) if you are looking for information about migrating blocks
+that do not contain computed fields.
+
+## SDKv2
+
+In SDKv2, blocks are defined by an attribute whose type is `TypeList`, or `TypeSet` and whose `Elem` field is set to a
+`schema.Resource` that contains a map of the block's attribute names to corresponding `schemaSchema` structs.
+
+```go
+map[string]*schema.Schema{
+    "example": {
+        Type:     schema.TypeList,
+        Computed: true,
+        Elem: &schema.Resource{
+            Schema: map[string]*schema.Schema{
+                "nested_example": {
+                        Type:        schema.TypeString,
+                        Computed:    true,
+                        ...
+```
+
+## Framework
+
+In the Framework, when working with protocol version 5, computed blocks are implemented using an attribute with a `Type`
+of `types.ListType` which has an `ElemType` of `types.ObjectType`.
+
+When working with protocol version 6, we recommend that you define computed blocks using nested attributes.
+
+```go
+map[string]tfsdk.Attribute{
+"example": {
+    Computed: true,
+        Type: types.ListType{
+            ElemType: types.ObjectType{
+                AttrTypes: map[string]attr.Type{
+                    "nested_example":  types.StringType,
+                    ...
+
+```
+## Migration Notes
+
+- When using protocol version 5 specify `ElemType` as `types.ObjectType` when migrating blocks that are computed from SDKv2 to Framework.
+- When using protocol version 6, use [nested attributes](https://www.terraform.io/plugin/framework/schemas#attributes-1) when migrating blocks that are computed from SDKv2 to Framework.
+
+## Example
+
+The following examples show how to migrate portions of the [tls](https://github.com/hashicorp/terraform-provider-tls)
+provider.
+
+For a complete example, clone the
+`terraform-provider-tls` repository and compare the `data_source_certificate.go` file in
+[v3.4.0](https://github.com/hashicorp/terraform-provider-tls/blob/v3.4.0/internal/provider/data_source_certificate.go)
+with
+[v4.0.1](https://github.com/hashicorp/terraform-provider-tls/blob/v4.0.1/internal/provider/data_source_certificate.go).
+
+### SDKv2
+
+The following example from the `data_source_certificate.go` file shows the implementation of the `certificates` nested
+block on the `certificate` data source's schema.
+
+```go
+Schema: map[string]*schema.Schema{
+"certificates": {
+        Type:     schema.TypeList,
+        Computed: true,
+        Elem: &schema.Resource{
+            Schema: map[string]*schema.Schema{
+                "signature_algorithm": {
+                    Type:        schema.TypeString,
+                    Computed:    true,
+                    ...
+                },
+```
+
+### Framework
+
+The following shows the same section of provider code after the migration.
+
+This code defines the `certificates` block as an attribute on the `certificate` data source's schema, where the
+`types.ObjectType` is being used to define the nested block.
+
+```go
+map[string]tfsdk.Attribute{
+    "certificates": {
+        Type: types.ListType{
+            ElemType: types.ObjectType{
+                AttrTypes: map[string]attr.Type{
+                    "signature_algorithm":  types.StringType,
+            },
+        },
+        Computed:            true,
+        ...
+```