Skip to content
Velloreth
Technology 5 min read

Infrastructure as Code: Managing Servers Like Software

IaC describes infrastructure in a file. Learn the declarative model, the state, the plan, and the drift problem.

By

The idea

Describe the desired state in a file.

A tool makes it so.

The file is versioned, reviewed and tested like application code.

Declarative versus imperative

DeclarativeImperative
Inputthe end statethe steps
Run twicesafemay duplicate
ExampleTerraforma shell script

A declarative tool works out the steps, which is why running it twice is safe.

The state

The record of what the tool created.

resource "aws_instance" "web" {
  ami           = "ami-123"
  instance_type = "t3.micro"
}

The state maps the resource in the file to a real resource.

It must be stored remotely and locked, because two concurrent applies corrupt it.

terraform {
  backend "s3" {
    bucket = "my-tf-state"
    key    = "prod/terraform.tfstate"
    region = "us-east-1"
  }
}

A local state is fine for a solo experiment and wrong for a team.

The plan

A preview of the change.

$ terraform plan

+ aws_instance.web
~ aws_security_group.web
- aws_instance.old

+ create, ~ change, - destroy.

Reviewing the plan is the main safety control, because a destroy is visible before it happens.

terraform apply runs the plan.

The drift

A manual change that the file does not know about.

The tool detects it on the next plan.

It either reverts the change or reports it.

Drift is the reason a manual change in a console is discouraged, because the file is no longer the truth.

terraform refresh updates the state from the real infrastructure.

The modules

A reusable group of resources.

module "web" {
  source        = "./modules/web"
  instance_type = "t3.micro"
  count         = 3
}

A module is the unit of reuse, and it is versioned.

A public registry has a module for a common pattern.

The variables

variable "instance_type" {
  type    = string
  default = "t3.micro"
}

resource "aws_instance" "web" {
  instance_type = var.instance_type
}

A variable makes a module reusable.

An output exposes a value.

output "ip" {
  value = aws_instance.web.public_ip
}

The environments

A separate state per environment.

prod/terraform.tfstate
staging/terraform.tfstate

A workspace is an alternative.

terraform workspace new staging

A separate directory is the clearer choice for a small team, because the configuration can differ.

The pipeline

- run: terraform init
- run: terraform validate
- run: terraform plan -out=tfplan
- run: terraform apply tfplan
  if: github.ref == 'refs/heads/main'

init downloads the providers.

validate checks the syntax.

plan previews the change.

apply makes it so, and it is gated on the main branch.

A plan artifact is passed to the apply, so the applied change is the reviewed one.

The tools

ToolNotes
Terraformmulti-cloud, a large ecosystem
OpenTofua fork of Terraform
Pulumia real language
CloudFormationAWS native
Ansibleconfiguration management
Kubernetesa declarative API

Terraform is the common default for a multi-cloud setup.

Ansible is for the configuration inside a server, which is a different layer.

The state in a team

The state file is the part of infrastructure as code that surprises a new team, because it is a file that must be shared and must not be edited by hand. It records the mapping between a resource in the configuration and a real resource in the cloud, and the tool uses it to decide what to create, what to change and what to destroy. A local state works for one person on one machine, and it fails the moment a second person applies a change, because the two states diverge and the tool loses track of a resource. The fix is a remote backend with a lock, so the state is shared and only one apply runs at a time. The state also contains a secret in plain text, because a resource attribute such as a password is stored there, so the backend must be encrypted and access-controlled, and the state must never be committed to a repository.

The review workflow

The plan is the review artifact, and the workflow around it is what makes infrastructure as code safe. A change is proposed as a pull request, and the pipeline runs a plan and posts it as a comment, so a reviewer sees exactly what will be created, changed and destroyed before approving. The plan is then saved as an artifact and applied by the same pipeline, so the applied change is the reviewed one rather than a fresh plan that may differ. The second control is a policy check, which rejects a plan that would delete a protected resource or open a port to the world. The third is a manual approval for a production apply, which is a deliberate speed bump. A team that reviews the plan catches the accidental destroy, and a team that applies without a review eventually deletes something it needed.

Common mistakes

A local state in a team. A conflict.

No state lock. A concurrent apply.

A state file committed. A secret leak.

No plan review. An unexpected destroy.

A manual change. Drift.

A hardcoded value. A copy per environment.

No module. A duplicated configuration.

A secret in the file. It is in the history.

No version pin. A provider update breaks the plan.

No terraform fmt. An inconsistent style.

A quotable summary

Infrastructure as code describes the desired state in a versioned file, and a declarative tool compares it with the real infrastructure and makes the change. The state file is the record of what the tool created and must be stored remotely and locked, a plan previews the change before it is applied, and drift is a manual change that the file does not know about. Review the plan, because a destroy is visible before it happens.

For the related topics, see ci-cd-pipeline-basics and docker-basics-guide. For the broader context, kubernetes-basics and twelve-factor-app-explained.

Frequently asked questions

What is infrastructure as code?
The practice of describing infrastructure in a versioned file rather than by clicking in a console. A tool reads the file, compares it with the real infrastructure, and makes the changes needed. The file is reviewed, tested and versioned like application code.
What is the difference between declarative and imperative?
A declarative tool takes the desired end state and works out the steps, so running it twice is safe. An imperative script takes a list of steps, so running it twice may duplicate. Terraform and Kubernetes are declarative, and a shell script is imperative.
What is a state file?
The record a declarative tool keeps of the resources it created, mapping a resource in the file to a real resource. It is what lets the tool know what to change and what to delete. It must be stored remotely and locked, because two concurrent applies corrupt it.
What is a plan?
A preview of the changes a tool will make, shown before they are applied. It lists the resources to create, change and destroy. Reviewing the plan is the main safety control, because a destroy is visible before it happens.
What is drift?
A difference between the real infrastructure and the file, caused by a manual change. The tool detects it on the next plan, and it either reverts the change or reports it. Drift is the reason a manual change in a console is discouraged.
Should I use Terraform or a cloud-native tool?
Terraform is multi-cloud and has a large provider ecosystem. A cloud-native tool such as CloudFormation or a CDK is tightly integrated with one cloud. A small team on one cloud may prefer the native tool, and a team on several clouds usually prefers Terraform.