How ‘ -refresh-only ‘ flag works:

The -refresh-only flag can be used with terraform plan and terraform apply commands. When you run a command with this flag, Terraform will detect and show if any changes exists in our infrastructure, but it will not make any updates to our state file.

Let us explore how ‘-refresh-only ‘ flag works with an example:

In this example, we use -refresh-only flag along with terraform plan command.

terraform plan -refresh -only:

When we have an AWS EC2 instance in our account which is created with the help of Terraform Configuration file.

provider "aws" {
  region     = "us-west-2"
  access_key = "AKIAQ******WR3O4SH"
  secret_key = "aRsZ2dhL+U2j*********pXs6bHZ4V0Y0FnN"
}


resource "aws_instance" "my-blog-instance" {
  ami = "ami-0b6d6dacf350ebc82"
  instance_type = "t2.micro"
  tags = {
    Name = "blog-instance"
  }
}

When we terminate this instance (blog-instance) manually in AWS console and run terraform plan -refresh-only, then it shows that the instance has been deleted and we need to run terraform apply to create this terminated instance again.

▪ when we use terraform plan -refresh -only, then we don’t see the plan for changes. It only gives us the information that, instance had been deleted(in our case). But it doesn’t show details about what to add or delete or modify. It just gives information about what has changed in the infrastructure. Also, it doesn’t change our state file.

▪ However, we don’t need to run Terraform commands with the ‘ -refresh-only ‘ flag anymore, because ‘ terraform plan ‘ and ‘terraform apply’ commands now have an integrated state refresh feature, so that it automatically refresh the state before performing their tasks.

▪ But, understanding how the -refresh-only flag works is crucial, as it helps us understand the refresh process in both terraform plan and terraform apply commands.

Terraform Plan = State Refresh + Comparison

Refreshing the State Before Generating the Plan:

terraform plan automatically performs the equivalent of terraform plan -refresh-only internally and fetches the latest state of infrastructure(about instance deletion in our case) and stores it in memory (RAM). We can see “ Refreshing state… “ in the below screenshot.

It then compares this refreshed state(stored in memory) with the desired state in Terraform configuration file and internally calculates what changes need to be made to the infrastructure to match the desired state. Now, it shows us the plan in the output allowing us to decide whether to apply these changes to our infrastructure or not.

terraform apply -refresh-only:

Similar to terraform plan -refresh-only we also have terraform apply -refresh-only. It refreshes the state and asks us: “Would you like to update the Terraform state to reflect these detected changes?”

If we give “yes” then it will change our state file according to the infrastructure. So we use terraform apply -refresh -only when we want to change our state file according to the infrastructure. Even though, when our infrastructure and desired state are different.

Here is the proof:

Terminated EC2 instance:

Before giving terraform apply -refresh-only, the state file looks like:

Running terraform apply -refresh-only:

We get a prompt for confirmation to state file change:

When we give “yes”, the state file will be changed according to the infrastructure.

Terraform Apply = State Refresh + Applying Changes

terraform apply: It helps us to create or modify or delete our infrastructure based on our desired state in our Terraform configuration file.

For Example: when we delete EC2 instance manually and run terraform apply, then it will perform refresh and apply functions. If we did not run terraform plan before terraform apply, then it can also perform plan function and shows us the plan, what needs to be created/modified/deleted.

When we run terraform apply:

Now, EC2 instance will be added to our infrastructure. And based on our created EC2 instance, state file will be modified.

Difference between terraform apply refresh-only and terraform apply in the same scenario of EC2 instance deletion:

So, the difference between terraform apply -refresh-only and terraform apply is:

terraform apply -refresh -only: It helps us to change our state file according to the infrastructure by taking confirmation from us.
If we give “yes” then only it will change our state file, even though both our desired state and our infrastructure are different.

If we give “no” then it won’t change our state file.

terraform apply: It helps us to create/modify/delete our infrastructure based on our desired state and changes the state file according to the current state (infrastructure) after applying.

‘terraform plan’ generates a plan based on the refreshed state and desired state. Then why does ‘terraform apply’ refreshes the state again?

Reason:

▪ Between generating the plan and applying it, the state of our infrastructure might change. For example, someone could manually modify resources, or there could be updates from the cloud provider.

▪ By refreshing the state again during terraform apply Terraform ensures that it is working with the most up-to-date information before actually making any changes to the infrastructure.

For example:

When we modify name of our instance from blog-instance to blog-instance-new between terraform plan and terraform apply.

So, it refreshes the state(not state file) and compares it with the desired state and shows us the plan and asks for our confirmation to apply changes. When we give yes, then our instance name will be changed back to the blog-instance.

▪ After the instance name has been created, it also updates the state file matching the infrastructure.

▪ As, Terraform apply can do plan for us(like in the above screenshot), we might get an idea that, by skipping ‘ terraform plan ‘ command we can run ‘ terraform apply ‘ directly. Even though it’s possible, it is not a best practice, as terraform plan works more effective in planning than ‘ terraform apply ‘. Terraform apply might miss some minor changes.

Good To Know:

terraform refresh :

It is a deprecated terraform command. When we run ‘ terraform refresh ‘ in our terminal, then immediately our state file will be changed according to the existing infrastructure, which is created by the Terraform. But it won’t asks us for confirmation to change the state file according to the infrastructure or not, even though our desired state is different.

For example: When we have one EC2 instance in our AWS account, which is created using Terraform, then if we delete this EC2 instance manually and run terraform refresh in our terminal, then all the information regarding our EC2 instance will be deleted from our state file. If we run terraform plan and terraform apply again, an EC2 instance with the same details will be created again. So, we will end up having multiple instances.

▪ Therefore, it is not recommended to use terraform refresh , as there might be chances in changing our state file by mistake and that would be a big mess when it belongs to large infrastructure.

▪ Of course, we can use terraform.tfstate.backup if we lose terraform.tfstate or if we have saved all state file versions in s3 or GitHub, we can even use these to get our information back in our state file.

▪ To avoid these issues, the -refresh-only option for terraform plan and terraform apply was introduced in Terraform V0.15.4.

Difference between ‘terraform apply -refresh -only’ and ‘terraform refresh’:

So, we can say terraform apply -refresh-only and terraform refresh, both are almost same. Both are used to change the state files according to our infrastructure. Only difference is terraform refresh directly changes our state file according to our infrastructure, but terraform apply -refresh-only asks us to review and confirm whether to change the state file according to the infrastructure or not.

When can we use ‘terraform refresh’ (or) ‘terraform apply -refresh-only’ ?

When the state file is out of sync with the actual infrastructure (e.g., when changes are made manually or outside of Terraform), we can explicitly run the command terraform refresh or terraform apply -refresh-only to update the state file according to the actual infrastructure. This helps synchronize the state without making any changes to the infrastructure itself.

Conclusion:

With the integration of state refresh in commands like terraform plan and terraform apply, Terraform makes the process of managing infrastructure more accurate and efficient. This automatic integration of the refresh process saves time and reduces errors, allowing for smoother and more reliable infrastructure management.

Thanks note:

Thank you for visiting my blog! I hope you found this information helpful. If you enjoyed this post, feel free to follow me for more interesting and useful information. All my blogs will be in simple, general English, making it easy to understand. Stay tuned for more updates!

References:

https://developer.hashicorp.com/terraform/cli/commands/refresh

https://developer.hashicorp.com/terraform/tutorials/state/refresh

What happens when we run 'terraform plan' and 'terraform apply' with '-refresh-only' flag and when we run without this flag?