Create Longer Form Documentation Page on SDK Migration Benefits

[bflad]

Module version

v0.14.0

Use-cases

While there is a bullet point list at https://www.terraform.io/plugin/which-sdk that quickly describes some of the benefits of migrating to this framework from terraform-plugin-sdk, provider developers are rightfully asking to see more information about these. Asking provider developers to potentially rewrite their code (or use the new framework going forward) should show the quality of life improvements that should help justify/solidify why these changes are beneficial to them and their time/effort.

Attempted Solutions

Asking provider developers to read the which-sdk page list or browse existing framework provider code.

Proposal

Create a new "benefits" page in the SDK migration guide and link to it from the top level which-sdk page. The contents of this page should walk through code examples of each item.

During HashiConf Global 2022, there was a partner workshop presentation that walked through these in detail, which I'll paraphrase here:

• "More concise abstractions, less magic"
• "The framework has been in design for years now with a broad range of developer experience feedback"
• More idiomatic Go programming
  • Interfaces over structs in more abstractions
  • Request and response pattern
  • context.Context everywhere
  • Type assertions are almost entirely removed
• Configuration, Plan, and State (available only when you can access them)
• Null, Unknown, and Known Values (support for Terraform's three value states)
• Custom Attribute Types (handle specific values easier)
• Map Attribute Types With Any Value Type
• Object Attribute Types
• Nested Attribute Types (block vs attribute syntax)
• Computed no longer special introduces implicit behaviors
• Configuration Validation Capabilities
  • Attribute validation on any type (lists, maps, etc.)
  • Attribute type validation (baked into the type)
  • Declarative schema-level validation
  • Imperative schema-level validation
• Path Expressions
• Import Warning Diagnostics
• Planned Resource Destroy Diagnostics (Terraform 1.3+)
• Resource private state management

Maybe these can be used as a starting point.