Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.
Artifact RegistryTerraform

Terraform Backend

Store and lock Terraform and OpenTofu state in a Terraform Backend registry.

Use a Terraform Backend registry to store, lock, and version Terraform and OpenTofu state. The registry implements the standard HTTP backend, so terraform and tofu read and write .tfstate 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. To use an Infrastructure as Code Management (IaCM) workspace to own the state instead, go to CLI integration.

What you will learn from this topic

By the end of this quickstart guide, you will be able 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.

Registry permissions

Create the registry in the target project. To assign roles, go to RBAC and permissions.

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

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, perform the following steps:

  1. In Artifact Registry, select Registries.

  2. Select + Create Registry.

  3. Specify the Registry name.

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.

  1. Optionally, add a Description.

  2. Choose visibility between Public and Private. The default is Private.

  3. Select Terraform Backend as the Registry type.

  4. Click Save.

  5. Select Create to finalize.

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.

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.

Terraform Backend client setup

In your Terraform Backend Artifact, select the registry, then select Set Up 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 Set Up 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>.

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.

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, and password is the identity token from Generate Token. OpenTofu uses the same block; substitute tofu for terraform.

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.

Setup verification

To verify your setup, perform the following steps:

  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 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.

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

Troubleshooting

`terraform init` or `apply` fails with `401` or `403` against the HTTP backend

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

`terraform init` fails because the lock method is not supported

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.

Apply stops with `HTTP 423 Locked`

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.

State write returns `HTTP 422`

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.

Terraform reports `HTTP 403` on a workspace that used to exist

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.

State write returns `HTTP 413`

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

Next steps

  • To publish Terraform modules and providers instead of state, go to Terraform.

  • To control who can read, write, and force-unlock state in your registry, go to RBAC and permissions.

  • To use an IaCM workspace to own the state instead of a backend block, go to CLI integration.

Last updated

Was this helpful?