skills.rest
hashicorp
hashicorpOFFICIAL
Explore all skills by this author →
WebsiteGitHub

provider-framework-migration

Migrate Terraform provider resources from Plugin SDKv2 to the Plugin Framework.

859|125|Updated Nov 8, 2025
Search Tags:#terraform#GO#provider-development#plugin-framework#muxing#Migration#sdkv2
One-click install
npx skills add https://github.com/hashicorp/agent-skills --skill provider-framework-migration
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: provider-framework-migration
Source: https://github.com/hashicorp/agent-skills/tree/main/plugins/terraform/skills/provider-framework-migration
Command: npx skills add https://github.com/hashicorp/agent-skills --skill provider-framework-migration

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Migrating Terraform provider resources from Plugin SDKv2 to the Plugin Framework is risky: behavioral differences around null versus zero values, block versus attribute syntax, and state compatibility can silently break existing users. This Skill provides a structured, per-resource migration workflow that avoids big-bang rewrites and prevents breaking changes.

Core Features & Use Cases

  • Muxed Provider Setup: Combine SDKv2 and Framework plugin servers in one provider using terraform-plugin-mux (tf5to6server, tf6muxserver) so resources migrate incrementally.
  • Schema Translation Reference: A complete SDKv2-to-Framework mapping table covering ForceNew, ValidateFunc, DiffSuppressFunc, Default, Timeouts, and nested blocks.
  • State-Compatibility Verification: Baseline acceptance tests, ImportStateVerify checks, and empty-plan upgrade tests that prove the migrated resource is indistinguishable to users.
  • Use Case: You maintain a Terraform provider still on SDKv2 and need to port a simple resource to the Framework. Follow the five-step workflow to mux the provider, port the resource, move its registration, and verify an empty plan against pre-migration state.

Quick Start

Use the provider-framework-migration skill to migrate my SDKv2 resource to the Plugin Framework and set up a muxed provider server.

Frequently Asked Questions about provider-framework-migration

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I migrate a Terraform provider from SDKv2 to the Plugin Framework?▼

Migrate per-resource, not all at once. First mux both plugin servers with terraform-plugin-mux, then port each resource's schema and CRUD using the SDKv2-to-Framework mapping table, move its registration, and verify existing acceptance tests pass unchanged.

How do I run SDKv2 and Plugin Framework resources in the same provider?▼

Use terraform-plugin-mux to serve both plugins side by side. Upgrade the SDKv2 server with tf5to6server, combine it with the Framework server via tf6muxserver, and ensure provider-level schemas match exactly while each resource exists in only one plugin.

Which Terraform resources should not be migrated to the Plugin Framework?▼

Avoid migrating complex or heavily-used resources without a driving need, especially those using DiffSuppressFunc, CustomizeDiff, StateFunc, or complex nested blocks. SDKv2 and the Framework differ behaviorally around null versus zero values, which can surface as breaking changes.

Why do plan diffs appear after migrating a resource to the Plugin Framework?▼

SDKv2 collapses unset values into Go zero values while the Framework distinguishes null, unknown, and zero. If the ported code sends the API different values than SDKv2 did, existing configurations change behavior. Audit every GetOk and zero-value comparison, and verify with ImportStateVerify and empty-plan upgrade tests.

Does migrating to the Plugin Framework require a state upgrade?▼

Not if every attribute keeps its exact name and type, since the Framework reads the state SDKv2 wrote. A StateUpgrader is only needed when the new types normalize stored values differently, which is a signal the resource may belong in the do-not-migrate bucket.

Related Skills

Explore More Software Engineering Skills→
hashicorphashicorp
790

provider-resources

Automate Terraform provider resource and data source development with the Plugin Framework.

Official
Advanced
kk0gakk0ga

provider-test-patterns

Standardize Terraform provider acceptance tests with Plugin Framework and terraform-plugin-testing.

Community
Advanced
L3DigitalNetL3DigitalNet
6

Test Plugin Skill

Generate and execute tests for Claude Code plugins and MCP tools.

Official
Intermediate
optionioptioni

openspec-bulk-archive-change

Batch archive completed codebase changes with openspec CLI conflict resolution.

Official
Intermediate