Terraform state: remote backends and locking for small teams
Short answer: Terraform keeps a state file that records which real cloud resources belong to your configuration. By default it's a local file, which is fine for one person experimenting but risky for a team: it can be lost, it can go out of date, and it contains secrets in plain text. Move it to a remote backend with locking switched on, restrict who can read it, keep versions so you can recover, and make sure only one apply can run at a time.
What the state file actually does
Terraform's documentation explains that state is how Terraform maps real-world resources to your configuration, keeps track of metadata and improves performance on larger setups. When you run plan, Terraform compares three things: your configuration, the state and what actually exists in your cloud account.
If the state is missing or stale, Terraform's picture of the world is wrong. It might try to create a database that already exists or miss that a server was changed. That's why where you keep state matters as much as the configuration itself.
By default, Terraform stores state in a local file called terraform.tfstate, with the previous version in terraform.tfstate.backup. The docs note this needs no setup but limits collaboration and risks losing work. For a small business running its app on a cloud provider, the usual failure is simple: the state lives on one developer's laptop, the laptop is replaced, and nobody can safely change the infrastructure any more.
Treat state as a secret
Terraform's guidance on sensitive data is blunt: state is a plaintext file that includes any secret values in your configuration, such as database passwords generated by Terraform. It tells you to treat the state file as sensitive and keep it out of Git.
In practice:
- Add
*.tfstateand*.tfstate.*to.gitignorebefore the first commit. - Store state where access is controlled and encrypted at rest.
- Give read access only to the people and pipelines that run Terraform.
- Where possible, keep long-lived secrets in a secrets manager and reference them, rather than having Terraform generate and hold them.
If a state file has ever been committed to a repository, assume the secrets in it are exposed and rotate them.
Choosing a remote backend
A backend is where Terraform stores state. Common choices for small teams:
| Backend | Good fit when | Locking |
|---|---|---|
| Cloud object storage (for example, an S3 bucket) | You already run on that cloud | Supported, check the backend docs |
| A managed Terraform service | You want runs, history and access control in one place | Built in |
| Your CI system's state storage, where offered | Terraform only runs from CI | Varies |
Pick the one closest to where your infrastructure already lives, so access control follows the accounts you already manage.
For the S3 backend, HashiCorp's documentation is specific on two points as of late 2026. First, S3 now supports state locking itself when you set use_lockfile = true; the older DynamoDB-based locking is marked deprecated and due for removal in a future version. Second, it strongly recommends switching on bucket versioning, so you can recover state if it's deleted or corrupted.
A minimal configuration looks like this, with placeholder names:
terraform {
backend "s3" {
bucket = "example-terraform-state"
key = "shop-app/production.tfstate"
region = "eu-west-2"
encrypt = true
use_lockfile = true
}
}
After adding the block, terraform init offers to copy your existing local state into the new backend. Do that once, check that terraform plan shows no unexpected changes, then delete the local copy.
Why locking matters
Without locking, two people, or a person and a CI job, can run apply at the same moment. Both read the same starting state, both make changes and the last one to write wins, quietly dropping the other's record of what it created. You end up with resources Terraform no longer knows about.
With locking, the second run waits or fails with a lock error. Terraform's locking page says this happens automatically for backends that support it.
It also documents terraform force-unlock for when a lock is left behind, for example after a crashed run. Use it carefully: the docs warn that unlocking while someone else really holds the lock can cause multiple writers. Before forcing, confirm the run that held it has actually stopped. The command needs the lock ID Terraform printed, which acts as a safeguard against unlocking the wrong lock.
Split state so mistakes stay small
One state file for everything means every plan touches everything, and one bad change can affect production and staging together. A simpler, safer layout for a small business:
- One state per environment, such as
stagingandproduction, using different keys or folders. - Separate state for long-lived foundations, such as networking and DNS, from frequently changed app resources.
- Read shared values, like a network ID, through outputs rather than copying them by hand.
Smaller states run faster and limit the blast radius of an error.
Day-to-day habits that prevent trouble
- Run Terraform from one place. Ideally, changes go through CI on merge, with people running
planlocally only. - Review the plan. Treat
planoutput like a code review. Destroy-and-recreate on a database deserves a second look. - Don't edit state by hand. Use Terraform's own commands for moving or removing resources from state.
- Keep versions. Bucket versioning or the managed service's history is your undo button.
A worked example
Imagine a hypothetical Manchester events company whose app runs on one cloud account. Its Terraform state sat on a contractor's laptop. When the contractor left, the team found the state was weeks out of date. They imported the existing resources, moved state to a versioned, encrypted bucket with use_lockfile switched on, split staging from production and made CI the only place apply runs. The next time two changes landed together, the second CI job simply waited for the lock.
FAQ
Can I keep Terraform state in Git if the repository is private?
It's not recommended. State holds secrets in plain text and Git keeps every old version forever. A private repository still exposes those secrets to everyone with access.
What happens if I lose the state file?
Terraform no longer knows what it manages. You can import existing resources back into a new state, but it's slow and error-prone. Versioned remote state avoids this.
Is DynamoDB still needed for S3 locking?
Not for new setups, according to HashiCorp's S3 backend docs, which describe use_lockfile and mark DynamoDB locking as deprecated. Check the docs for your Terraform version.
How many state files should a small team have?
Usually one per environment, plus one for shared foundations. Split further only when plans get slow or risky.
If your infrastructure state lives on one laptop or nobody is sure where it is, let us help you move it somewhere safe.