aiven/tf-resource-migration

Terraform Resource Migration Skill

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

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 | planModifier: true or ModifyPlan | | Flatten/Expand functions | expandModifier: true / flattenModifier: true | | DiffSuppressFunc | planModifier: true | | Multiple API calls in Update | Custom updateView via init() override | | Complex delete (cancel + delete) | 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.

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
• [ ] 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 | | 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 | Use planModifier: true for custom diff logic | | 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