# Provider Framework Migration

Migrate Terraform provider resources and data sources from Plugin SDKv2 to the Plugin...

- Repository: https://github.com/hashicorp/agent-skills (911 stars)
- Category: Testing
- License: MPL-2.0
- Last updated: 2026-10-28
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add hashicorp/agent-skills --skill provider-framework-migration -g -a claude-code -y`
Codex: `npx skills add hashicorp/agent-skills --skill provider-framework-migration -g -a codex -y`
Cursor: `npx skills add hashicorp/agent-skills --skill provider-framework-migration -g -a cursor -y`
Gemini CLI: `npx skills add hashicorp/agent-skills --skill provider-framework-migration -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add hashicorp/agent-skills`

## Description

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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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](https://developer.hashicorp.com/terraform/plugin/framework/migrating).

## 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`,
  no `CustomizeDiff`, no `StateFunc`, 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.

## Step 1: Mux the Provider

The rest: https://github.com/hashicorp/agent-skills/blob/HEAD/plugins/terraform/skills/provider-framework-migration/SKILL.md