New Terraform Planning Options: -refresh=false, -refresh-only, -replace

HashiCorp Terraform Cloud and Terraform Enterprise now offer new options to provide more explicit control over when resource state is refreshed and when resources need to be replaced. With these new features customers can reduce the time it takes to make changes to their infrastructure. These features have been available in open source Terraform in June of this year.

»Introducing -refresh=false Planning Option and -refresh-only Plan Mode

The Terraform plan and apply workflow normally begins with a preemptive refresh of the state of your infrastructure — this ensures that any changes that have happened out-of-band are detected and that your infrastructure converges back to what is defined in code. The time taken for this refresh can be considerable when managing large scale deployments, and if you’re all-in on Terraform Cloud or Enterprise it can be unnecessary as Terraform already has the latest state. That’s time you and your team can get back so that your changes are quicker to plan and quicker to deploy! Support for the -refresh=false plan option with Terraform Cloud and Enterprise means teams can now execute their plans and applies without that preemptive state refresh.

Out-of-band changes can still occur though, and without a refresh Terraform Cloud and Enterprise will not know that configuration has drifted. For that reason we've also added a complementary -refresh-only plan mode, that customers can queue on whatever schedule or event is appropriate to their needs. This will update the state to reflect the current deployed configuration according to a more convenient schedule for your organization, and any subsequent apply will converge the infrastructure back to what is defined in code.

»Introducing Support for -replace Planning Option

There are occasions when a resource has previously been provisioned but it has degraded in some way and needs to be replaced. A configuration change might not be needed, but a record of the change is still warranted. Existing approaches to dealing with this (e.g., the taint subcommand) worked great for solo practitioners. However, teams collaborating on infrastructure would need to coordinate out-of-band to ensure resources were replaced without inadvertently deploying unintended changes from another team mid-replacement.

The -replace planning option provides an improved way to replace degraded resources as a single atomic operation within a Terraform plan, avoiding potential race conditions in the highly collaborative environment of Terraform Cloud and Terraform Enterprise.

Rather than the previous approach of queueing up a number of resources to replace and then eventually planning and applying your change, the replacements are defined alongside the plan. This guarantees that the replacement and changes are bundled together in a single operation. There’s no longer a risk of a teammate inadvertently inserting their change into the middle of your flow. Instead you now have a workflow that is consistent with the collaboration, visibility, and auditing expectations of Terraform Cloud and Enterprise customers

»Quicker Plans (and Applies)

For a simple example of what providing the -refresh=false plan option can do, compare the two side-by-side CLI-based terraform apply runs below. In both cases there have been no configuration changes, and so there are no changes to be applied.The left side shows the default behavior of Terraform, on the right is the same command executed with the additional refresh=false option:

The whole process is much more straightforward on the right-hand version because there’s less work to do. Even with only a few resources to manage, the operation is completed significantly faster on the right-hand side with a greatly reduced output. Workspaces managing large numbers of resources will see even more significant improvements.

»Detecting and Correcting Out-of-Band Changes

As we discussed earlier, out-of-band changes can still occur, and without a refresh Terraform Cloud and Terraform Enterprise will not know that configuration has drifted. To get a sense of what that looks like in practice, the demo below manually removes a few subnets via the AWS Console, and then queues up a -refresh-only plan (via the web UI):

Running a refresh-only plan allows customers to run a plan without having to push any configuration changes. You can see in the output above that it detects the changes we made outside of Terraform, and asks if we'd like to update our state to reflect what is currently deployed.

If these are intentional changes, this is an opportunity to update the configuration to match what’s in production and move all of our infrastructure configuration back into code. In this example we’re assuming the deletion of the subnets was a mistake that we want to correct.

We apply this plan so our state once again reflects what is deployed, and then immediately queue a new plan. When that plan completes it identifies that the deployed state has diverged from our configuration and prompts us to bring the missing subnets back. A click of the Confirm button and they’re back.

»Replacing Resources with -replace

Finally, the new -replace option allows customers to queue up a plan that intentionally replaces a degraded or unhealthy resource. The example below flags one of the subnets from the earlier examples for replacement:

The plan will mark that resource to be removed and then recreated using the provided configuration. This is similar to the workflow customers may be familiar with using the previous taint subcommand, but now batched into a single atomic command that is consistent with the collaboration expectation of Terraform Cloud and Terraform Enterprise customers.

»Getting Started

All of these features are available today in Terraform Cloud, and in the 202106-01 release of Terraform Enterprise. More details on how to use these features can be found in our official documentation and resources:

• refresh=false plan option
• -refresh-only plan mode
• -replace plan option
• HashiCorp Learn guide on Using Refresh-Only Mode to Sync Terraform State
• HashiCorp Learn guide on Managing Resource Drift
• Armon Dadgar’s whiteboard presentation on how you can prevent configuration drift
• HashiCorp blog guide on Detecting and Managing Drift with Terraform