Guide to terraform refresh, import, and replace

Terraform, the open-source infrastructure as code (IaC) tool, offers a robust suite of commands for managing and maintaining infrastructure. In this post, we’ll dive into three important Terraform commands: terraform refresh, terraform import, and terraform replace. Understanding these commands can help you effectively manage infrastructure states, integrate existing resources, and handle resource updates.

Table of Contents:

• 1. terraform refresh

• 2. terraform import

• 3. terraform replace

1. terraform refresh

The terraform refresh command updates the Terraform state to match the real-world infrastructure without modifying any infrastructure resources.

When to Use:

• To check for out-of-sync states after manual changes are made to resources.

• Before running terraform plan to ensure the latest state of your resources is reflected.

Command Syntax:

terraform refresh

Example:

Let’s say you have a resource in your Terraform configuration:

resource "aws_instance" "example" {
  ami           = "ami-12345678"
  instance_type = "t2.micro"
}

If someone manually changes the AMI ID outside of Terraform (via the AWS Console, for example), the state file won’t automatically know about it. By running terraform refresh, Terraform will fetch the latest AMI ID and update the state file.

$ terraform refresh
aws_instance.example: Refreshing state... [id=i-0abcd1234ef567890]

After running this command, Terraform’s state file reflects the latest real-world resource configuration, but it doesn’t modify any resource unless you explicitly apply changes.

Key Notes:

• terraform refresh does not modify infrastructure; it only updates the state file.

• Always ensure your state is up to date by refreshing before running plan and apply.

2. terraform import

The terraform import command allows Terraform to integrate existing infrastructure that was not originally managed by Terraform into its state. This is useful when you have resources created manually or by other systems, and you want to start managing them via Terraform.

When to Use:

• When you want to start managing a resource created outside of Terraform.

• Migrating resources from manual creation or other tools to Terraform.

Command Syntax:

terraform import [OPTIONS] ADDRESS ID

• ADDRESS refers to the resource in the configuration, and ID is the identifier of the existing resource.

Example:

Let’s assume an EC2 instance (i-0abcd1234ef567890) was created manually in AWS. You want Terraform to manage this instance. First, add the resource configuration in your .tf file:

resource "aws_instance" "imported_example" {
  ami           = "ami-12345678"
  instance_type = "t2.micro"
}

Next, run the import command to bring the existing EC2 instance into Terraform’s state:

$ terraform import aws_instance.imported_example i-0abcd1234ef567890
aws_instance.imported_example: Importing from ID "i-0abcd1234ef567890"...
aws_instance.imported_example: Import complete!

After importing, the state file knows about the existing resource, and Terraform can now manage it as if it was initially created via Terraform.

Key Notes:

• terraform import doesn’t modify the resource, but only maps it to Terraform’s state.

• You need to manually add the corresponding resource block in your configuration file before running import.

3. terraform replace

The terraform replace command forces the replacement of a resource. This is useful when you want to recreate a resource due to configuration changes or infrastructure requirements.

When to Use:

• If a resource needs to be destroyed and re-created to apply certain changes.

• When you need to handle errors by forcing a clean rebuild of a resource.

Command Syntax:

terraform apply -replace="RESOURCE_ADDRESS"

• RESOURCE_ADDRESS is the address of the resource to be replaced.

Example:

Suppose you want to replace an AWS EC2 instance because its configuration needs a clean rebuild. Here’s how you can force Terraform to replace it:

$ terraform apply -replace="aws_instance.example"

Terraform will then show a plan where it intends to destroy the existing resource and recreate a new one:

Plan: 1 to add, 0 to change, 1 to destroy.

This ensures a fresh deployment of the resource, even if there were no configuration changes that would automatically trigger a replacement.

Key Notes:

• Replacing a resource will first destroy it and then create a new one.

• Be cautious when using -replace for resources that have stateful information or critical dependencies.

Conclusion

Terraform offers powerful tools to manage infrastructure effectively:

• terraform refresh ensures that the state file is always in sync with real-world resources.

• terraform import helps to integrate existing infrastructure into Terraform management.

• terraform replace enables you to forcefully recreate resources when needed.

Mastering these commands will help you maintain, integrate, and upgrade infrastructure in a more controlled and reliable manner, ensuring smoother operations in any Terraform-managed environment.