Provider Framework Migration
Migrate Terraform provider resources and data sources from Plugin SDKv2 to the Plugin...
Install
npx skills add hashicorp/agent-skills --skill provider-framework-migration -g -a claude-code -y- Repository
- hashicorp/agent-skills911
- Category
- Testing
- Updated
- 7d ago
- License
- MPL-2.0
- Context cost
- Mediumabout 1,994 tokens
- Runs scripts
- No, instructions only
What it does
Migrate Terraform provider resources and data sources from Plugin SDKv2 to the Plugin Framework: muxing both plugins in one provider (terraform-plugin-mux, tf5to6server), per-resource migration workflow, SDKv2-to-Framework schema mapping (ForceNew, ValidateFunc, DiffSuppressFunc, Default, Timeouts, blocks), null-vs-zero-value behavioral traps, and state-compatibility verification. Use when converting or translating SDKv2 resources to the Framework, setting up a muxed provider server, deciding whether a resource should be migrated at all, or debugging plan diffs and state errors that appeared after a migration.
Migrating from Plugin SDKv2 to the Plugin Framework
The Plugin Framework is required for net-new resources and data sources; SDKv2 is maintenance-only. Migration is per-resource and incremental: a muxed provider serves SDKv2 and Framework implementations side by side, so you never need a big-bang rewrite. This skill covers the mux setup, the per-resource workflow, and the behavioral traps that turn a mechanical translation into a silent breaking change.
Reference (load when needed):
references/schema-mapping.md, the full SDKv2 → Framework translation table with code pairs
Official guide: Framework migration.
Decide Whether to Migrate at All
Migration has real risk and little user-visible payoff, so triage first:
- Do not migrate complex or heavily-used resources without a driving need (a Framework-only feature, a bug that SDKv2 cannot fix). The two SDKs differ behaviorally, most importantly around null versus zero values, and those differences surface as breaking changes for existing users. This is the standing policy in large providers like terraform-provider-aws.
- Simple resources migrate safely: flat schemas, no
DiffSuppressFunc, noCustomizeDiff, noStateFunc, no complex nested blocks. - New capabilities never require migrating old code, mux and write the new resource in the Framework alongside the old ones.
To tell what mode a provider is in, check go.mod: terraform-plugin-mux
present means it already serves both; only terraform-plugin-sdk/v2 means
SDKv2-only (mux setup is your first step); only
terraform-plugin-framework means the migration is done.
