tf-resource-migration

Migrate existing SDK-based resources to Plugin Framework while maintaining state compatibility and behavior parity.

Tooling Rule (read first)

Always drive generation, formatting, and linting through Task:

• task generate — generates code and runs task fmt automatically at the end
• task fmt — formats Go, Terraform, and whitespace
• task lint — runs all linters

Do NOT use go run ./generators/..., go generate, gofmt, goimports, golangci-lint, or make for these workflows. See AGENTS.md and Taskfile.dist.yml (run task --list) for the full command surface.

Overview

This skill guides migration of resources from:

• Source: internal/sdkprovider/ (terraform-plugin-sdk/v2)
• Target: internal/plugin/ (terraform-plugin-framework) with YAML-generated code

Key Challenge: Preserve exact behavior and state compatibility so users don't experience breaking changes.

Prerequisites: This skill builds on tf-resource-generator. For YAML syntax, adapter API, modifier patterns, custom view overrides, write-only fields, and all implementation details, see that skill.

When to Use This Skill

Use this skill when:

• Migrating existing aiven_* resources from SDK to Plugin Framework
• User says: "migrate", "convert", "port", "move to Plugin Framework"

Use tf-resource-generator skill when:

• Creating brand new resources from scratch
• Questions about YAML syntax, adapter API, or implementation patterns

Migration Workflow

1. Analyze the Existing SDK Resource

Find the SDK resource:

# Find resource file
find internal/sdkprovider -name "*resource_*.go" | grep -i "resource_name"

# Find data source file
find internal/sdkprovider -name "*datasource_*.go" | grep -i "resource_name"

Read and document:

• Schema definition (all fields, types, attributes)
• CRUD functions (Create, Read, Update, Delete)
• Custom logic and transformations
• State upgrade functions (if any)
• Existing tests (critical for parity)

2. Identify API Operations

Check what API operations the SDK resource uses:

# Search for API client calls in the resource
grep -A 5 "client\." internal/sdkprovider/service/resource_name.go

# IMPORTANT: Also check the data source — it may use a different API operation
grep -A 5 "client\." internal/sdkprovider/service/resource_name_data_source.go

Then find corresponding OpenAPI operation IDs. See tf-resource-generator for OpenAPI search patterns.

Determine clientHandler: The clientHandler YAML value is the Go package name under github.com/aiven/go-client-codegen/handler/. Find it by searching for the operation ID in the module cache:

grep -r "OperationID" $(go env GOMODCACHE)/github.com/aiven/go-client-codegen*/handler/

For example, ServiceFlinkCreateApplication lives in handler/flinkapplication/, so clientHandler: flinkapplication.

3. Map SDK Schema to YAML

SDK Type -> YAML Type

| SDK Type | YAML Type | |----------|-----------| | schema.TypeString | type: string | | schema.TypeInt | type: integer | | schema.TypeFloat | type: number | | schema.TypeBool | type: boolean | | schema.TypeList | type: arrayOrdered | | schema.TypeSet | type: array (or arrayOrdered for performance) | | schema.TypeMap | additionalProperties: {type: string} |

SDK Attributes -> YAML Attributes

| SDK Attribute | YAML Attribute | |---------------|----------------| | Required: true | required: true | | Optional: true | optional: true | | Computed: true | computed: true | | Sensitive: true | sensitive: true | | ForceNew: true | forceNew: true | | ConflictsWith: [] | conflictsWith: [] | | ExactlyOneOf: [] | exactlyOneOf: [] |

Nested Blocks

SDK Set of objects:

"tags": {
    Type:     schema.TypeSet,
    Elem: &schema.Resource{
        Schema: map[string]*schema.Schema{
            "key":   {Type: schema.TypeString},
            "value": {Type: schema.TypeString},
        },
    },
}

YAML (use arrayOrdered for performance):

schema:
  tags:
    type: arrayOrdered
    items:
      type: object
      properties:
        key:
          type: string
        value:
          type: string

