Accessing A Workspace's State Data

Introduction

In April 2021, a change was introduced to Terraform Cloud (now HCP Terraform) to restrict access to a workspace’s state data by default. This behavior is introduced to Terraform Enterprise in v202104-1. This change limits workspaces’ ability to access other workspaces’ remote state using the terraform_remote_state data source by default.

Use Case

For new workspaces created after this change, the steps outlined in this document are required in order to allow other workspaces to access a target workspace’s state data via the terraform_remote_state data source.

Procedure

There are two options for allowing access to a workspace’s state:

1. Share with all workspaces in this organization: All workspaces within the same organization may access the state data of the target workspace.
2. Share with specific workspaces: Only the specified list of workspaces may access the state data of the target workspace. If no workspaces are selected, no other workspaces may access the state data of the target workspace.

We recommend that you follow the principle of least privilege and only enable state access between workspaces that specifically need information from each other.

Note: In Terraform Cloud, workspaces created before this change default to global sharing. Workspaces created after the change do not allow state sharing by default. For Terraform Enterprise, administrators may can choose whether new workspaces on their instances default to global access or selective access.

Workspaces may be configured to allow state access in three ways:

1. Using the Terraform Cloud or Terraform Enterprise UI
2. Using the tfe provider’s tfe_workspace resource
3. Using the Terraform Cloud or Terraform Enterprise API

Using the Terraform Cloud UI

A workspace’s remote state sharing setting may be altered in the Terraform Cloud or Terraform Enterprise UI by using the following method.

1. Navigate to the workspace within the Terraform Cloud or Terraform Enterprise UI.
2. From within the workspace, click on Settings and then General
3. Towards the bottom of the page, locate the Share with all workspaces in this organization selector.
4. If it is desired to share the state with all workspaces within the same organization, enable the selector. If only selected workspaces, or no state sharing is desirable, select Share with specific workspaces .
5. If only selected workspaces are desired, once the toggle has be set to Share with specific workspaces, select the workspace(s) from the drop down. Workspaces may be searched for by beginning to type their name. If no workspace sharing is required, do not select any workspaces from the drop down list.
6. Click Save settings.

Using the tfe provider

When using the tfe provider to manage workspaces and their settings, the remote state sharing option may be adjusted by altering the Terraform configuration. In order to adjust this setting, version 0.25.0 or later of the tfe provider must be used.

If the tfe provider was not previously used to manage workspaces, the configuration must be defined, and then terraform import used in order to import the existing workspace data into the Terraform state file.

1. Navigate to the Terraform configuration that manages the workspace.

2. In the tfe_workspace resource that manages a given workspace, add one of the following arguments to define a workspace’s state sharing setting.

   • global_remote_state (bool): Whether the workspace’s state data should be accessible by all other workspaces within the same organization. If this is set to false, only the workspaces in the remote_state_consumer_ids argument may access the workspace’s state date.
   • remote_state_consumer_ids (set(string)): The set of workspaces that may access the target workspace’s state data. This value should only be set of global_remote_state is set to false. The values expected are the a set of workspace IDs, which may be collected from either the workspace’s General settings or in the data.id value of the response from the Show a workspace API endpoint. If no workspace IDs are specified, the workspace will now allow sharing of it’s state data with any other workspace.

3. After updating the Terraform configuration, follow the steps for the run method that is used (UI, API, or CLI) to apply the changes.

Using the API

The Terraform Cloud and Terraform Enterprise workspaces API endpoint has been updated to allow for altering a workspace’s remote state sharing setting as well. Doing so may require the use of multiple API endpoints, which are covered below.

Creating a workspace

When creating a new workspace using the create a workspace API endpoint, the data.attributes.global-remote-state attribute may be included in the payload in order to specify a workspace’s state sharing setting. This value expects a boolean and defaults to false (state date is not shared with any other workspaces). Settings this value to true will enable all other workspaces within the organization to access the newly created workspace’s state data.

A sample of a payload for creating a workspace without a VCS repository may appears as follows.

{
  "data": {
    "type": "workspaces",
    "attributes": {
      "name": "remote-state-sharing",
      "global-remote-state": true
    }
  }
}

The request to the API endpoint itself would then appear as follows.

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/organizations/$ORGANIZATION/workspaces

Updating an existing workspace

For existing workspaces, the update a workspace API endpoint may be used to the state sharing setting. As with creating a workspace above, the data.attributes.global-remote-state may be passed in the payload to alter the setting.

Rather than defaulting to false, as the create a workspace API endpoint does, this value defaults to the previous setting so as to not inadvertently modify this setting when updating other values. All other values may be omitted from the payload, as the values default to the previously set value. A sample payload may appear as follows.

{
  "data": {
    "type": "workspaces",
    "attributes": {
      "global-remote-state": true
    }
  }
}

The request itself may go to one of two different endpoints, as follows.

PATCH /organizations/:organization_name/workspaces/:name:

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PATCH \
  --data @payload.json \
  https://app.terraform.io/api/v2/organizations/$ORGANIZATION/workspaces/$WORKSPACE_NAME

PATCH /workspaces/:workspace_id:

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PATCH \
  --data @payload.json \
  https://app.terraform.io/api/v2/workspaces/$WORKSPACE_ID

Adding remote state consumers

To add additional workspaces to the list of allowed state consumers, the add remote state consumers API endpoint may be used. This API endpoint may only be used against workspaces that have data.attributes.global-remote-state set to true.

The payload for the API call expects a top level data list with any number of objects containing data[].type set to "workspaces" and data[].id matching the ID of an existing workspace. The value expected in each of the data[].id attributes are workspace IDs, which may be collected from either the workspace’s general settings or in the data.id value of the response from the show a workspace API endpoint.

A sample payload may appear as follows.

{
  "data": [
    {
      "type": "workspaces",
      "id": "ws-7aiqKYf6ejMFdtWS"
    },
    {
      "type": "workspaces",
      "id": "ws-7aiqKYf662MFdAHY"
    }
  ]
}

The request itself should be formatted as follows.

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/workspaces/$WORKSPACE_ID/relationships/remote-state-consumers

Replacing remote state consumers

Similar to the option of adding remote state consumers below, the replace remote state consumers API endpoint allows for adding remote state consumers to a target workspace’s configuration. This endpoint, however, replaces the existing list of workspaces with exactly what is passed in the payload.

The payload for this endpoint is identical to the payload used to add remote state consumers above, however, the request should be made as follows.

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PATCH \
  --data @payload.json \
  https://app.terraform.io/api/v2/workspaces/$WORKSPACE_ID/relationships/remote-state-consumers

Deleting remote state consumers

In addition to adding and replacing consumers, and API endpoint has been added to delete remote state consumers. This endpoint will remove the specified workspaces from the list of workspaces allowed to access the target workspace’s state data. The payload itself uses the same format as is used for adding or replacing consumers, however, the request should be updated as follows.

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  --data @payload.json \
  https://app.terraform.io/api/v2/workspaces/$WORKSPACE_ID/relationships/remote-state-consumers

Additional Information

• Accessing State from Other Workspaces documentation
• The terraform_remote_state Data Source documentation
• Remote State Sharing workspace setting documentation