RFC: Progressive migration to Plugin Framework to re-enable `moved` block support (fixes #2812)

[gaetanars]

Summary

This is a proposal to progressively migrate provider resources from SDKv2 to the Terraform Plugin Framework, resource by resource, submitted as individual PRs. The primary motivation is re-enabling moved block support broken since v3.0.0 (see #2812), and aligning with HashiCorp's standard migration path.

I've completed a pilot implementation for kubernetes_namespace_v1 to establish the patterns before starting the bulk migration. I'd like feedback from the maintainers before proceeding.

Problem

Since v3.0.0, moved blocks between cross-type resources (e.g. kubernetes_namespace → kubernetes_namespace_v1) raise:

Error: Move Resource State Not Supported
The "kubernetes_namespace_v1" resource type does not support moving resource
state across resource types.

Root cause: SDKv2 does not implement ResourceWithMoveState. This interface is only available in the Plugin Framework.

Proposed Strategy

One PR per resource, submitted in API group order:

1. Phase 0 (pilot): kubernetes_namespace_v1 ← establishes patterns for all subsequent migrations
2. Phase 1: remaining core/v1 resources
3. Phase 2: apps/v1
4. Phase 3: batch/v1, networking, RBAC
5. Phases 4–6: storage, admission, miscellaneous + data sources
6. Phase 7: cleanup (remove mux once all resources migrated)

Each PR:

• Implements ResourceWithMoveState (for moved {} blocks, Terraform ≥ 1.8)
• Implements ResourceWithUpgradeState (for terraform state mv / pre-1.8 workflows)
• Removes the resource from SDKv2 ResourcesMap in the same commit (mux constraint: a type cannot be registered in both providers simultaneously)
• Maintains strict functional parity with the SDKv2 implementation

Key Technical Patterns (established in pilot)

MoveState

• SourceTypeName == "kubernetes_namespace" routes the deprecated alias to kubernetes_namespace_v1
• req.SourceRawState.JSON used directly (no SourceSchema declared)

UpgradeState (v0 → v1)

• SDKv2 serializes schema.TypeList metadata as [{...}] → PriorSchema must use schema.ListNestedAttribute
• timeouts must be present in PriorSchema (users with custom timeout blocks have it in state)
• Handler uses req.State.Get(ctx, &prior) since PriorSchema is provided
• Schema.Version = 1 on the Framework resource to trigger the upgrade path
• Null normalization: annotations: {} → nil, generate_name: "" → types.StringNull()

KubeClientsets interface extension

• Added GetIgnoreAnnotations() []string and GetIgnoreLabels() []string to the exported interface (needed since providerMetadata is unexported)

JSON Patch for Update

• patchMetadata() takes *schema.ResourceData and cannot be reused → DiffStringMap (exported from patch_operations.go) used directly

Acceptance criteria per PR

• ResourceWithMoveState + ResourceWithUpgradeState both implemented
• Unit test with real SDKv2 state JSON fixture exercising the upgrade path
• Acceptance test: provision with v3.0.1 → plan with local provider → plancheck.ExpectEmptyPlan()
• Acceptance test: moved {} block → plancheck.ExpectEmptyPlan()
• ImportStateVerify: true passes
• make build, make test, make fmtcheck, make go-lint pass
• Changelog entry

Questions for maintainers

1. PR granularity: 1 PR per resource is my default; would you prefer a different boundary (e.g. 1 PR per API group)?
2. kubernetes_namespace removal: The deprecated alias is removed from ResourcesMap in the same PR as the _v1 migration. Is that the right approach, or should the deprecated type remain accessible via some backward-compat path?
3. Schema parity: Should these PRs strictly maintain SDKv2 parity, or is there appetite for minor schema improvements (e.g. adding validators) in the same PR?
4. Testing requirements: Are acceptance tests against a real cluster required in CI for these PRs, or is the unit test + existing SDKv2 acceptance test coverage sufficient initially?

Happy to adjust the approach based on your feedback before submitting the pilot PR.

/cc @hashicorp/terraform-provider-kubernetes-maintainers

[bjornmage]

Endorsing this RFC.

On the two open questions:

1. PR granularity — one-PR-per-resource is the right default for a migration of this size and risk profile. It keeps each review bounded, lets acceptance-test failures localize to a single resource, and each PR's moved/UpgradeState path is self-contained. Grouping by API group would make individual PRs too large to review and would couple unrelated acceptance-test surfaces. The only exception I'd consider is grouping very small resources (e.g. kubernetes_limit_range_v1 + kubernetes_resource_quota_v1) when they share a single module consumer pattern and the diff is < ~500 LOC combined. Default to per-resource, relax to per-group only if individual PRs turn out to be trivial.

2. Deprecated alias removal in the same commit — yes, this is correct and the only mux-safe way to do it. A downstream consumer observation: because kubernetes_secret/kubernetes_namespace/etc. and their _v1 counterparts are currently served by the same SDKv2 factory function with only the deprecation-message argument differing (kubernetes/provider.go lines 255–350 — e.g. resourceKubernetesSecretV1("Deprecated; use kubernetes_secret_v1.") vs resourceKubernetesSecretV1("")), the MoveState implementation for most of core/v1 should be an identity copy of the state JSON: SourceRawState.JSON → resp.TargetState with no schema translation beyond the ListNestedAttribute → SingleNestedAttribute metadata shape change you already solved for namespace_v1. That's a generic helper waiting to happen — corev1.moveStateJSONPassthroughWithMetadataConversion(...) — applicable to most core/v1 resources as a near-drop-in.

Production context from our stack is in the sibling thread at #2812. No local fork — waiting for this to land cleanly. I've offered to contribute the kubernetes_secret_v1 migration in PR #2858's thread as a stacked follow-up.