{"canonical_url":"https://engineer.company/glossary/terraform/","content_markdown":"# Terraform\n\n## What it is\n\nTerraform is HashiCorp's infrastructure as code tool. You describe cloud and\non-premises resources in plain text files, keep those files in version control,\nand Terraform works out which real objects to create, change or destroy so that\nthe running estate matches the files. The program itself is called as\n`terraform`, in lower case, which is how the name appears in every command and\nscript.\n\nThe language is declarative. HashiCorp's documentation describes it as\n“describing an intended goal rather than the steps to reach that goal”. A\nconfiguration says that a machine of a certain size exists in a certain\nnetwork; it does not list the API calls that would produce one. Files carry the\n`.tf` extension, and there is also a JSON-based variant with the `.tf.json`\nextension. The native syntax is defined in terms of a syntax called HCL and has\ntwo main building blocks: a block, which is a container for other content, and\nan argument, which assigns a value to a name.\n\nThree ideas carry the rest of the tool.\n\nProviders are plugins. The configuration tells Terraform which plugins to\ninstall, and `terraform init` finds, downloads and installs them. HashiCorp\nsays providers let Terraform work with virtually any platform or service that\nhas an accessible API, and the publicly available ones are listed on the\nTerraform Registry. A provider defines the resource types for its platform, so\nthe same core program can manage a DNS zone, a virtual machine and a monitoring\nrule at three different vendors.\n\nModules are directories. A module is a collection of `.tf` and `.tf.json` files\nkept together in one directory, and the root module is the working directory\nwhere Terraform is invoked.\n\nState is memory. Terraform keeps track of the real infrastructure in a state\nfile, which its introduction calls the source of truth for the environment. The\nstate maps each resource in the configuration to the real object it manages,\nalong with metadata. By default it is a local file named `terraform.tfstate`,\nand the previous version is kept beside it as `terraform.tfstate.backup`.\n\nThe licence has changed. On August 10, 2023, HashiCorp announced that it was\nmoving its source code licence from the Mozilla Public License 2.0 to the\nBusiness Source License 1.1 for all future releases of its products, while its\nAPIs, SDKs and almost all other libraries stay on MPL 2.0. OpenTofu describes\nitself as a Terraform fork, started by Gruntwork, Spacelift, Harness, Env0,\nScalr and others, and developed under the Linux Foundation's stewardship. Its\nrepository is published under MPL 2.0, and its site presents it as a\nreplacement for Terraform that keeps existing workflows and configurations.\n\n## Why it matters\n\nHashiCorp describes the core workflow in three steps. Write: you define\nresources, which may span several providers and services. Plan: Terraform works\nout what it would create, change or destroy and lays that out as an execution\nplan. Apply: once the plan is approved, it carries out those changes, ordering\nthem by the dependencies between resources, which it derives from a resource\ngraph.\n\nThe middle step is where most of the value sits. A plan is a preview that a\nperson who did not write the change can read before anything happens. A\nreviewer sees more than the diff of the files: they see the consequences, two\nresources created, one updated and, now and then, one destroyed that nobody\nmeant to touch. That last line is cheap to catch on a pull request and very\nexpensive to discover afterwards.\n\nThe second reason is reach. Because the knowledge of each platform lives in\nits provider, one language, one workflow and one set of review habits cover\nevery provider a team uses. A company on two clouds and a separate DNS host can\ndescribe all three in one repository and review all three the same way.\nMicrosoft's Bicep makes a different trade in its Azure Resource Manager workflow:\nit keeps no state file of its own, because Azure stores the deployment state.\nThat does not make Bicep an Azure-only language: its\n[extensions](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/bicep-extension)\nalso support resources outside Resource Manager, including Kubernetes and\nMicrosoft Graph.\n\nThe third reason is the state. Since Terraform records which real object\nbelongs to which block, it can tell an object it manages from one it has never\nseen, and it can compare the record with what is running. That record is also\nthe price of the tool. It has to live somewhere the whole team can reach, it\nneeds a lock so two runs do not write it at once, and it can contain secrets,\nso it needs access control as strict as theirs.\n\nThere are smaller costs as well. HCL is one more language to learn, and every\nprovider has its own resource types and quirks. Teams that build a product on\ntop of Terraform also have a licence to read: HashiCorp's licence FAQ has a\nquestion of its own on what counts as a competitive offering. OpenTofu offers\nthe same workflow under MPL 2.0.\n\n## What it looks like in practice\n\nHashiCorp's page on resource syntax uses this block as its example:\n\n```hcl\nresource \"aws_instance\" \"web\" {\n  ami           = \"ami-a1b2c3d4\"\n  instance_type = \"t2.micro\"\n}\n```\n\n`resource` is the block type and `aws_instance` is the resource type, defined\nby the AWS provider. `\"web\"` is the local name: Terraform uses that label to\ntrack the resource in its state file, and it has no effect on the settings of\nthe real machine. The two lines inside the block are arguments.\n\nThree commands take that file from text to a running machine:\n\n```sh\nterraform init\nterraform plan -out=tfplan\nterraform apply tfplan\n```\n\n`terraform init` prepares the working directory: it installs the provider\nplugins the configuration asks for and sets up the place where state will be\nkept. It is safe to run more than once, and its documentation says to commit\nthe dependency lock file to version control.\n\n`terraform plan -out=tfplan` computes the plan and writes it to a file in an\nopaque format. Planning does not apply the proposed infrastructure changes.\n`terraform apply tfplan` then performs the operations in that file without\nasking for confirmation, because HashiCorp treats passing a saved plan as the\napproval. For the same reason, the `-auto-approve` flag is ignored when a plan\nfile is given.\n\nIn a team the split falls naturally. A CI job runs the plan on the pull\nrequest and keeps the file, a person reads the plan as well as the diff, and\nafter the merge a second job applies that same file, so what runs is what was\nread. The apply documentation adds a condition that is easy to forget: make\nsure nobody can change the infrastructure outside the Terraform workflow, or\nthe plan describes a world that has already moved.\n\nOn this site, the [tech stack page](/tech-stack/) puts Terraform alongside\nAnsible: both write down what the machines should be, so that an environment can\nbe read instead of reconstructed. A portfolio entry applies the idea with a\ndifferent tool:\n[Azure infrastructure was provisioned as code](/portfolio/provisioned-azure-infrastructure-as-code/)\nin Bicep. The testing, staging and product environments are all built from one\nset of templates, and since the templates take parameters, adding or changing an\nenvironment is a pull request. Set beside this article, the entry shows the\ntrade from earlier. Bicep has no state file of its own because Azure holds the\nrecord, while Terraform keeps its own state and in return works across more than\none cloud.\n\n## Where it goes wrong\n\nMost Terraform accidents share a shape: the configuration is valid, the run\nsucceeds, and something real is gone or changed.\n\n**Renaming a resource destroys it.** Change the label `\"web\"` to `\"frontend\"`\nand the resource has a new address. HashiCorp's refactoring guide says that by\ndefault Terraform interprets a changed address as an instruction to destroy the\nexisting object and create a new one. For a disposable machine that costs a few\nminutes; for a database it costs the data. The fix is a `moved` block, which\nupdates the address without destroying anything:\n\n```hcl\nmoved {\n  from = aws_instance.web\n  to   = aws_instance.frontend\n}\n```\n\nKeep the block once it has done its work. HashiCorp strongly recommends\nretaining historical `moved` blocks and states that removing one is a breaking\nchange.\n\n**Two people apply against two copies of local state.** Out of the box, each\nworkspace's state is a local file. That suits one person on one laptop. As soon\nas a colleague runs Terraform from another copy, the two state files disagree\nabout what exists, and each run acts on its own version. The fix is to keep\nstate in HCP Terraform or in remote storage with locking and access control, as\nHashiCorp recommends. Terraform then locks the state automatically for every\noperation that could write it, and does not continue if it cannot take the\nlock. Not all storage options support locking, so check before choosing one,\nand leave `-lock=false` alone: the flag exists, and the documentation\nrecommends against it.\n\n**A stuck lock is forced open while someone is still working.** When automatic\nunlocking fails, the lock stays behind, and the `force-unlock` command releases\nit with the lock ID that Terraform printed. The locking documentation tells the\nuser to be very careful: forcing a lock that someone else holds can leave two\nwriters on the same state, and the command is meant only for your own lock after\nautomatic unlocking failed. The fix is to find out whose lock it is, and whether\nthat run is still alive, before forcing anything.\n\n**The state file leaks secrets.** HashiCorp warns that secrets can end up in the\nstate, and that storing it in a system without secure access control can expose\nthem. A state file in a world-readable bucket, or copied into a build artefact,\nis a credentials leak. Keep it out of the repository, give it the same access\ncontrol as the secrets it holds, and never edit it by hand; the `terraform\nstate` command exists for the corrections that are needed.\n\n**Approval becomes a formality.** The `-auto-approve` flag skips the interactive\napproval of the plan, and passing a saved plan file skips it too, because the\nfile counts as the approval. The apply documentation warns that this covers\nchanges that destroy things too, deleting resources among them. A CI job that\napplies on every merge without a reviewed plan has removed the one moment where\na person could have seen the destroy coming. The fix is the saved-plan flow\nabove, with a required human review between the plan job and the apply job.\nWhere `-auto-approve` is used in automation, HashiCorp's own advice is to run a\nplan first and review it.\n\n## Further reading\n\n- [What is Terraform?](https://developer.hashicorp.com/terraform/intro)\n  — HashiCorp's introduction: write, plan, apply, providers and state.\n- [terraform apply command](https://developer.hashicorp.com/terraform/cli/commands/apply)\n  — saved plans, `-auto-approve`, and running the command in automation.\n- [State Locking](https://developer.hashicorp.com/terraform/language/state/locking)\n  — automatic locks, unsupported storage and the `force-unlock` warning.\n- [Refactor modules](https://developer.hashicorp.com/terraform/language/modules/develop/refactoring)\n  — why a changed address means destroy and create, and the `moved` block.\n- [HashiCorp adopts Business Source License](https://www.hashicorp.com/en/blog/hashicorp-adopts-business-source-license)\n  — the August 2023 announcement of the move from MPL 2.0 to BSL 1.1.\n- [OpenTofu](https://opentofu.org/)\n  — the fork of Terraform maintained under the Linux Foundation.\n\n\u003chttps://engineer.company/glossary/terraform/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"What Terraform is, how write, plan and apply fit together, why its state file needs a lock, and how a rename or a skipped review destroys real resources.","formats":{"gemtext":"https://engineer.company/glossary/terraform/index.gmi","gopher":"https://engineer.company/glossary/terraform/gophermap","html":"https://engineer.company/glossary/terraform/","json":"https://engineer.company/glossary/terraform/index.json","markdown":"https://engineer.company/glossary/terraform/index.md","pdf":"https://engineer.company/glossary/terraform/index.pdf"},"kind":"page","language":"en","title":"What is Terraform?","url":"https://engineer.company/glossary/terraform/","version":1}