> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/3.0/setup/terraform-backend.md).

# Terraform Backend

Terraform Backend - store state files in Harness Artifacts

Use a **Terraform Backend** registry to store, lock, and version Terraform state files using the HTTP backend protocol. The registry implements this protocol natively, so `terraform` and `tofu` read and write `.tfstate` files without a custom plugin.

A Terraform Backend registry is a different registry type from a Terraform registry. To publish modules and providers, go to [Terraform](https://developer.harness.io/artifact-registry/3.0/setup/terraform.md). To use an Infrastructure as Code Management (IaCM) workspace to own the state instead, go to [CLI integration](https://developer.harness.io/infrastructure-as-code-management/platform/workspaces/cli-integration).

## What you will learn from this topic

By the end of this guide, you will know how to:

* Create a Terraform Backend registry in Harness Artifacts.
* Configure a Terraform or OpenTofu workspace to read and write state through the registry.
* Review workspace locks and prior state versions in the registry.

## Before you begin

* Install Terraform CLI 1.0 or later, or OpenTofu CLI 1.6 or later, on the machine or pipeline that runs `init`, `plan`, and `apply`.
* Make sure you have access to a Harness account with permission to create registries and connectors.

{% hint style="info" %}
**Registry permissions**

Create the registry in the target project. To assign roles, go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md).

| Action                         | Permission required                                         |
| ------------------------------ | ----------------------------------------------------------- |
| Read state                     | Download (pull) permission                                  |
| Write state and acquire a lock | Upload (push) permission                                    |
| Delete state                   | Delete Artifact permission                                  |
| Force unlock                   | Artifact Registry Edit role or Artifact Registry Admin role |
| {% endhint %}                  |                                                             |

## Create a Terraform Backend Artifact

Create one Terraform Backend registry per project. The same registry can hold state for many environments, because each environment maps to a separate workspace address in the backend URL.

To create a Terraform Backend Artifact:

1. In Artifact Registry, select **Registries**.
2. Select **+ Create Registry**.
3. Specify the **Registry name**.

{% hint style="info" %}
**Registry name criteria**

The registry name must start with a letter, can only contain lowercase alphanumerics, `_`, `.`, and `-`, and must be unique to your Harness account.
{% endhint %}

4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **Terraform Backend** as the **Registry type**.
7. Click **Save**.
8. Select **Create** to finalize.

{% hint style="info" %}
**Registry type not listed**

Terraform Backend registries roll out by account. If **Terraform Backend** does not appear in the registry type list, contact [Harness Support](mailto:support@harness.io).
{% endhint %}

{% hint style="info" %}
**Local registry only**

A Terraform Backend registry does not support an upstream proxy or a virtual registry. Terraform and OpenTofu write state to it directly, instead of the registry fetching state from another registry.
{% endhint %}

## Terraform Backend client setup

In your Terraform Backend Artifact, select the registry, then select **Setup Client**. The dialog gives you an identity token and the backend block to add to your Terraform or OpenTofu configuration.

### Generate an identity token

An identity token serves as the password for authenticating with the registry.

1. In your Terraform Backend Artifact, select **Setup Client**.
2. Select **Generate Token**.
3. Select an **Expiration** for the token:
   * **30 Days**
   * **90 Days**
   * **180 Days**
   * **Custom**
4. Copy the token. You use it in the following steps in place of `<IDENTITY_TOKEN>`.

{% hint style="info" %}
**Token expiration**

The identity token stops working after the expiration you select. Generate a new token and update your client configuration before the current token expires.
{% endhint %}

### Configure the HTTP backend

Replace `<ACCOUNT_ID>`, `<REGISTRY_NAME>`, `<WORKSPACE>`, and `<IDENTITY_TOKEN>` with your own values.

**1. Configure the backend block and initialize**

