English for Terraform State

Most confusing Terraform incidents trace back to state — the file that tracks what Terraform believes exists — getting out of sync with what’s actually deployed, and the vocabulary here (drift, locking, import) is exactly what lets a team diagnose that gap instead of just re-running apply and hoping.

Key Vocabulary

State file — the file (typically terraform.tfstate) where Terraform records the real-world resources it’s created and their current attributes, used to compute the diff for every plan. “The state file says this bucket exists with versioning enabled, so any plan will compare the actual bucket against that recorded state, not against the raw config alone.”

Drift — a mismatch between what the state file records and what actually exists in the real infrastructure, typically caused by manual changes made outside of Terraform. “Someone changed the security group manually in the console, so Terraform’s state now shows drift — the next plan will want to revert that change back to match the config.”

State locking — a mechanism that prevents two people or CI runs from modifying the state file simultaneously, avoiding corruption or conflicting concurrent changes. “The apply failed immediately with a lock error — someone else’s plan was already holding the state lock, so ours correctly refused to run concurrently.”

Import — bringing an existing resource, created outside of Terraform, under Terraform’s management by adding it to the state file without recreating it. “We imported the manually created database instance into state so Terraform would stop trying to create a duplicate on every plan.”

Remote backend — a shared storage location (S3, Terraform Cloud, etc.) for the state file, used instead of a local file so a team can collaborate on the same infrastructure without stepping on each other’s state. “We moved state to a remote backend with locking enabled specifically so two engineers running apply at the same time wouldn’t corrupt each other’s changes.”

Common Phrases

• “Is this drift, or did the config actually change?”
• “Is the state locked right now — is someone else running an apply?”
• “Do we need to import this, or was it already created through Terraform?”
• “Is state stored remotely, or is this still a local state file?”
• “What does the plan say the drift actually is before we apply anything?”

Example Sentences

Explaining an unexpected plan output: “The plan wants to delete and recreate this resource, which isn’t what we intended — it’s drift. Someone modified a tag manually outside of Terraform, and now the state file and reality disagree.”

Diagnosing a stuck apply in an incident: “The apply is hanging because state is locked from a run that crashed without releasing the lock — we’ll need to force-unlock it carefully after confirming no other apply is genuinely in progress.”

Describing an onboarding step for legacy infrastructure: “Before we can manage this database with Terraform, we need to import it into state first — otherwise Terraform will try to create a brand-new one and either fail or duplicate it.”

Professional Tips

• Say drift, not “the plan looks weird,” when state and reality disagree — naming it precisely signals the fix is reconciling state, not just rerunning apply and hoping it goes away.
• Always use a remote backend with state locking for any team-shared infrastructure — a local state file is one of the most common causes of destructive concurrent-apply incidents.
• Recommend import explicitly for any resource created manually that needs to come under Terraform management — recreating it instead of importing it risks real downtime.
• Read the plan’s diff carefully before applying when drift is suspected — Terraform doesn’t distinguish “someone changed this on purpose” from “this needs to be reverted,” so a human has to make that call.

Practice Exercise

1. Write a sentence explaining what drift is and a common cause of it.
2. Explain why state locking matters for a team working on the same infrastructure.
3. Describe when you’d use terraform import instead of just running apply.

In Practice: Navigating Nuances for Non-Native Speakers

Let’s face it – technical jargon can be tricky regardless of your native language. When communicating about complex systems like Terraform and its state files, subtle differences in phrasing can dramatically impact clarity and acceptance within a team. For developers who aren’t entirely fluent in English, understanding the intent behind certain terms is just as crucial as knowing their literal definitions. It’s not just about saying “drift” – it’s about conveying the seriousness of the situation.

Consider this scenario: you’ve been reviewing a Terraform PR that introduces a new database server. The author includes a commit message stating, “Applied changes to DB.” While technically accurate, it lacks context and doesn’t acknowledge potential issues. A more professional approach would be, “Updated infrastructure with a new PostgreSQL instance. This change introduces drift in the state file; we need to investigate potential conflicts and ensure proper locking is configured to prevent future inconsistencies.” Notice the shift? The added words highlight the risk associated with the change – a risk that’s often unspoken but critically important for collaborative infrastructure work. Similarly, if you’re explaining a Terraform configuration to someone unfamiliar with the project, stating “This will modify the state” isn’t enough. Instead, try “These changes are designed to drive divergence from our baseline state, requiring careful consideration of locking and potential rollback strategies.” Understanding terms like ‘divergence’, ‘drift’ and ‘baseline’ – and how they relate to maintaining a consistent Terraform state – is key.

Another common situation arises in Slack discussions when troubleshooting issues. Someone might frantically type: “State broken! Can’t apply!” While understandable, it doesn’t provide actionable information. A more helpful response would be, “Okay, let’s investigate the state drift. Can you share the diff between the current state and our baseline? We need to identify the source of the divergence to properly resolve this.” Using phrases like “source of divergence” clearly frames the problem as a systematic issue needing diagnosis, not just a random ‘broken’ state. This also subtly emphasizes the importance of understanding why the drift occurred – was it an unintentional change, or a deliberate modification that wasn’t properly tracked?

Finally, when writing PR descriptions, it’s vital to be precise about how changes affect the Terraform state. Instead of simply saying “Added resources,” consider “Introduced three new EC2 instances and updated the associated security group rules. This will result in state divergence requiring synchronization and a review of our locking strategy.” The inclusion of phrases like ‘state divergence’, ‘synchronization’ and ‘locking strategy’ demonstrates an awareness of Terraform’s core principles and helps prevent misunderstandings down the line.

Here’s an example of how you might use terraform apply to check for potential state conflicts:

terraform plan -out=temp_plan.tfplan
terraform show tfplan temp_plan.tfplan | grep "Conflict"

This command generates a temporary plan and then specifically searches the output for any indications of conflicts, a clear signal that your state is diverging from your intended configuration. Remember, precise language builds trust and reduces ambiguity in collaborative infrastructure work.