{"canonical_url":"https://engineer.company/glossary/infrastructure-as-code/","content_markdown":"# Infrastructure as code\n\n## What it is\n\nInfrastructure as code is the practice of describing the things a system runs\non (machines, networks, firewall rules, load balancers, DNS records) in text\nfiles, keeping those files in version control, and letting a tool build the\nreal environment from them. The files are the master copy. A change to the\ninfrastructure starts as a change to a file, passes the same review as\napplication code, and reaches the running system only when the tool applies\nit. The term is also written with hyphens, infrastructure-as-code, and\nshortened to IaC.\n\nNIST's Special Publication 800-204C, a guide to DevSecOps for applications built\nfrom microservices, describes infrastructure as code as the code that provisions\nand configures the resources an application is deployed on, “in a repeatable and\nconsistent manner”. The same guide says these definitions are kept under version\ncontrol with the same tools as the application's own source code. Repeatability\nis the whole point. An environment that can be produced from files can be\nproduced again, next to the first one, after a disaster, or in a test account on\na Tuesday afternoon.\n\nDefinitions come in two broad styles. A declarative definition states the end\nresult, say a server of a given size in a given network with one port open, and\nleaves the tool to work out what to create, change or leave alone. An imperative\ndefinition is a list of steps: create this, attach that, then open the port. SP\n800-204C files infrastructure as code under declarative code: the team writes\ndown what it requires, and a tool turns that into a running instance. HashiCorp\ndescribes the Terraform language in the same terms, as a description of an\nintended goal rather than of the steps that reach it. The difference shows on\nthe second run. A list of steps records how something was done once, while a\ndeclaration records what should exist, and that is what the tool needs to know\nwhen part of it already does.\n\nThere is no single language. SP 800-204C notes that, depending on the tool, the\ncode is written either in a general scripting language such as Python,\nJavaScript or TypeScript, or in a configuration language of the tool's own, such\nas HashiCorp's HCL, which may or may not be compatible with a standard format\nlike JSON. Terraform's language is of the second kind and lives in files ending\nin `.tf`. Azure accepts Resource Manager templates in JSON or in the shorter\nBicep language. Ansible writes its playbooks in YAML and reaches machines over\nSSH with their existing operating-system credentials, without installing an\nagent on them.\n\nIt helps to separate two jobs that both fall under the name. Provisioning\ncreates the pieces: the virtual machine, the disk, the network, the firewall.\nConfiguration shapes what runs inside a machine that already exists: packages,\naccounts, service files. Some tools lean towards one job and some towards the\nother, and the boundary is soft. What makes either of them infrastructure as\ncode is that the definition lives in a repository and the tool brings the real\nsystem into line with it.\n\nTools also differ in how they remember what they built. Terraform keeps a state\nfile that maps the resources in the configuration to the real objects it\ncreated, and its documentation describes that state as the source of truth for\nthe environment. Bicep keeps no state file, because Azure itself records what\nwas deployed. Where the record lives decides what happens when two people run\nthe tool at once, or when the record is lost.\n\n## Why it matters\n\nBefore infrastructure as code, each environment was set up by hand and then\npatched by hand. Staging received a fix that production did not, a port opened\nfor a test was never closed, one machine out of three got a newer package. SP\n800-204C calls this drift: the configuration in place no longer gives the\noperational state that was intended. It also names the usual way in, a change\nmade in a web console or on the command line that goes around the code. When a\nrelease works in staging and fails in production, drift is a common reason.\n\nInfrastructure as code moves the master copy out of the running system. The team\nchanges the definition, and the running system follows it. Nobody logs in to\nchange a firewall rule; they change the file that describes the firewall, and\nthe tool carries the change out. Three things follow from that.\n\nThe first is review and history. A change to the network becomes a diff in a\npull request that a second person reads before anything happens. Months later,\nthe question of who opened a port, and why, has an answer in the commit log\ninstead of in somebody's memory. Undoing a change is a revert followed by\nanother run of the tool.\n\nThe second is repeatability. A well-written definition is idempotent: applied to\nan environment that already matches, it changes nothing, and applied to one that\nhas drifted, it brings it back. There are two ways to get there: adjust what is\nthere, or discard it and build a fresh one from the definition. The second way,\ntaken as a rule, is immutable infrastructure.\n\nThe third is cheap environments. SP 800-204C describes the tools as automating\nthe whole life of the infrastructure, from provisioning to de-provisioning, and\nnotes that some of it lives too briefly to be worth maintaining at all. A team\ncan create several test environments on demand and tear them down again, and the\ncode itself can be checked before it touches anything: the guide asks for every\npiece of it to be scanned for vulnerabilities before it is merged. A branch can\nget its own short-lived copy of the production layout, and a reviewer can see a\npreview of a change before approving it.\n\nThe costs deserve a plain statement. Changing one firewall rule through a pull\nrequest is slower than changing it in a web console, and during an outage that\nfeels expensive. Each tool has its own language and its own model of state to\nlearn. And a file that can build an environment can also delete one: the lever\nreaches just as far in both directions, which is why the preview matters as\nmuch as the run that follows it.\n\n## What it looks like in practice\n\nHere is one change travelling from an edit to the running system, in a setup\nwhere a CI job runs the tool and posts its dry run on the pull request:\n\n```text\nDay 1   09:10  Edit the network definition: allow TCP 443 from the office\n        09:12  Open a pull request; CI runs a dry run (the plan)\n        09:14  Plan posted on the pull request: one rule added, none removed\n        10:30  A reviewer reads the plan as well as the diff, and approves\n        10:31  Merge; CI applies the plan that was reviewed\n        10:33  A second run of the same definition reports no changes\nDay 40         Someone asks why 443 is open: the commit log says who and why\n```\n\nThe plan is the part that earns its keep. The diff shows what the author meant\nto change; the plan shows what the tool is about to do, including anything the\nauthor did not expect, such as a resource it intends to destroy. Terraform can\nsave a plan to a file with `-out`, and `terraform apply` given that file\nperforms the operations in it, so what runs at 10:31 is what the reviewer\napproved at 10:30. The quiet second run at 10:33 is the check that\nthe definition and the system now agree.\n\nOn this site, the\n[Infrastructure as Code service page](/services/infrastructure-as-code/)\ndescribes repeatable server provisioning from versioned configuration rather\nthan relying on somebody's memory.\n\nGetting there safely is mostly a matter of order, and a\n[portfolio entry from September 2026](/portfolio/provisioned-a-second-server-from-code/)\nshows why. It adds a second server, hosted with another provider. The earlier\nmachine had been set up by hand and protected later, so for a while a newly\ncreated host on a default password policy sat open to the internet. This time\nthe server was created from the repository, and the protection was in place\nbefore the machine was. The firewall play is run ahead of the server play, and\nat the second provider the tags are assigned before the cloud firewall, since\nrules aimed at tags have nothing to attach to until the tags are there. A rerun\ndoes no harm, because the creating role takes over a machine that already\nexists. That role is the only one that costs money, so its own documentation\nrecords the region, the machine type and its specification, and the price per\nmonth in euros. The entry is also candid about what a dry run misses. Both\nfirewalls are configured by calling the providers' REST APIs from a\ngeneral-purpose HTTP task, and that task does not support check mode, so a dry\nrun passes over it. The real rehearsal is a run of the firewall play on its own,\nwhich costs nothing and can be undone.\n\n## Where it goes wrong\n\nInfrastructure code tends to fail in ways that look like success. The tool\nfinishes cleanly, the CI run is green, and the files and the real system\nquietly disagree.\n\n**A hand fix made during an incident is undone by the next run.** Someone opens\na port in the console at two in the morning, the outage ends, and a week later\nthe routine run closes it again, because the files never heard about it. The\nopposite also happens: nobody runs the tool again, and the files stop describing\nreality. Put the emergency change into the code the same day, and run a\nscheduled check that compares the files with what is running; SP 800-204C asks\nfor that comparison straight after each deployment and at intervals while the\nsystem runs. With Terraform the plan command's detailed exit code makes that a\nshort nightly job:\n\n```sh\nterraform plan -detailed-exitcode\n# exit 0: no changes, exit 1: error, exit 2: changes present\n```\n\nOn a branch that has already been applied, an exit code of 2 means the real\nsystem has moved away from the code, and someone should find out why.\n\n**Deleting a resource from the file does not always delete it.** Tools disagree\nabout what a missing resource means. For Azure Resource Manager templates,\nMicrosoft's what-if documentation states that a resource which exists but is\nnot in the template is deleted only in complete mode. In any other mode it keeps\nrunning and keeps costing money. Learn your tool's rule for removal before\nrelying on it, and read the preview for the deletions you expect as well as the\nones you fear.\n\n**The dry run does not see everything.** A preview is a model of the change,\nnot a guarantee. Microsoft's what-if documentation lists properties reported as\ndeleted when Azure only fills in a default during deployment, and calls the\nresult noise; any property set through the `reference` function shows as\nchanging on every run. The portfolio entry above shows the other gap: a task\nwithout check-mode support is skipped in a dry run, so the preview says nothing\nabout it. Know your tool's known noise, and treat whatever the preview cannot\nsee as untested until a rehearsal on something cheap and reversible covers it.\n\n**Secrets end up in the repository or in the state.** A password written into a\ndefinition file stays in the history of every clone. Less obvious: Terraform's\ndocumentation warns that its state can hold secrets, and by default that state\nis a local file called `terraform.tfstate`. Keep secrets in a secret store and\nrefer to them by name, keep state in remote storage with locking and access\ncontrol, as HashiCorp recommends, and never edit the state file by hand; the\n`terraform state` command exists for the changes that are needed.\n\n**A script is dressed up as a definition.** A shell script in the repository\nthat creates a server is under version control, but it is not idempotent: run it\ntwice and there are two servers, or an error halfway through. Use declarative\nresources, or steps that check before they act, such as the role above that\nadopts an existing machine. Ansible's documentation sets the standard plainly:\nwhen a system is already in the state a playbook describes, running the\nplaybook again changes nothing.\n\n## Further reading\n\n- [Implementation of DevSecOps for a Microservices-based Application with Service Mesh (NIST SP 800-204C)](https://csrc.nist.gov/pubs/sp/800/204/c/final)\n  — infrastructure as declarative, versioned code, drift and scanning.\n- [Terraform Language Documentation](https://developer.hashicorp.com/terraform/language)\n  — the declarative language, its resources and its blocks.\n- [Command: plan](https://developer.hashicorp.com/terraform/cli/commands/plan)\n  — the dry run, saved plans and the detailed exit codes.\n- [State](https://developer.hashicorp.com/terraform/language/state)\n  — what Terraform records, where it keeps it, and why it is sensitive.\n- [Introduction to Ansible](https://docs.ansible.com/ansible/latest/getting_started/introduction.html)\n  — agentless automation over SSH, playbooks and desired state.\n- [Template deployment what-if](https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/deploy-what-if)\n  — previewing an Azure deployment, its change types and its known noise.\n\n\u003chttps://engineer.company/glossary/infrastructure-as-code/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"What infrastructure as code means, why teams write servers and networks down as files, how one change travels from edit to running system, and where it breaks.","formats":{"gemtext":"https://engineer.company/glossary/infrastructure-as-code/index.gmi","gopher":"https://engineer.company/glossary/infrastructure-as-code/gophermap","html":"https://engineer.company/glossary/infrastructure-as-code/","json":"https://engineer.company/glossary/infrastructure-as-code/index.json","markdown":"https://engineer.company/glossary/infrastructure-as-code/index.md","pdf":"https://engineer.company/glossary/infrastructure-as-code/index.pdf"},"kind":"page","language":"en","title":"What is infrastructure as code?","url":"https://engineer.company/glossary/infrastructure-as-code/","version":1}