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, andapply.Make sure you have access to a Harness account with permission to create registries and connectors.
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:
In Artifact Registry, select Registries.
Select + Create Registry.
Specify the Registry name.
Optionally, add a Description.
Choose visibility between Public and Private. The default is Private.
Select Terraform Backend as the Registry type.
Click Save.
Select Create to finalize.
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.
In your Terraform Backend Artifact, select Set Up Client.
Select Generate Token.
Select an Expiration for the token:
30 Days
90 Days
180 Days
Custom
Copy the token. You use it in the following steps in place of
<IDENTITY_TOKEN>.
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:
In a new directory with no existing
.terraformdirectory or local state file, runterraform initagainst the backend block you configured.Run
terraform apply, and confirm the workspace address appears in the Terraform Backend registry in Harness, along with its lock status and version history.Run
terraform state listto 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.
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
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?