cli: manual AWS terraform state transitions

This commit is designed to be reverted in the future (AB#3248).
Terraform does not implement moved blocks with dynamic targets: https://github.com/hashicorp/terraform/issues/31335 so we have to migrate the terraform state ourselves.

cli/internal/terraform/terraform.go

@@ -47,9 +47,10 @@ var ErrTerraformWorkspaceExistsWithDifferentVariables = errors.New("creating clu
 type Client struct {
 	tf tfInterface
 
-	file       file.Handler
-	workingDir string
-	remove     func()
+	manualStateMigrations []StateMigration
+	file                  file.Handler
+	workingDir            string
+	remove                func()
 }
 
 // New sets up a new Client for Terraform.
@@ -71,6 +72,12 @@ func New(ctx context.Context, workingDir string) (*Client, error) {
 	}, nil
 }
 
+// WithManualStateMigration adds a manual state migration to the Client.
+func (c *Client) WithManualStateMigration(migration StateMigration) *Client {
+	c.manualStateMigrations = append(c.manualStateMigrations, migration)
+	return c
+}
+
 // Show reads the default state path and outputs the state.
 func (c *Client) Show(ctx context.Context) (*tfjson.State, error) {
 	return c.tf.Show(ctx)
@@ -105,6 +112,10 @@ func (c *Client) CreateCluster(ctx context.Context, logLevel LogLevel) (CreateOu
 		return CreateOutput{}, fmt.Errorf("terraform init: %w", err)
 	}
 
+	if err := c.applyManualStateMigrations(ctx); err != nil {
+		return CreateOutput{}, fmt.Errorf("apply manual state migrations: %w", err)
+	}
+
 	if err := c.tf.Apply(ctx); err != nil {
 		return CreateOutput{}, fmt.Errorf("terraform apply: %w", err)
 	}
@@ -296,6 +307,10 @@ func (c *Client) Plan(ctx context.Context, logLevel LogLevel, planFile string) (
 		return false, fmt.Errorf("terraform init: %w", err)
 	}
 
+	if err := c.applyManualStateMigrations(ctx); err != nil {
+		return false, fmt.Errorf("apply manual state migrations: %w", err)
+	}
+
 	opts := []tfexec.PlanOption{
 		tfexec.Out(planFile),
 	}
@@ -372,6 +387,23 @@ func GetExecutable(ctx context.Context, workingDir string) (terraform *tfexec.Te
 	return tf, func() { _ = inst.Remove(context.Background()) }, err
 }
 
+// applyManualStateMigrations applies manual state migrations that are not handled by Terraform due to missing features.
+// Each migration is expected to be idempotent.
+// This is a temporary solution until we can remove the need for manual state migrations.
+func (c *Client) applyManualStateMigrations(ctx context.Context) error {
+	for _, migration := range c.manualStateMigrations {
+		if err := migration.Hook(ctx, c.tf); err != nil {
+			return fmt.Errorf("apply manual state migration %s: %w", migration.DisplayName, err)
+		}
+	}
+	return nil
+	// expects to be run on initialized workspace
+	// and only works for AWS
+	// if migration fails, we expect to either be on a different CSP or that the migration has already been applied
+	// and we can continue
+	// c.tf.StateMv(ctx, "module.control_plane.aws_iam_role.this", "module.control_plane.aws_iam_role.control_plane")
+}
+
 // writeVars tries to write the Terraform variables file or, if it exists, checks if it is the same as we are expecting.
 func (c *Client) writeVars(vars Variables) error {
 	if vars == nil {
@@ -408,6 +440,13 @@ func (c *Client) setLogLevel(logLevel LogLevel) error {
 	return nil
 }
 
+// StateMigration is a manual state migration that is not handled by Terraform due to missing features.
+// TODO(AB#3248): Remove this after we can assume that all existing clusters have been migrated.
+type StateMigration struct {
+	DisplayName string
+	Hook        func(ctx context.Context, tfClient TFMigrator) error
+}
+
 type tfInterface interface {
 	Apply(context.Context, ...tfexec.ApplyOption) error
 	Destroy(context.Context, ...tfexec.DestroyOption) error
@@ -417,4 +456,11 @@ type tfInterface interface {
 	ShowPlanFileRaw(ctx context.Context, planPath string, opts ...tfexec.ShowOption) (string, error)
 	SetLog(level string) error
 	SetLogPath(path string) error
+	TFMigrator
+}
+
+// TFMigrator is an interface for manual terraform state migrations (terraform state mv).
+// TODO(AB#3248): Remove this after we can assume that all existing clusters have been migrated.
+type TFMigrator interface {
+	StateMv(ctx context.Context, src, dst string, opts ...tfexec.StateMvCmdOption) error
 }