Run a refresh-only operation

To manage your infrastructure and propose changes, Terraform reconciles your configuration, state file, and the actual status of the resources it manages. To ensure the accuracy of the proposed changes, your state file must be up to date.

Resource drift is when your resources no longer match your Terraform state. Drift can occur when you or others change resources outside of the Terraform workflow. This makes it hard for your team to make sense of proposed changes and can lead to unintended changes to your infrastructure.

In Terraform, refresh-only operations update your Terraform state file to match the actual state of your infrastructure. Terraform plan and apply operations run an implicit in-memory refresh, but they do not update your state unless you complete an apply operation. Refresh-only operations update your state file without changing your deployed resources, ensuring that future operations proceed as expected.

In this tutorial, you will change to your infrastructure outside of the Terraform workflow, then use a refresh-only operation to detect this drift. You will then review the output from the refresh-only operation and decide if you want to keep the change and update your configuration, or revert the change and update the resource to match your Terraform configuration.

Prerequisites

To follow this tutorial, you will need:

• An HCP Terraform account and organization
• An AWS account and associated credentials that allow you to create resources in the us-west-2 region, including an EC2 instance, VPC, and security groups.
• A GitHub account.
• The learn-hcp-terraform workspace you created in the previous tutorial.

Introduce drift

In the Trigger HCP Terraform runs from VCS changes tutorial, you created an EC2 instance named learn-hcp-terraform when you deployed the following aws_instance resource and set your workspace variable to learn-hcp-terraform:

resource "aws_instance" "app_server" {
  ami           = data.aws_ami.ubuntu.id
  instance_type = var.instance_type

  tags = {
    Name = var.instance_name
  }
}

To intentionally introduce drift, update the Name tag of your EC2 instance. To do this, open your EC2 console and click the pencil icon next to your learn-hcp-terraform-upstream instance. Update the name to manually-changed and press Enter.

Since your state file tracks the name of the EC2 instance, this introduces drift between your state and your resource.

Run a refresh-only operation

Next, run a refresh-only operation to update your state to match the real-world resource configuration.

Log in to HCP Terraform and navigate to your learn-hcp-terraform workspace. Click New run button, then choose Refresh state from the Run Type drop-down menu. Click Start to begin the refresh-only operation.

Once HCP Terraform finishes the plan, it reports that it detected the Name tag changed and does not match the value it has in the latest state file. Notice that HCP Terraform also reports that it will not add, change, or destroy any resources if you confirm and apply this plan. It only updates the value it has in state.

Click Confirm & apply, then click Confirm plan to update your state file to match the real-world resource. Once HCP Terraform completes the apply operation, it reports that it refreshed the state, but it did not change any resources outside of Terraform.

Because this run did not perform an apply operation, it does not trigger downstream run triggers.

Update configuration

After identifying drift between your state and your resources, you must decide if you want to accept the new value and update your configuration, or reject the change and reapply your configuration to revert the resource to its original state.

In this case, update your configuration to match the new value. Since the instance_name workspace variable defines the value for the Name tag in your configuration, you don't actually need to change your configuration. You only need to update the instance_name workspace variable to match the new value.

Click Variables in the left navigation panel of your learn-hcp-terraform workspace. Next to the instance_name variable, open the ... menu and click Edit variable. Update the Value to manually-changed and click Save variable.

Next, apply your changes to verify that your configuration, state, and resource now match. Click New run in the top-right corner, keep the Run Type as Plan and apply, then click Start.

Notice that the run completes the plan, reports that your infrastructure matches the configuration, and does not need to complete an apply operation. This means that your configuration, state, and resource now all once again match.

Next steps

In this tutorial, you learned how Terraform uses configuration, state, and resource to propose infrastructure changes . Then, you manually introduced drift so that your configuration and state no longer matched your resource. You then ran a refresh-only operation to update your state, then reconciled your configuration to match the change.

Refresh-only operations ensure predictable infrastructure operations. In some editions of HCP Terraform, you can also use drift detection to periodically run refresh-only operations. If HCP Terraform detects drift, it displays an alert on the workspace.

Continue to the next tutorial to learn how to destroy infrastructure with HCP Terraform.