Introduce `StateMigrateJSON` method/command (#609)
diff --git a/tfexec/internal/e2etest/state_migrate_test.go b/tfexec/internal/e2etest/state_migrate_test.go new file mode 100644 index 0000000..2f7f69d --- /dev/null +++ b/tfexec/internal/e2etest/state_migrate_test.go
@@ -0,0 +1,90 @@ +// Copyright IBM Corp. 2020, 2026 +// SPDX-License-Identifier: MPL-2.0 + +package e2etest + +import ( + "context" + "os" + "path/filepath" + "regexp" + "testing" + + "github.com/google/go-cmp/cmp" + "github.com/hashicorp/go-version" + tfjson "github.com/hashicorp/terraform-json" + + "github.com/hashicorp/terraform-exec/tfexec" + "github.com/hashicorp/terraform-exec/tfexec/internal/testutil" +) + +func TestStateMigrateJSON_tooOldVersion(t *testing.T) { + versions := []string{testutil.Latest_v1_12} + + runTestWithVersions(t, versions, "state_migrate_local_backend", func(t *testing.T, tfv *version.Version, tf *tfexec.Terraform) { + re := regexp.MustCompile("terraform state migrate -json was added in 1.18.0") + + _, err := tf.StateMigrateJSON(context.Background()) + if err == nil { + t.Fatal("expected StateMigrateJSON to fail in old version") + } + if !re.MatchString(err.Error()) { + t.Fatalf("error running StateMigrateJSON: %s", err) + } + }) +} + +func TestStateMigrateJSON_basic(t *testing.T) { + runTest(t, "state_migrate_local_backend", func(t *testing.T, tfv *version.Version, tf *tfexec.Terraform) { + if tfv.LessThan(stateMigrateMinVersion) { + t.Skip("state migrate command not available in this Terraform version") + } + + srcBytes, err := os.ReadFile(filepath.Join(tf.WorkingDir(), "src.tfstate")) + if err != nil { + t.Fatalf("failed to read source state: %s", err) + } + sourceState := string(srcBytes) + + iter, err := tf.StateMigrateJSON(context.Background()) + if err != nil { + t.Fatalf("error running StateMigrateJSON: %s", err) + } + + finalMsg := "" + for nextMsg := range iter { + if nextMsg.Err != nil { + t.Fatalf("error getting next message: %s", nextMsg.Err) + } + switch m := nextMsg.Msg.(type) { + case tfjson.VersionLogMessage: + t.Logf("versions: Terraform %q, UI %q", m.Terraform, m.UI) + case tfjson.DiagnosticLogMessage: + t.Errorf("unexpected diagnostic: %q", m.Msg) + case tfjson.MigrationCompleteMessage: + t.Logf("migration complete: %q", m.Msg) + case tfjson.MigrationFinalizedMessage: + finalMsg = m.Msg + } + } + + expectedMsg := `Finished migrating state from backend "local" to backend "local".` + if diff := cmp.Diff(expectedMsg, finalMsg); diff != "" { + t.Fatalf("unexpected final message: %s", diff) + } + + dstBytes, err := os.ReadFile(filepath.Join(tf.WorkingDir(), "dst.tfstate")) + if err != nil { + t.Fatalf("failed to read destination state: %s", err) + } + destinationState := string(dstBytes) + + if diff := cmp.Diff(sourceState, destinationState); diff != "" { + t.Fatalf("unexpected difference after migration: %s", diff) + } + }) + + // TODO: basic state store test (requires an implemented provider) + + // TODO: provider upgrade test (requires an implemented provider) +}
diff --git a/tfexec/internal/e2etest/testdata/.gitattributes b/tfexec/internal/e2etest/testdata/.gitattributes new file mode 100644 index 0000000..6566631 --- /dev/null +++ b/tfexec/internal/e2etest/testdata/.gitattributes
@@ -0,0 +1,3 @@ +# Always checkout state files with LF (even on Windows) +# to match how the state is written by Terraform +*.tfstate text eol=lf
diff --git a/tfexec/internal/e2etest/testdata/state_migrate_local_backend/.terraform.lock.hcl b/tfexec/internal/e2etest/testdata/state_migrate_local_backend/.terraform.lock.hcl new file mode 100644 index 0000000..6e7e533 --- /dev/null +++ b/tfexec/internal/e2etest/testdata/state_migrate_local_backend/.terraform.lock.hcl
@@ -0,0 +1,2 @@ +# This file is maintained automatically by "terraform init". +# Manual edits may be lost in future updates.
diff --git a/tfexec/internal/e2etest/testdata/state_migrate_local_backend/from.tfmigrate.hcl b/tfexec/internal/e2etest/testdata/state_migrate_local_backend/from.tfmigrate.hcl new file mode 100644 index 0000000..a8a53d9 --- /dev/null +++ b/tfexec/internal/e2etest/testdata/state_migrate_local_backend/from.tfmigrate.hcl
@@ -0,0 +1,5 @@ +from { + backend "local" { + path = "src.tfstate" + } +}
diff --git a/tfexec/internal/e2etest/testdata/state_migrate_local_backend/src.tfstate b/tfexec/internal/e2etest/testdata/state_migrate_local_backend/src.tfstate new file mode 100644 index 0000000..a50176d --- /dev/null +++ b/tfexec/internal/e2etest/testdata/state_migrate_local_backend/src.tfstate
@@ -0,0 +1,36 @@ +{ + "version": 4, + "terraform_version": "1.18.0", + "serial": 1, + "lineage": "effc3564-885c-34f7-cae4-7be5aff731cf", + "outputs": {}, + "resources": [ + { + "mode": "managed", + "type": "terraform_data", + "name": "test", + "provider": "provider[\"terraform.io/builtin/terraform\"]", + "instances": [ + { + "schema_version": 0, + "attributes": { + "id": "c2d8ad26-8316-550c-5e25-bcc3a20e58d9", + "input": { + "value": "foo", + "type": "string" + }, + "output": { + "value": "foo", + "type": "string" + }, + "store": null, + "triggers_replace": null + }, + "sensitive_attributes": [], + "identity_schema_version": 0 + } + ] + } + ], + "check_results": null +}
diff --git a/tfexec/internal/e2etest/testdata/state_migrate_local_backend/to.tf b/tfexec/internal/e2etest/testdata/state_migrate_local_backend/to.tf new file mode 100644 index 0000000..775b02c --- /dev/null +++ b/tfexec/internal/e2etest/testdata/state_migrate_local_backend/to.tf
@@ -0,0 +1,9 @@ +terraform { + backend "local" { + path = "dst.tfstate" + } +} + +resource "terraform_data" "test" { + input = "foo" +}
diff --git a/tfexec/internal/e2etest/util_test.go b/tfexec/internal/e2etest/util_test.go index 7fd872c..ffee59a 100644 --- a/tfexec/internal/e2etest/util_test.go +++ b/tfexec/internal/e2etest/util_test.go
@@ -29,6 +29,8 @@ providerAddressMinVersion = version.Must(version.NewVersion("0.13.0")) metadataFunctionsMinVersion = version.Must(version.NewVersion("1.4.0")) + + stateMigrateMinVersion = version.Must(version.NewVersion("1.18.0-dev")) ) func runTest(t *testing.T, fixtureName string, cb func(t *testing.T, tfVersion *version.Version, tf *tfexec.Terraform)) {
diff --git a/tfexec/options.go b/tfexec/options.go index 30d6b6a..b132f60 100644 --- a/tfexec/options.go +++ b/tfexec/options.go
@@ -476,3 +476,19 @@ func LockFile(useLockFile bool) *LockFileOption { return &LockFileOption{useLockFile: useLockFile} } + +type SourceProviderLockFileOption struct { + path string +} + +func SourceProviderLockFile(path string) *SourceProviderLockFileOption { + return &SourceProviderLockFileOption{path: path} +} + +type DestinationProviderLockFileOption struct { + path string +} + +func DestinationProviderLockFile(path string) *DestinationProviderLockFileOption { + return &DestinationProviderLockFileOption{path: path} +}
diff --git a/tfexec/state_migrate.go b/tfexec/state_migrate.go new file mode 100644 index 0000000..cc40666 --- /dev/null +++ b/tfexec/state_migrate.go
@@ -0,0 +1,104 @@ +// Copyright IBM Corp. 2020, 2026 +// SPDX-License-Identifier: MPL-2.0 + +package tfexec + +import ( + "context" + "fmt" + "iter" + "os/exec" +) + +type stateMigrateConfig struct { + srcProviderLockFile string + dstProviderLockFile string + + upgrade bool + + reattachInfo ReattachInfo +} + +var defaultStateMigrateOptions = stateMigrateConfig{} + +// StateMigrateOption represents options used in the StateMigrate method. +type StateMigrateOption interface { + configureStateMigrate(*stateMigrateConfig) +} + +func (opt *SourceProviderLockFileOption) configureStateMigrate(conf *stateMigrateConfig) { + conf.srcProviderLockFile = opt.path +} + +func (opt *DestinationProviderLockFileOption) configureStateMigrate(conf *stateMigrateConfig) { + conf.dstProviderLockFile = opt.path +} + +func (opt *UpgradeOption) configureStateMigrate(conf *stateMigrateConfig) { + conf.upgrade = opt.upgrade +} + +func (opt *ReattachOption) configureStateMigrate(conf *stateMigrateConfig) { + conf.reattachInfo = opt.info +} + +// StateMigrateJSON executes `terraform state migrate` with `-json` flag +// and any specified options and waits for it to complete. +// +// StateMigrateJSON is likely to be removed in a future major version in favour of +// StateMigrate returning JSON by default. +func (tf *Terraform) StateMigrateJSON(ctx context.Context, opts ...StateMigrateOption) (iter.Seq[NextMessage], error) { + err := tf.compatible(ctx, tf1_18_0, nil) + if err != nil { + return nil, fmt.Errorf("terraform state migrate -json was added in 1.18.0: %w", err) + } + + cmd, err := tf.stateMigrateJSONCmd(ctx, opts...) + if err != nil { + return nil, err + } + + return tf.runTerraformCmdJSONLog(ctx, cmd), nil +} + +func (tf *Terraform) stateMigrateJSONCmd(ctx context.Context, opts ...StateMigrateOption) (*exec.Cmd, error) { + c := defaultStateMigrateOptions + + for _, o := range opts { + o.configureStateMigrate(&c) + } + + mergeEnv := map[string]string{} + if c.reattachInfo != nil { + reattachStr, err := c.reattachInfo.marshalString() + if err != nil { + return nil, err + } + mergeEnv[reattachEnvVar] = reattachStr + } + + args := tf.buildStateMigrateArgs(c) + + return tf.buildTerraformCmd(ctx, mergeEnv, args...), nil +} + +func (tf *Terraform) buildStateMigrateArgs(c stateMigrateConfig) []string { + args := []string{ + "state", "migrate", + "-no-color", + "-input=false", + "-force-copy", + "-json", + } + + if c.srcProviderLockFile != "" { + args = append(args, "-source-provider-lock-file="+c.srcProviderLockFile) + } + if c.dstProviderLockFile != "" { + args = append(args, "-destination-provider-lock-file="+c.dstProviderLockFile) + } + if c.upgrade { + args = append(args, "-upgrade") + } + return args +}
diff --git a/tfexec/state_migrate_test.go b/tfexec/state_migrate_test.go new file mode 100644 index 0000000..dda27ca --- /dev/null +++ b/tfexec/state_migrate_test.go
@@ -0,0 +1,86 @@ +// Copyright IBM Corp. 2020, 2026 +// SPDX-License-Identifier: MPL-2.0 + +package tfexec + +import ( + "context" + "testing" + + "github.com/hashicorp/terraform-exec/tfexec/internal/testutil" +) + +func TestStateMigrateJSONCmd(t *testing.T) { + td := t.TempDir() + + tf, err := NewTerraform(td, tfVersion(t, testutil.Latest_v1)) + if err != nil { + t.Fatal(err) + } + + // empty env, to avoid environ mismatch in testing + tf.SetEnv(map[string]string{}) + + t.Run("defaults", func(t *testing.T) { + stateMigrateJSONCmd, err := tf.stateMigrateJSONCmd(context.Background()) + if err != nil { + t.Fatal(err) + } + + assertCmd(t, []string{ + "state", + "migrate", + "-no-color", + "-input=false", + "-force-copy", + "-json", + }, nil, stateMigrateJSONCmd) + }) + + t.Run("override all defaults", func(t *testing.T) { + stateMigrateJSONCmd, err := tf.stateMigrateJSONCmd(context.Background(), + SourceProviderLockFile("src.lock.hcl"), + DestinationProviderLockFile("dst.lock.hcl"), + Upgrade(true)) + if err != nil { + t.Fatal(err) + } + + assertCmd(t, []string{ + "state", + "migrate", + "-no-color", + "-input=false", + "-force-copy", + "-json", + "-source-provider-lock-file=src.lock.hcl", + "-destination-provider-lock-file=dst.lock.hcl", + "-upgrade", + }, nil, stateMigrateJSONCmd) + }) + + t.Run("reattach config", func(t *testing.T) { + stateMigrateCmd, err := tf.stateMigrateJSONCmd(context.Background(), Reattach(map[string]ReattachConfig{ + "registry.terraform.io/hashicorp/examplecloud": { + Protocol: "grpc", + ProtocolVersion: 6, + Pid: 1234, + Test: true, + Addr: ReattachConfigAddr{ + Network: "unix", + String: "/fake_folder/T/plugin123", + }, + }, + })) + if err != nil { + t.Fatal(err) + } + + assertCmd(t, []string{ + "state", "migrate", + "-no-color", "-input=false", "-force-copy", "-json", + }, map[string]string{ + "TF_REATTACH_PROVIDERS": `{"registry.terraform.io/hashicorp/examplecloud":{"Protocol":"grpc","ProtocolVersion":6,"Pid":1234,"Test":true,"Addr":{"Network":"unix","String":"/fake_folder/T/plugin123"}}}`, + }, stateMigrateCmd) + }) +}
diff --git a/tfexec/version.go b/tfexec/version.go index 751c9b2..aeef247 100644 --- a/tfexec/version.go +++ b/tfexec/version.go
@@ -40,6 +40,7 @@ tf1_13_0 = version.Must(version.NewVersion("1.13.0")) tf1_14_0 = version.Must(version.NewVersion("1.14.0")) tf1_16_0 = version.Must(version.NewVersion("1.16.0")) + tf1_18_0 = version.Must(version.NewVersion("1.18.0")) ) // Version returns structured output from the terraform version command including both the Terraform CLI version