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.

Practice

1. What is the main purpose of the terraform state replace-provider command?

easy

A. To delete all resources managed by a provider

B. To apply changes to infrastructure

C. To initialize a new Terraform project

D. To update provider references in the Terraform state file after a provider rename or move

Solution

1. Step 1: Understand the command's purpose

   terraform state replace-provider is used to update provider references in the state file when a provider is renamed or moved.

2. Step 2: Compare with other commands

   Other options like deleting resources, initializing projects, or applying changes are unrelated to this command.

3. Final Answer:

   To update provider references in the Terraform state file after a provider rename or move -> Option D

4. Quick Check:

   Replace-provider updates provider names in state [OK]

Hint: Remember: replace-provider updates provider names in state [OK]

Common Mistakes:

• Confusing replace-provider with terraform apply
• Thinking it deletes resources
• Mixing it up with terraform init

2. Which of the following is the correct syntax to replace the provider registry.terraform.io/old/provider with registry.terraform.io/new/provider in the Terraform state?

easy

A. terraform state replace-provider --from=old/provider --to=new/provider

B. terraform replace-provider state registry.terraform.io/old/provider registry.terraform.io/new/provider

C. terraform state replace-provider registry.terraform.io/old/provider registry.terraform.io/new/provider

D. terraform provider replace-state old/provider new/provider

Solution

1. Step 1: Recall the correct command syntax

   The correct syntax is terraform state replace-provider OLD_PROVIDER NEW_PROVIDER without flags.

2. Step 2: Check each option

   terraform state replace-provider registry.terraform.io/old/provider registry.terraform.io/new/provider matches the correct syntax exactly. Options B, C, and D use incorrect command order or flags.

3. Final Answer:

   terraform state replace-provider registry.terraform.io/old/provider registry.terraform.io/new/provider -> Option C

4. Quick Check:

   Correct syntax is 'terraform state replace-provider OLD NEW' [OK]

Hint: Use 'terraform state replace-provider OLD NEW' exactly [OK]

Common Mistakes:

• Adding extra flags like --from or --to
• Swapping command order
• Using 'replace-state' instead of 'replace-provider'

3. Given the command:
terraform state replace-provider registry.terraform.io/old/provider registry.terraform.io/new/provider
What will happen to the Terraform state after running this command?

medium

A. All resources using the old provider will now reference the new provider in the state file

B. Terraform will delete all resources managed by the old provider

C. Terraform will initialize a new provider configuration

D. The state file will be reset to empty

Solution

1. Step 1: Understand the effect of replace-provider

   The command updates the provider references in the state file from old to new, so Terraform tracks resources correctly.

2. Step 2: Eliminate incorrect outcomes

   The command does not delete resources, initialize providers, or reset state; it only changes provider references.

3. Final Answer:

   All resources using the old provider will now reference the new provider in the state file -> Option A

4. Quick Check:

   State provider references updated, resources unchanged [OK]

Hint: Replace-provider changes provider refs, does not delete resources [OK]

Common Mistakes:

• Thinking resources get deleted
• Confusing with terraform init
• Assuming state resets

4. You ran terraform state replace-provider registry.terraform.io/old/provider registry.terraform.io/new/provider but got an error saying the old provider is not found in the state. What is the most likely cause?

medium

A. The new provider is not installed locally

B. The old provider name is incorrect or does not exist in the current state

C. You forgot to run terraform init before the command

D. Terraform version is too old to support replace-provider

Solution

1. Step 1: Analyze the error message

   If Terraform says the old provider is not found, it means the exact old provider name is not present in the state file.

2. Step 2: Consider other options

   While Terraform version or init might cause other errors, this specific error points to a wrong old provider name.

3. Final Answer:

   The old provider name is incorrect or does not exist in the current state -> Option B

4. Quick Check:

   Old provider must match state exactly [OK]

Hint: Check old provider name matches state exactly [OK]

Common Mistakes:

• Assuming terraform init fixes provider name errors
• Ignoring exact provider namespace and name
• Thinking new provider installation affects this error

5. You have a Terraform state using provider registry.terraform.io/oldcorp/cloud. The provider was renamed to registry.terraform.io/newcorp/cloud. You want to update your state safely. Which sequence of steps is best practice?

hard

A. Backup state file, run terraform state replace-provider registry.terraform.io/oldcorp/cloud registry.terraform.io/newcorp/cloud, then run terraform plan

B. Run terraform state replace-provider without backup, then run terraform apply

C. Delete the old provider block from configuration, then run terraform init

D. Manually edit the state file to replace provider names

Solution

1. Step 1: Backup the state file

   Always backup your state before making changes to avoid data loss.

2. Step 2: Run replace-provider command

   Use terraform state replace-provider to update provider references safely.

3. Step 3: Run terraform plan

   Check the plan to verify no unexpected changes before applying.

4. Final Answer:

   Backup state file, run terraform state replace-provider, then run terraform plan -> Option A

5. Quick Check:

   Backup first, replace provider, then plan [OK]

Hint: Always backup state before replace-provider, then plan [OK]

Common Mistakes:

• Skipping state backup
• Editing state file manually
• Running apply without plan