Terraform 1.1 Improves Refactoring and the Cloud CLI Experience

We’re excited to announce the release of HashiCorp Terraform 1.1, now immediately available for download as well as for use in HashiCorp Terraform Cloud. Terraform is widely adopted as the standard for multi-cloud provisioning and automation, for individuals and for teams at any scale. This release marks a milestone in delivering new ways to easily and safely refactor as part of your Day 2 operations, as well as an improved command-line interface (CLI) experience for Terraform Cloud and Terraform Enterprise users.

»Easier and Safer Refactoring with moved Statements

As a team’s infrastructure grows in both quantity and complexity, its Terraform configuration can often become unmanageable. When this happens, practitioners might want to do some refactoring, such as splitting a single module into multiple modules — whether it be modules within a single configuration or shared modules across multiple configurations. Terraform 1.1 introduces a new mechanism for refactoring using moved statements within a module’s own source code, enabling users to plan, preview, and validate multiple refactoring actions simultaneously.

»Refactoring with terraform state mv

Prior to this release, refactoring tasks required terraform state mv commands via the CLI, along with corresponding changes to configuration. This process was often difficult and awkward, as well as potentially risky. Not only did users need to worry about updating their configuration, but also needed to update state without actually destroying and recreating infrastructure.

Additionally, directly refactoring modules was not possible for module authors and Terraform Cloud users. For module authors, refactoring a module required releasing a new major version to indicate a breaking change, along with a guide for end users to manually update state. For Terraform Cloud and Enterprise users, refactoring within core Terraform Cloud workflows wasn’t feasible, as users need to be able to create a plan based on configuration changes. This often led users with admin access on the workspace to switch to local state with the CLI to make out-of-band and risky changes.

»Refactoring with moved Statements

Terraform 1.1 introduces a new mechanism to safely refactor Terraform modules and configurations — all as part of creating a plan. These moved statements are written into a module’s source code, which allows Terraform to combine state updates with the configuration changes during the plan phase.

These moved statements can be used to:

• Rename a resource
• Enable count or for_each for a resource
• Rename a module call
• Enable count or for_each for a module call
• Split one module into multiple modules

Since these actions are declared in the configuration, Terraform will explain the changes as part of the plan output, so users can then validate and apply multiple actions at once. This allows for much easier and safer refactoring, without requiring users to touch state. This new mechanism also allows module authors and Terraform Cloud users to refactor within their workflows — no out-of-band or manual tasks required.

»An Improved CLI Experience for Terraform Cloud and Enterprise

Terraform Cloud and Enterprise practitioners use three core workflows, either in isolation or jointly:

• UI/VCS-driven workflows
• CLI-driven workflows
• API-driven workflows

Each of these workflows represent ways that users trigger and manage runs, along with other remote operations.

With the release of Terraform 1.1, we wanted to focus on enhancing the CLI-driven workflow by introducing a new integration with Terraform Cloud and Terraform Enterprise. This new way of connecting to Terraform Cloud is declared as a cloud block within the terraform settings block, and allows for new functionality, improved error messages, and an overall better practitioner experience.

»How is the New Cloud Integration Different?

Prior to this release, users would connect to Terraform Cloud by declaring a remote backend in their backend configuration. While this integration worked, the overall developer experience and functionality left room for improvement. In terms of functionality, this new integration allows users to pass input variables using the -var flags (along with the other methods of supplying variables), as well as managing workspaces via workspace tags — all from the CLI. For improving the developer experience, we focused on three things:

1. Improving error messages and CLI prompts
2. Clarifying remote state storage versus remote operations
3. Helping users better understand Terraform Cloud workspaces

»Improving Error Messages and CLI Prompts

Firstly, the new Terraform Cloud integration comes with more useful error messages to help users quickly understand and resolve issues. The existing remote backend often confused users with generic responses pointing to backend issues without context on how to find the culprit and fix the problem. This has been replaced with actionable help output that’s more applicable to Terraform Cloud users.

Additionally, we’ve added context-rich prompts to help users quickly onboard and migrate state, whether from a local Terraform project, an Amazon S3 backend, or the existing remote backend.

That leads us to the next point: what is a remote backend, and how is Terraform Cloud different?

»Clarifying Remote State Storage Versus Remote Operations

This new integration offers a much simpler answer to that question. Remote backends define where Terraform state is stored, such as on local disk or in another storage service (such as S3). Terraform Cloud provides both state storage and an execution environment for remote operations. This new integration clarifies this by making a native integration (rather than an all-purpose remote backend) within the terraform top-level settings block. Now, all backends refer only to where state can be stored, and Terraform Cloud and Enterprise have a baked-in presence where users can define things like workspace tags and names for managing runs.

»Helping Users Better Understand Terraform Cloud Workspaces

Lastly, we wanted to help users better understand Terraform Cloud workspaces. In Terraform Cloud, a workspace contains everything Terraform needs to manage a collection of infrastructure — including execution context, stored values for input variables, state versioning, run history, and more. Workspaces are flexible and are not associated with a particular configuration, but rather with a Terraform Cloud organization.

In this way, Terraform Cloud workspaces behave like completely separate working directories, and are typically named by both the set of resources they contain as well as the deployment environments they provision (for example, networking-prod-east). With the workspace block in the new cloud block, users can add workspace tags (such as prod) and their workspace in the Terraform Cloud UI will reflect exactly what’s in the configuration. Previously, remote backend users could use only workspace names and prefixes, which made the mental model more confusing than necessary. Additionally, expressions like ${terraform.workspace} will now refer to the Terraform Cloud workspace name in all workflows (CLI, API, or VCS-driven runs).

To learn how to seamlessly migrate your existing backend to the new Terraform Cloud integration, see the documentation. Or sign-up for a free Terraform Cloud account for remote state storage, remote runs, state versioning, and more.

»Getting Started with Terraform 1.1

• Download the Terraform 1.1 release
• Sign up for a free Terraform Cloud account
• Review the Using Terraform Cloud with Terraform CLI documentation.
• Explore our HashiCorp Learn tutorials, including the new Use Configuration to Move Resources and Migrate State from S3 to Terraform Cloud tutorials.

For more details, please see the full HashiCorp Terraform 1.1 changelog. This release wouldn't have been possible without all of the great community feedback we've received via GitHub issues and elsewhere. Thank you!