Manage Terraform state by storing it in a remote backend with locking, encrypting it, restricting access, and keeping it out of version control. State maps your configuration to real resources and can contain secret values in plaintext, so protect it like a credential store.
What is Terraform state?
HashiCorp's documentation says Terraform stores state about your managed infrastructure and configuration. It links each resource in your configuration to the remote object it manages, and Terraform uses that link to decide what to create, update or delete. The documentation says Terraform cannot function without state.
By default, state lives in a local terraform.tfstate file with a backup beside it. That is fine for a first experiment. It fails for teams: the file can be lost, and two people can work from different copies.
Why does state need a remote backend?
A remote backend gives one shared copy and, if the backend supports it, locking. Locking happens automatically during any operation that could write state, which prevents two people from corrupting it. If Terraform cannot get the lock, it stops. The documentation says locking only works when the backend supports it, so check yours.
Skipping locks with -lock=false is discouraged. The force-unlock command exists for a lock left behind by a failed run, and the documentation warns to be very careful: forcing an unlock while someone else holds it can create multiple writers. Use it only to release your own stale lock.
Is it safe to put state in Git?
No. HashiCorp advises against storing state in version control or in any system without locking and secure access control. There is a second reason. Secret values that enter your configuration end up in state and plan files. The sensitive argument hides values from command output and the HCP Terraform interface, but they are still stored, and terraform output with the json or raw option prints them in plain text.
Constructed example: a database password passed as a variable is created with the database. Months later, someone with read access to the bucket holding state can read that password. Nobody ever committed it to Git, yet it sits in a file that was widely readable.
How do you reduce what lands in state?
The documentation recommends treating state as sensitive data, storing it remotely, encrypting it at rest, restricting access, and using audit logs. It notes encryption depends on the backend: the S3 backend supports an encrypt option, and the Google Cloud Storage backend supports customer-supplied or customer-managed keys.
To avoid storing a value at all, use ephemeral variables, the ephemeral block, or write-only arguments. Terraform omits ephemeral values from state and plan files entirely.
Should you edit state by hand?
No. State is JSON, but the documentation says not to edit it directly. Use the terraform state commands. When you import an object or run terraform state rm, you take on responsibility for the one to one mapping between resource instances and remote objects.
If another tool needs data from state, use terraform output -json or terraform show -json after a successful apply. The state format can change between versions, so parsing the file directly means ongoing maintenance.
How to check or apply this
- Find every state file: search repositories and laptops for
terraform.tfstate. - Move each to a remote backend that supports locking.
- Turn on encryption at rest and restrict read access to people and pipelines that need it.
- Enable access logging on the storage.
- Remove state files and backups from Git, and add them to the ignore list. Rotate any secret that was ever exposed.
- Replace secret variables with ephemeral values where your provider supports them.
- Run applies from CI so one identity writes state.
Quick check
Does marking a variable sensitive keep it out of state?
No. It hides the value from command output and the HCP Terraform interface, but the value is still stored in state and plan files.
When is force-unlock acceptable?
Only to release a lock you hold after an automatic unlock failed. Forcing someone else's lock can cause several writers.
Sources
Last reviewed: 18 October 2026.