Read-Only Nested Collections

Do not reshape a field to fix a diff. A list stays a list and a set stays a set, which is what keeps an existing state readable.

Nested collections are the one exception, and the generator decides it: a collection that is read-only all the way down becomes a computed nested attribute, everything else a block. No YAML key asks for this — Item.RendersAsAttribute derives it.

The Plugin Framework has no computed blocks: Terraform plans a block from the configuration, so a value stored for a block the configuration doesn't declare either shows up as a permanent diff or fails the apply with an inconsistent result. An attribute can be computed, and a read-only collection gives up nothing by losing the block body — it has no field to write in it. The two are interchangeable for readers: same list(object({...})) in the state, same expressions (app.application_versions[0].id), so no state upgrade is involved.

An object stays a one-element collection in both forms, as the SDKv2 state holds it. That is due for removal in v5.0.0, when current_deployment.0.status becomes current_deployment.status. Never anticipate it in a migration: it breaks every reader.

Caveat — this holds only when nothing inside is settable. An optional: true + computed: true collection such as the kafka topic config stays a block, because real configurations write it in block syntax. Marking one nested field optional: true is enough to turn the whole collection back into a block. Data sources keep blocks too: their result is not planned against a configuration, so a block holding API values causes no diff there.

For an optional+computed block, drop the values the user did not set instead — see flattenConfig in internal/plugin/service/kafka/topic/topic.go. Flatten writes back only the keys the response carries, so delete(dto, name) leaves whatever prior state holds; d.Set(name, nil) removes it.

Generated example: application_versions in internal/plugin/service/flink/jarapplication/zz_resource.go.

4. Preserve ID Structure

CRITICAL: The ID format MUST stay the same for state compatibility.

Find the ID format in SDK code:

# Look for ResourceData.SetId calls
grep -A 2 "SetId" internal/sdkprovider/service/resource_name.go

# Look for ID builder functions
grep -B 5 "buildResourceID\|parseResourceID" internal/sdkprovider/service/resource_name.go

Common ID patterns:

• Single field: project
• Composite: project/service_name/database_name

Set in YAML:

idAttributeComposed: [project, service_name, database_name]

5. Handle Custom Logic

Identify in SDK code and map to generator features:

| SDK Pattern | Generator Feature | |-------------|------------------| | StateUpgraders | May need version in YAML + state upgrader | | CustomizeDiff | modifyPlan: true (writes plan values, d.RequiresReplace for replacement) — not planModifier, which runs inside Read | | Flatten/Expand functions | expandModifier: true / flattenModifier: true | | DiffSuppressFunc | No equivalent, see Diff Suppression Has No Equivalent | | Post-Create/Update waiter (poll Read until the resource converges) | refreshStateExists, or stateAttribute with refreshStateDesired/refreshStateFailed, or ResourceOptions.RefreshStateCheck when the value is nested (see tf-resource-generator) | | Multiple API calls in Update | Custom updateView via init() override | | Delete waiter (poll until gone/terminal state; conflicts clear as Delete is re-issued) | deleteStateDesired (see tf-resource-generator); avoid a custom deleteView | | Complex delete (cancel + delete state machine) | Custom deleteView via init() override | | Data source looks up by alt key (e.g. name) | A second read op with datasourceLookup: true + resultListLookupKeys; add resultIDField: <GoField> when the lookup endpoint differs in shape from the canonical read and should only resolve the id | | Sensitive field not stored in state | writeOnly: true |

For implementation details of each, see tf-resource-generator skill.

Diff Suppression Has No Equivalent

DiffSuppressFunc cannot be ported. Terraform rejects a plan whose value for a configured attribute differs from the configuration, which is why the Plugin Framework offers no such hook: SDKv2 only got away with it through its legacy type-system shims. Decide what the suppression was buying:

