Using the Controlled Remote State Access Migration Tool

Overview

Terraform Enterprise v202104-1 and later includes a command-line tool to help you adopt the controlled remote state access feature across many workspaces. The tool examines the usage of the terraform_remote_state data source in your existing workspaces and provides recommendations for configuring remote state consumers. This helps you implement the feature without interrupting existing workflows.

Prerequisites

To run the migration tool, you need:

• An installation of Terraform Enterprise v202104-1 or later.
• Superuser access to the instance running Terraform Enterprise to connect via SSH.

Procedure

The migration tool is a wrapper around a rake task within the ptfe_atlas container. It is safe to re-run the tool multiple times if you encounter any errors or timeouts.

1. Connect to the Terraform Enterprise instance (or one of the nodes in a clustered deployment) using SSH.

2. Connect to the application container. The container name depends on your Terraform Enterprise version.

   For Terraform Enterprise versions before v202205-1, use ptfe_atlas.

   $ sudo docker exec -it ptfe_atlas /bin/bash

   For Terraform Enterprise v202205-1 or later, use tfe-atlas.

   $ sudo docker exec -it tfe-atlas /bin/bash

3. (Optional) Once connected to the container, view the configuration options for the migration script.

   $ ./scripts/populate_state_sharing_settings.sh --help

4. Run the migration script.

   $ ./scripts/populate_state_sharing_settings.sh

5. The tool will prompt you to establish relationships for workspaces that consume state from other workspaces. Review the output and respond to the prompts. ```text

   Organization: hashicorp

   output-workspace-1's state is used by: -> consumer-workspace output-workspace-2's state is used by: -> consumer-workspace Establish relationships between these workspaces? (y/n) Choosing y means that state from the producing workspace can only be accessed by the consuming workspace(s), instead of being available to any workspace in the organization. You can always adjust these settings via the workspace settings page.

6. After assessing all workspaces with active state sharing, the tool offers to switch all remaining workspaces to restricted sharing. Review the prompt and respond.

   Require explicit remote state access for remaining workspaces in this organization? (y/n)
   There are 27 workspace(s) left in this organization which are
   configured to allow remote state access from any other workspace
   in the organization. Choosing y means that going forward, these
   workspace(s) must explicitly choose to allow state access. This
   setting can always be adjusted via the workspace settings page.

Troubleshooting

Terraform State Parser Issues

The tool relies on data populated by the Terraform state parser service. This data is automatically populated during Terraform runs. If some workspaces have not had a run since the upgrade to v202104-1, the tool will attempt to populate the missing data and display the following message.

Some workspaces in organization hashicorp are missing
remote state access data. Populating missing data...
...........................Done!

If this step times out, the Terraform state parser service may be experiencing high load. To resolve this, you can lower the batch size from its default of 10. Re-run the migration tool with the --batch-size option.

$ ./scripts/populate_state_sharing_settings.sh --batch-size 5

Renamed Workspaces and Organizations

The terraform_remote_state data source uses workspace and organization names to find the correct state. If a workspace or organization was renamed since the last Terraform run, the migration tool may not detect the relationship.

To correct this, queue a new run in any workspace that was recently renamed, as well as in any workspaces that consume state from it.