> ## Documentation Index
> Fetch the complete documentation index at: https://docs.envzero.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Remote backend

> Store and manage Terraform state with env zero remote backend, including state locking, versioning, deployment correlation, and access control.

Terraform uses persisted state data to keep track of the resources it manages. Most non-trivial Terraform configurations use a [backend](https://www.terraform.io/language/settings/backends/configuration) to store the state remotely. This lets multiple people access the state data and work together on that collection of infrastructure resources.

Terraform offers several state storage options, of which env zero supports [Remote Backend](https://www.terraform.io/language/settings/backends/remote), which has some great benefits such as:

* **No underlying infrastructure setup and management** - env zero takes care of the setup as opposed to other approaches, where you need to do all the setup and management yourself (for example, [S3 Backend](https://www.terraform.io/language/settings/backends/s3) requires you to create an S3 Bucket and an optional DynamoDB Table for locking beforehand).
* **Security** - env zero stores the state securely and assures only you can access it.
* **State consistency** - Remote Backends assure that users won't overwrite each other's state with a locking mechanism and that they receive the most recent state on every Terraform operation
* **[Remote plans](https://docs.envzero.com/guides/admin-guide/remote-backend/remote-plan.md)** - By providing the Remote Backend configuration and successful login, users can run `terraform plan` locally, which will trigger a remote plan in env zero. The remote plan will use the shared state and variables set for the env zero environment.

Using env zero's Remote Backend has additional advantages:

* **No Terraform Backend configuration when running inside env zero** - You don't have to provide any type of configuration; deploy your code as is, and env zero will automatically configure it to use the Remote Backend.
* **States UI** - View the current version of your current state and all previous versions.
* **Correlation of Deployment to State** - Identify which deployment caused a specific change to your state.
* **[State Access Control](https://docs.envzero.com/guides/admin-guide/remote-backend/state-access-control.md)** - Specify which environments should be able to access an environment's state in env zero.

> [!WARNING]
>
> **Reusing Workspace Name**
>
> Terraform uses the workspace name to distinguish between one state and another.
>
> When using a remote backend in env zero, the workspace name identifies that environment's state.
>
> Therefore, if a remote backend environment is created and then [marked as inactive](https://docs.envzero.com/guides/admin-guide/environments.md#mark-an-environment-as-inactive), and another remote backend environment is created with the same workspace name, it would inherit the first environment's state.
>
> Marking an environment as inactive stops reserving its workspace name, so env zero no longer rejects the new environment as a duplicate. It does not clear the state that name points at. Reuse a workspace name only when you intend the new environment to adopt the old state.

## Use Remote Backend in a New Environment

To enable Remote Backend in a new environment:

* Create a new [Environment](https://docs.envzero.com/guides/admin-guide/environments/setting-up-a-new-environment.md)
  * Check the **Enable Remote State** checkbox
  * Enter a **Workspace Name**

Here's what it looks like for environments based on a predefined template:

![New environment form for a template-based environment with Enable Remote State checkbox and Workspace Name field](https://mintcdn.com/envzero-b61043c8/pcx_nh6zT3at7dYL/images/guides/admin-guide/9aa75ce-screen_shot_2022-09-14_at_16.png?fit=max\&auto=format\&n=pcx_nh6zT3at7dYL\&q=85\&s=306942b6408f26aa229af38c87dac8cf)

Here's what it looks like for environments based on a direct VCS integration:

![New environment form for a direct VCS integration with Enable Remote State checkbox and Workspace Name field](https://mintcdn.com/envzero-b61043c8/pcx_nh6zT3at7dYL/images/guides/admin-guide/860732b-screen_shot_2022-09-14_at_16.png?fit=max\&auto=format\&n=pcx_nh6zT3at7dYL\&q=85\&s=675731335a1c57b772dad0c298a3863f)

> [!NOTE]
>
> **Workspace Name Restrictions**
>
> env zero enforces that a Workspace Name must be unique among all Remote Backend environments in the Organization. The Terraform configuration for the Remote Backend consists of Organization ID and Workspace Name. Therefore, we have this limitation to block possible state conflicts.

> [!NOTE]
>
> **Force Remote Backend**
>
> You can force all new Terraform environments in a project to be created with a Remote Backend. See [Force remote backend](https://docs.envzero.com/guides/policies-governance/force-remote-backend.md) for more info.

> [!WARNING]
>
> **Terragrunt**
>
> Currently, env zero does not support using the Remote Backend with Terragrunt. Let us know (via chat or email) if you would like us to add support for this.

### Enable Remote Backend on a workflow sub-environment

A workflow sub-environment takes the workflow's **Use env zero Remote Backend** setting once, when env zero creates it, and only if its template is Terraform or OpenTofu. Sub-environments have no **Settings** tab, so to enable Remote Backend on an existing sub-environment, use the [Update Environment](https://docs.envzero.com/api-reference/environments/update-environment.md) API.

> [!WARNING]
>
> **Required permission**
>
> Enabling Remote Backend requires the **Edit Environment Settings** permission on the sub-environment.

Before you start, you need:

* An [API key](https://docs.envzero.com/guides/admin-guide/user-role-and-team-management/api-keys.md) ID and secret
* A sub-environment whose template is Terraform or OpenTofu
* If the sub-environment was deployed before, the **Run Tasks** permission, to migrate its state. No built-in project or environment role includes it; grant it with a [custom role](https://docs.envzero.com/guides/admin-guide/user-role-and-team-management/custom-roles.md).

**1. Get the sub-environment ID**

Read it from the workflow environment with the [Get Environment](https://docs.envzero.com/api-reference/environments/get-environment.md) API. `<ALIAS>` is the sub-environment's key under `environments` in `env0.workflow.yaml`.

```bash theme={null}
curl -s -u "<API_KEY_ID>:<API_KEY_SECRET>" \
  "https://api.env0.com/environments/<WORKFLOW_ENVIRONMENT_ID>" \
  | jq -r '.latestDeploymentLog.workflowFile.environments["<ALIAS>"].environmentId'
```

**2. Enable Remote Backend**

```bash theme={null}
curl -X PUT "https://api.env0.com/environments/<SUB_ENVIRONMENT_ID>" \
  -u "<API_KEY_ID>:<API_KEY_SECRET>" \
  -H "Content-Type: application/json" \
  -d '{"isRemoteBackend": true}'
```

The response is the updated environment, with `"isRemoteBackend": true`. The setting applies from the sub-environment's next deployment.

**3. Migrate existing state**

If the sub-environment was deployed before, env zero doesn't copy its existing state into the Remote Backend. Migrate it before the next deployment, or that deployment either fails or plans to re-create the sub-environment's resources.

Run a task on the sub-environment that sets the environment variable `TF_CLI_ARGS_init` to `-migrate-state -force-copy` (`"type": 0` marks it as an environment variable). The task's `init` step copies the state into the Remote Backend, and `terraform state list` prints the migrated resources. For OpenTofu, use `tofu state list`.

```bash theme={null}
curl -X POST "https://api.env0.com/environments/<SUB_ENVIRONMENT_ID>/deployments" \
  -u "<API_KEY_ID>:<API_KEY_SECRET>" \
  -H "Content-Type: application/json" \
  -d '{"deploymentType": "task", "taskPayload": "terraform state list", "configurationChanges": [{"name": "TF_CLI_ARGS_init", "value": "-migrate-state -force-copy", "type": 0, "scope": "DEPLOYMENT"}]}'
```

Running `terraform init -migrate-state` as the task command doesn't work. The task's own `init` step runs first and fails with `Error asking for state migration action: input is disabled`.

env zero saves `TF_CLI_ARGS_init` on the sub-environment. After the task succeeds, find the variable's ID and delete it:

```bash theme={null}
curl -s -u "<API_KEY_ID>:<API_KEY_SECRET>" \
  "https://api.env0.com/configuration?environmentId=<SUB_ENVIRONMENT_ID>&organizationId=<ORGANIZATION_ID>" \
  | jq -r '.[] | select(.name == "TF_CLI_ARGS_init") | .id'

curl -X DELETE "https://api.env0.com/configuration/<VARIABLE_ID>" \
  -u "<API_KEY_ID>:<API_KEY_SECRET>"
```

If the sub-environment's code configures its own backend, see [Migrating State](https://docs.envzero.com/guides/admin-guide/remote-backend/state-migration.md).

* Redeploying the workflow doesn't change the setting.
* If another Remote Backend environment in the organization uses the same workspace name, the call returns `409` with `Workspace name "<WORKSPACE_NAME>" is taken by remote backend environment`. You can't change a sub-environment's workspace name after it's created, so give each sub-environment its own `workspace` in the [workflow file](https://docs.envzero.com/guides/admin-guide/workflows/workflow-file-reference.md#sub-environment-properties) before it's first deployed.

### Viewing & Downloading State Versions

After a successful deployment with Remote Backend enabled, the **States** tab lists all state versions, newest first.

![States tab listing all state versions in reverse chronological order after a successful deployment](https://mintcdn.com/envzero-b61043c8/pcx_nh6zT3at7dYL/images/guides/admin-guide/cd0e876-screenshot_2022-10-25_at_14.png?fit=max\&auto=format\&n=pcx_nh6zT3at7dYL\&q=85\&s=4273fdbd678d5bcea9733f286b456106)

To download a state version, hover on the desired version. A Download button should appear.

![State version row on hover revealing the Download button to save the state file](https://mintcdn.com/envzero-b61043c8/pcx_nh6zT3at7dYL/images/guides/admin-guide/dd6c73f-screenshot_2022-10-25_at_14.png?fit=max\&auto=format\&n=pcx_nh6zT3at7dYL\&q=85\&s=32cdf04a952047d201331f930d3ba4bd)

Clicking it should initiate a file download.

> [!NOTE]
>
> **Note**
>
> Bigger state files may take a few moments to start downloading

If the state version was created by env zero  (i.e., not locally), there would also be a quick access link to its relevant deployment log.

![State version row showing a quick access link to the deployment log that created this state](https://mintcdn.com/envzero-b61043c8/BZYthPtvpSdQtcKJ/images/guides/admin-guide/1ea47d7-screenshot_2022-10-25_at_14.png?fit=max\&auto=format\&n=BZYthPtvpSdQtcKJ\&q=85\&s=0aa7117458706728fe509bc7869e0167)

### Release a Locked State

When working with Terraform or OpenTofu, you might encounter a scenario where the **state becomes locked**. This usually occurs when a previous deployment did not complete successfully - due to an error, crash, or manual interruption. In such cases, the workspace retains a state lock to prevent conflicting changes during concurrent deployments.

To resolve this issue, you can **manually release** the state lock. This action clears the lock, allowing you to re-run your deployment safely.

#### How to release a locked state

* Navigate to the STATES tab for the affected environment.
* If the workspace is locked, you’ll see a warning along with a **Force Release** button.
* Click the **Force Release** button to clear the lock

> [!WARNING]
>
> **Important**
>
> Only use force unlock when you're certain that no other deployments are currently running. Forcing unlock during an active deployment can corrupt your infrastructure state.

![States tab with a locked workspace warning and the Force Release button to clear the state lock](https://mintcdn.com/envzero-b61043c8/pcx_nh6zT3at7dYL/images/guides/admin-guide/4dbfd89cd07d3a64c29d69b06964b0bf15cdc73e1924cf692430b2f7d540aee9-image.png?fit=max\&auto=format\&n=pcx_nh6zT3at7dYL\&q=85\&s=8488a71272398377f2c7af8e08d4e11a)

### Using the Remote Backend Locally

Please check out this guide: [Using the Remote Backend on your local machine](https://docs.envzero.com/guides/admin-guide/remote-backend/login.md)

## Further reading

* [A guide to the Terraform state file](https://www.envzero.com/blog/a-guide-to-the-terraform-state-file)
* [Terraform backend configuration: local and remote options](https://www.envzero.com/blog/a-guide-to-local-and-remote-backends-in-terraform)
* [Manage Terraform remote state with a remote backend](https://www.envzero.com/blog/terraform-remote-state-using-a-remote-backend)

## Next steps

To keep remote backend state in your own AWS S3 bucket, [set up self-hosted remote state](https://docs.envzero.com/guides/admin-guide/remote-backend/self-hosted-remote-state.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.