• It hid a change that needs no API call (e.g. a local file path the API never sees). Set forceNew: false on the attribute and let the change apply in place. No update view is needed: the adapter skips a nil Update and refreshes the state, so the new value is simply stored.
• It hid a formatting difference the API normalizes (casing, trailing slash). Normalize the same way in modifyPlan — but only for computed attributes, since a configured one must keep the configured value.
• It paired with a computed attribute that drove replacement (CustomizeDiff + SetNew on a ForceNew computed field). Compute the value in modifyPlan and call d.RequiresReplace on it.

Whichever applies, the behavior changes for at least some configurations, so call it out in CHANGELOG.md. internal/plugin/service/flink/jarversion migrated a resource that used both a DiffSuppressFunc and CustomizeDiff.

6. Create YAML Definition

Create definitions/aiven_resource_name.yml. For complete YAML syntax reference, see tf-resource-generator skill.

IMPORTANT: Definition files MUST have the aiven_ prefix. The filename becomes the resource name directly.

Focus on migration-specific concerns:

• Match all SDK schema fields exactly
• Preserve ID structure
• Copy descriptions from SDK resource
• Keep every SDK Sensitive field as sensitive: true in YAML (no regressions)

7. Generate and Build

task generate
task build
task lint

8. State Compatibility Verification

CRITICAL: Ensure state is compatible between SDK and Plugin Framework versions.

Check schema version in SDK:

grep -A 3 "SchemaVersion" internal/sdkprovider/service/resource_name.go

If SDK has SchemaVersion > 0, you MUST handle state upgrades.

9. Backward Compatibility Testing

CRITICAL: Test that existing state from SDK version works with Plugin Framework version.

Use acc.BackwardCompatibilitySteps() helper:

func TestAccAivenResource_backwardCompat(t *testing.T) {
    resourceName := "aiven_resource_name.test"
    projectName := acc.ProjectName()

    resource.ParallelTest(t, resource.TestCase{
        PreCheck: func() { acc.TestAccPreCheck(t) },
        Steps: acc.BackwardCompatibilitySteps(t, acc.BackwardCompatConfig{
            TFConfig:           testAccResourceConfig(projectName),
            OldProviderVersion: "4.47.0", // Check CHANGELOG.md for latest
            Checks: resource.ComposeTestCheckFunc(
                resource.TestCheckResourceAttr(resourceName, "project", projectName),
                // Add all key attribute checks
            ),
        }),
    })
}

Find the latest version:

head -20 CHANGELOG.md

What this test does:

1. Creates resource with OLD SDK provider version
2. Applies with NEW Plugin Framework version
3. Verifies state is compatible and attributes match

Examples:

• internal/plugin/service/mysql/database/database_test.go - Basic backward compatibility
• internal/plugin/service/pg/user/user_test.go - Complex resource with custom update logic

10. Parity Testing

CRITICAL: Verify behavior matches SDK resource exactly.

Find SDK tests:

