State replace-provider in Terraform - Step-by-Step Execution

Process Flow - State replace-provider

Identify old provider in state

↓

Specify new provider details

↓

Run terraform state replace-provider

↓

Terraform updates state file

↓

Verify state points to new provider

↓

Done

This flow shows how Terraform replaces a provider in the state file by identifying the old provider, specifying the new one, running the command, updating the state, and verifying the change.

Execution Sample

Terraform

terraform state replace-provider \
  registry.terraform.io/terraform-providers/aws \
  registry.terraform.io/hashicorp/aws

This command replaces the AWS provider in the Terraform state from the old source to the new source.

Process Table

Step	Action	Input	State Change	Result
1	Identify old provider in state	registry.terraform.io/terraform-providers/aws	None yet	Old provider found in state
2	Specify new provider	registry.terraform.io/hashicorp/aws	None yet	New provider details ready
3	Run replace-provider command	terraform state replace-provider registry.terraform.io/terraform-providers/aws registry.terraform.io/hashicorp/aws	State file updated	Provider references replaced
4	Verify state	terraform state list	State file unchanged	State shows new provider
5	Done	N/A	N/A	Replacement complete

💡 Replacement stops after state file updates and verification confirms new provider

Status Tracker

Variable	Start	After Step 3	Final
provider_source	registry.terraform.io/terraform-providers/aws	registry.terraform.io/hashicorp/aws	registry.terraform.io/hashicorp/aws

Key Moments - 2 Insights

Why do we need to specify both old and new provider sources?

Because Terraform needs to know exactly which provider to replace (old) and what to replace it with (new), as shown in execution_table step 3.

Does running replace-provider change the actual infrastructure?

No, it only updates the state file to point to the new provider, not the real infrastructure, as seen in step 3 and 4.

Visual Quiz - 3 Questions

Look at the execution table, what is the state of provider_source after step 3?

A registry.terraform.io/terraform-providers/aws

B registry.terraform.io/hashicorp/aws

C Unchanged

D Empty

💡 Hint

Check variable_tracker column 'After Step 3' for provider_source

At which step does Terraform update the state file?

A Step 3

B Step 1

C Step 2

D Step 4

💡 Hint

See execution_table 'State Change' column for when state file updates

If you forget to specify the new provider, what will happen?

A Terraform replaces with a default provider

B Terraform skips replacement

C Terraform errors and stops

D Terraform replaces with the old provider again

💡 Hint

Refer to key_moments about specifying old and new providers

Concept Snapshot

terraform state replace-provider old_provider new_provider

- Replaces provider references in Terraform state
- Does not change real infrastructure
- Requires exact old and new provider addresses
- Run before terraform apply if provider source changes

Full Transcript

Terraform state replace-provider updates the provider references inside the Terraform state file. First, it identifies the old provider source in the state. Then, you specify the new provider source you want to replace it with. Running the command updates the state file to point to the new provider. This does not affect the actual infrastructure, only the state file. Finally, you verify the state to confirm the replacement. This process is useful when provider sources change but infrastructure remains the same.