Local Backend and State Locking

What it is

A backend decides where Terraform stores its state. If a configuration has no backend block and no cloud block, Terraform uses the local backend, which writes state as a file on the disk of the machine running Terraform.

State locking protects that file. While an operation that could write state is running, Terraform holds a lock so a second run cannot change the same state at the same time and corrupt it.

How it works

The local backend

With no backend configured, the state file is terraform.tfstate in the root module directory. You can also declare the local backend explicitly to change the path.

terraform {
  backend "local" {
    path = "state/network.tfstate"
  }
}

When Terraform writes a new state, it keeps the previous version as terraform.tfstate.backup. The backup is a single earlier snapshot, not a full history.

CLI workspaces on the local backend

The local backend supports multiple CLI workspaces. The default workspace uses terraform.tfstate, and each extra workspace gets its own state file under terraform.tfstate.d/<workspace name>/ unless workspace_dir says otherwise.

terraform workspace new dev
terraform workspace list
terraform workspace select default

Each workspace is a separate state for the same configuration. The code is shared; the recorded resources are not.

Limits of the local backend

The local backend is simple and fine for one person learning or testing. It has clear limits for team work:

Because state can contain secrets, do not commit terraform.tfstate or its backup to version control. A remote backend with access control and encryption is the usual fix.

State locking

Locking happens automatically on all operations that could write state, such as terraform plan, terraform apply and terraform destroy. Terraform does not print a message when it takes the lock; it only reports status if acquiring the lock takes longer than expected.

Not every backend supports locking; each backend's documentation says whether it does. The local backend locks the file, the S3 backend locks with a lock file when use_lockfile = true, and HCP Terraform locks workspace state for you.

Force unlock

If Terraform crashes or loses its connection mid run, the lock can be left behind. The next run fails and shows the lock ID.

terraform force-unlock 6638c5b7-7d63-4ea5-8b2c-0f1e1d5b1a2e

Use it only to clear your own stuck lock. If you remove a lock that another person's run still holds, two writers can overwrite each other and corrupt the state.

How the exam asks about this

• "No backend block exists. Where does Terraform save state?" In terraform.tfstate in the root module directory, using the local backend.
• "A teammate's apply is running and you run terraform apply." Your run cannot acquire the lock and stops, or waits if you set a lock timeout.
• "A crashed run left the state locked." Run terraform force-unlock with the lock ID, after confirming no run is still active.