ls internal/sdkprovider/service/*resource_name*_test.go

Ensure Plugin Framework tests cover:

• All CRUD operations from SDK tests
• Update step: If the resource implements Update (mutable fields that are not all ForceNew), acceptance tests MUST include a Terraform apply that changes at least one updatable attribute after create — i.e. an explicit update step in the test sequence, not only create + destroy. Skip this only when the resource is create/delete-only or every mutable change forces replacement.
• Edge cases
• Error handling
• Import functionality
• Special field behaviors

State Compatibility Checklist

Before marking migration complete:

• [ ] Resource ID format is identical
• [ ] All schema fields are present (no removals)
• [ ] Field types match exactly, and no optional field turned from a block into an attribute
• [ ] Computed fields work the same way
• [ ] Default values match
• [ ] Required/Optional flags match
• [ ] All SDK-sensitive fields remain sensitive: true in YAML
• [ ] ForceNew behavior matches
• [ ] Import works with existing IDs
• [ ] Existing state can be used without migration
• [ ] Backward compatibility test added using acc.BackwardCompatibilitySteps()
• [ ] All SDK test scenarios pass with Plugin version
• [ ] When the resource supports Update, acceptance tests include an update step (apply with changed config after create)
• [ ] Changelog entry added to CHANGELOG.md

Common Migration Issues

| Issue | Solution | |-------|----------| | Sensitive field no longer marked sensitive | Set sensitive: true on the attribute (and nested fields if applicable); match SDK Sensitive: true exactly | | ID format changed accidentally | Verify idAttributeComposed matches SDK's ID builder | | Set ordering causes diffs | Use arrayOrdered instead of array | | Read-only list of objects diffs on every plan | It must render as a computed attribute; check nothing inside it is optional (see Read-Only Nested Collections) | | Computed field becomes required | Keep as computed: true if API provides it | | Custom validation lost | Implement in custom modifier or use schema validation | | State upgrade needed | Implement state upgrader in Plugin Framework | | DiffSuppressFunc behavior | Not portable — see Diff Suppression Has No Equivalent | | Field the API accepts but never returns | Fill it in a readView override only when the state has no value, so imports don't keep a null and existing state stays untouched | | OpenAPI default would plan a change against SDKv2 state | Workaround: dropDefault: true plus useStateForUnknown: true, and send the API default from the create view. Goes away in v5.0.0 with SDKv2 state support | | Computed value must force replacement | Compute it in modifyPlan and call d.RequiresReplace(name); schema forceNew runs too early to see it | | Post-create waiter polls a nested attribute | refreshStateExists: true plus ResourceOptions.RefreshStateCheck; stateAttribute only accepts top-level attributes | | Renamed ID field missing in old state | Use planModifier: true to extract from composite ID | | Read fails with 404 after migration | Likely a renamed ID field is empty — use planModifier | | "was null, but now cty.X" error | Add computed: true + useStateForUnknown: true (see generator skill) | | Field nested differently in API | Use expandModifier and flattenModifier (see generator skill) | | Multiple update operations needed | Override updateView via init() (see generator skill) | | Data source lookup key differs | Add a second read operation with datasourceLookup: true + resultListLookupKeys. If the lookup endpoint returns a different shape than the canonical read (e.g. a directory of ids), also set resultIDField: <GoField> (see generator skill) |

Migration-Specific Commands

# Find SDK resource
find internal/sdkprovider -name "*resource_*.go" | grep -i "name"

# Analyze SDK schema
grep -A 20 "Schema:" internal/sdkprovider/service/resource.go

# Find SDK ID format
grep -A 2 "SetId" internal/sdkprovider/service/resource.go

# Compare implementations
diff internal/sdkprovider/service/resource.go internal/plugin/service/resource/zz_resource.go

# Run backward compatibility test
task test-acc -- -run TestAccAivenResource_backwardCompat

After Migration

Once all tests pass and state compatibility is verified:

1. Remove SDK resource - Delete from internal/sdkprovider/ and remove provider registration
2. Update documentation - Ensure docs reflect the Plugin Framework version
3. Add migration notes if needed - Document any unavoidable behavioral differences
4. Add changelog entry - Add record to CHANGELOG.md under the unreleased section:

   - Migrate `aiven_resource_name` to the Plugin Framework
   - Change `aiven_resource_name`: deprecate `termination_protection` field. Instead, use [prevent_destroy](https://developer.hashicorp.com/terraform/tutorials/state/resource-lifecycle#prevent-resource-deletion)
   

Do not maintain both versions - this creates maintenance burden and user confusion.

Key Principles

1. State compatibility first - Users should not need to recreate resources
2. Preserve exact behavior - Match SDK resource behavior precisely
3. Preserve sensitivity - All fields that were Sensitive in SDK must stay sensitive in Plugin Framework (sensitive: true); never expose secrets in plan or state output by omission
4. Test thoroughly - All SDK test scenarios must pass with Plugin version; when Update exists, tests must exercise it via an update apply step
5. Remove SDK version - Once verified, delete SDK resource to avoid maintenance burden