Add the following to your Terraform configuration, then run `terraform init`. `lock_method` and `unlock_method` are required: the HTTP backend defaults to `LOCK` and `UNLOCK`, and this registry accepts `POST` and `DELETE` instead. `username` can be any non-empty value (the registry ignores it, but Terraform's HTTP backend requires one; the Setup Client panel uses your account email), and `password` is the identity token from **Generate Token**. OpenTofu uses the same block; substitute `tofu` for `terraform`.

{% code title="backend.tf" overflow="wrap" %}

```hcl
terraform {
  backend "http" {
    address        = "https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/terraform-backend/state/<WORKSPACE>"
    lock_address   = "https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/terraform-backend/state/<WORKSPACE>/lock"
    unlock_address = "https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/terraform-backend/state/<WORKSPACE>/lock"
    lock_method    = "POST"
    unlock_method  = "DELETE"
    username       = "harness"
    password       = "<IDENTITY_TOKEN>"
    retry_max      = 3
  }
}
```

{% endcode %}

The first lock or state write creates the workspace. You do not create the workspace in the registry UI first. A read before that first write returns `HTTP 404`, which Terraform treats as an empty state.

{% hint style="warning" %}
**State can contain sensitive values**

A `.tfstate` file can include resource addresses, endpoints, and other values you would not otherwise publish. Grant download permission only to the people and pipelines that run Terraform or OpenTofu. Do not commit `.tfstate`, or a backend block that contains the identity token, to version control.
{% endhint %}

## Setup verification

To verify your setup:

1. In a new directory with no existing `.terraform` directory or local state file, run `terraform init` against the backend block you configured.
2. Run `terraform apply`, and confirm the workspace address appears in the Terraform Backend registry in Harness, along with its lock status and version history.
3. Run `terraform state list` to confirm you can read back the state you wrote.

If a step fails, go to [Troubleshooting](#troubleshooting) to resolve common authentication and locking issues before you retry.

## Review locks and prior versions

The registry lists each workspace with its lock status, the lock holder, and when the lock was taken.

| Condition                  | Result                                                                                                                                                                                   |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Workspace is locked        | Apply stops with `HTTP 423` and the lock holder's identity. Wait for that process to finish. Locks do not expire on their own; Terraform releases the lock when apply finishes or fails. |
| Holder process has stopped | A user with the Artifact Registry Edit role or the Artifact Registry Admin role can select **Force Unlock**.                                                                             |
| Write succeeds             | The previous state is kept. Versions are identified by the Terraform `serial` in the state file.                                                                                         |
| Rollback                   | The selected version is copied forward as the new current state. The earlier version stays in the history.                                                                               |
| Delete the current version | Not supported. Roll back to an earlier version instead, or delete the workspace.                                                                                                         |
| Workspace is soft-deleted  | Terraform receives `HTTP 403`, so it does not treat the address as empty. Restore the workspace before you run Terraform again.                                                          |
| State larger than 50 MB    | The write is rejected with `HTTP 413`.                                                                                                                                                   |

To review state reads, writes, locks, unlocks, force unlocks, deletes, and rollbacks, go to [Audit Trail](https://developer.harness.io/harness-platform/use-harness-platform/governance/audit-trail/audit-trail).

{% hint style="danger" %}
**Force Unlock during a live apply**

Force-unlock only after you confirm the holder process has stopped. Clearing a lock while that apply is still running lets the next write replace state out from under it.
{% endhint %}

You can store state for every environment on one Terraform Backend registry, with locking and a record of each write.

## Troubleshooting

<details>

<summary>`terraform init` or `apply` fails with `401` or `403` against the HTTP backend</summary>

The identity token in the `password` field of `backend.tf` is missing, incorrect, or expired. Generate a new identity token from **Setup Client**, and update `backend.tf` before you rerun the command.

</details>

<details>

<summary>`terraform init` fails because the lock method is not supported</summary>

Set `lock_method` to `POST` and `unlock_method` to `DELETE` on both the lock and unlock addresses. The HTTP backend defaults to the `LOCK` and `UNLOCK` methods, and a Terraform Backend registry does not accept those methods.

</details>

<details>

<summary>Apply stops with `HTTP 423 Locked`</summary>

Another process holds the state lock. The response body names the holder. Wait for that apply to finish. If the holder process is gone, a user with the Artifact Registry Edit role or the Artifact Registry Admin role can select **Force Unlock** on the workspace.

</details>

<details>

<summary>State write returns `HTTP 422`</summary>

The registry rejected the write because the state serial is not newer than the copy already stored. Pull the current state and retry the apply. Do not overwrite the stored state with an older serial.

</details>

<details>

<summary>Terraform reports `HTTP 403` on a workspace that used to exist</summary>

The workspace is soft-deleted. A `403` stops Terraform from creating a new empty state and recreating infrastructure. Restore the workspace in Artifact Registry, then run Terraform again.

</details>

<details>

<summary>State write returns `HTTP 413`</summary>

The state file is larger than the 50 MB limit. Reduce the state, or split the configuration so each workspace stays under the limit.

</details>

## Next steps

* To publish Terraform modules and providers instead of state, go to [Terraform](https://developer.harness.io/artifact-registry/3.0/setup/terraform.md).
* To control who can read, write, and force-unlock state in your registry, go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md).
* To use an IaCM workspace to own the state instead of a backend block, go to [CLI integration](https://developer.harness.io/infrastructure-as-code-management/platform/workspaces/cli-integration).

{% @harness-feedback/feedback %}
