Terraform: a practical guide to infrastructure as code

Terraform is an infrastructure-as-code tool. You describe the target infrastructure in configuration files, and Terraform compares that description with real infrastructure, builds a plan, and then creates, updates, or deletes objects until the two match. The real job is not "writing cloud scripts." It is keeping an explicit model of infrastructure state.

Terraform can manage far more than basic IaaS objects. A Terraform configuration may include virtual machines, networks, DNS records, IAM bindings, managed databases, and even SaaS resources. The boundary is the provider model: if a provider can create, read, update, and delete a resource type, Terraform can manage it.

The CLI workflow has three moving parts:

1. The Terraform CLI itself.
2. Configuration files written in the Terraform language, which is based on HCL.
3. Providers, which are plugins that talk to cloud or service APIs.

Terraform reads the configuration, builds an execution plan, and decides which objects must be created, changed, replaced, or removed. It also tracks dependencies between resources and applies changes in parallel where that is safe.

Install Terraform from the official downloads page and place the binary on $PATH.

Terraform supports -chdir=DIR to run commands against a different working directory. That is handy in scripts and monorepos.

Shell completion can be installed with terraform -install-autocomplete and removed with terraform -uninstall-autocomplete.

Many subcommands accept resource addresses. A few common forms are:

The CLI configuration file path can be set with TF_CLI_CONFIG_FILE. On non-Windows systems, the default path is $HOME/.terraformrc. This file can configure plugin caching, credentials, and provider installation behavior.

dev_overrides is mainly for provider development. It lets you test a local provider binary without going through the full registry and checksum flow.

terraform init prepares the working directory. Terraform commands are expected to run from a directory that contains Terraform configuration files. Initialization downloads providers and modules, sets up the backend, and creates local working data.

After initialization, the directory usually contains:

• .terraform/, which stores provider and module downloads.
• terraform.tfstate when the local backend is used.
• terraform.tfstate.d/ when multiple workspaces are used with the local backend.

Some changes require re-running initialization, especially provider version changes, module source changes, and backend configuration changes.

terraform get can download modules without doing the full set of init tasks. terraform init -upgrade upgrades providers and modules to newer versions that still satisfy the version constraints.

terraform validate checks whether the configuration is syntactically and structurally valid.

terraform plan shows the changes Terraform would like to make. It compares the desired state from configuration with the current state of the infrastructure, using both the state file and provider API reads.

Terraform's core execution loop is built around three commands: plan, apply, and destroy.

A saved plan can later be passed to terraform apply.

1. Destroy mode, enabled by -destroy, builds a plan that removes everything tracked by the current configuration.
2. Refresh-only mode, enabled by -refresh-only, updates state and root outputs to match infrastructure changes made outside Terraform.

Use -var 'NAME=VALUE' to set input variables directly, and -var-file=FILENAME to load them from a file.

Use -parallelism=n to cap concurrency. The default is 10.

Option	Meaning
-refresh=false	Skip the pre-plan refresh step. This can reduce remote API calls, but Terraform may miss drift introduced outside Terraform.
-replace=ADDRESS	Force Terraform to plan a replacement for a single resource instance, such as aws_instance.example[0].
-target=ADDRESS	Limit planning to a specific resource and its dependencies. Useful for debugging, but easy to abuse.
-input=false	Disable interactive prompts for root input variables. This is standard in CI and batch execution.

terraform apply executes the proposed changes. By default it runs an implicit plan first, though it can also execute a previously saved plan file.

The basic form is terraform apply [options] [plan file].

Use -auto-approve to skip manual approval.

Use -lock-timeout=DURATION to wait for a state lock before failing.

terraform destroy removes all infrastructure objects managed by the current configuration and workspace.

Command	Meaning
console	Evaluate Terraform expressions interactively.
fmt	Format configuration files.
force-unlock	Remove a stale state lock. Use carefully, because unlocking while another process is still running can corrupt state.
graph	Generate a dependency graph of the configuration.
import	Attach an existing infrastructure object to a resource address in configuration.
login / logout	Manage credentials for remote services such as Terraform Cloud or a private module registry.
output	Show root module outputs.
providers	Show provider dependencies for the current module.
refresh	Refresh state to match remote infrastructure.
show	Display a saved plan or current state in human-readable form.
workspace	Manage and switch workspaces.

taint marks a resource instance as not fully functional. That flag does not immediately change infrastructure, but the next plan will propose destroying and recreating the object.

untaint clears that status.

A Terraform configuration is built from blocks. The syntax looks like this:

A block is a container, and its meaning depends on the block type. In a resource block, the two labels identify the resource type and local name.

Depending on block type, the number of labels may be zero, fixed, or variable. A block body may contain arguments or nested blocks. Top-level blocks are limited to a fixed set of Terraform language constructs.

An argument assigns a value to a name. The available arguments and their types depend on context, usually the resource type or block type.

Identifiers are used for argument names, block type names, and many Terraform object names. They may contain letters, digits, -, and _, but cannot start with a digit.

Single-line comments can start with # or //. Multi-line comments use /* ... */.

Type	Meaning
string	Unicode text, for example "hello".
number	Numeric value, for example 6.02.
bool	true or false.
list / tuple	Ordered collections, for example ["us-west-1a", "us-west-1c"].
map / object	Key-value structures, for example { name = "Mabel", age = 52 }.

null represents the null value.

Terraform strings support standard escapes such as \n, \r, \t, \", \\, \uNNNN, and \UNNNNNNNN.

Indented heredoc is also supported:

Terraform can render JSON or YAML from native values with helper functions such as jsonencode:

Terraform supports interpolation with ${ ... } and template directives with %{ ... }.

Whitespace trimming uses ~ inside template directives.

Terraform expressions can reference values from several sources:

• <RESOURCE TYPE>.<NAME> for managed resources.
• var.<NAME> for input variables.
• local.<NAME> for locals.
• module.<MODULE NAME> for child module outputs.
• data.<DATA TYPE>.<NAME> for data resources.
• path.module, path.root, and path.cwd for filesystem paths.
• terraform.workspace for the current workspace name.

Special values also appear in certain contexts, including count.index, each.key, each.value, and self.

Terraform supports logical operators such as !, &&, and ||; arithmetic operators such as *, /, %, +, and -; and the usual comparison operators.

A for expression transforms one complex value into another. Each input element may contribute zero or one output element.

You can also filter values with an if clause:

Grouping mode is enabled by adding ... at the end of the value expression:

Expressions can assign argument values, but they cannot directly repeat or conditionally emit nested blocks. That is where dynamic blocks come in.

dynamic can generate nested blocks inside resources, data sources, providers, and provisioners. It cannot generate meta-argument blocks such as lifecycle.

Splat expressions are a concise alternative to some for expressions:

Splat syntax works with list-like collections, not maps or objects. It can also turn a single optional value into a list-like expression in some contexts:

Module and provider authors can use type constraints to validate user input. Terraform's type system is stronger than it first appears. You can constrain not only the outer type, but also the shape and element types inside it.

Terraform also performs automatic conversions between similar complex types, such as object and map, or tuple and list, when the values fit the required shape. That flexibility is convenient, but it also means module authors should think carefully about how strict they want input constraints to be.

any is not really a type. It is a placeholder that Terraform resolves to a concrete type during type-checking. For example, a value such as ["a", "b", "c"] can satisfy list(any), and Terraform will infer a more specific list element type behind the scenes.

Version constraints appear when selecting modules, providers, or the Terraform CLI version itself:

~> allows changes to the rightmost specified version component.

A resource block declares the desired shape of a real infrastructure object:

The resource type decides which arguments exist. The local name only matters inside the current module. Together, the type and local name form the module-local identity of the resource.

When Terraform creates a new resource, it stores the remote object's identifier in state. On later runs, Terraform compares the real object with the configuration and decides whether to update it in place, replace it, or leave it alone.

When a configuration is applied, Terraform generally does four things:

1. Create resources that exist in configuration but not in state.
2. Destroy resources that exist in state but no longer exist in configuration.
3. Update resources whose arguments changed and support in-place changes.
4. Replace resources whose arguments changed but cannot be updated in place.

That last case depends heavily on provider behavior and the underlying API. Terraform decides the graph; the provider decides what each API operation can actually do.

Within the same module, resource attributes are accessed as <RESOURCE TYPE>.<NAME>.<ATTRIBUTE>.

Besides user-supplied arguments, resources also expose read-only attributes that come back from the provider API, such as generated IDs.

Terraform infers most dependencies from expressions. If one resource argument references another resource, Terraform treats that as a dependency edge in the graph.

For dependencies that cannot be inferred from expressions, use the depends_on meta-argument.

Some resource types do not represent remote infrastructure at all. They only store data in Terraform state. These local-only resources are often used for intermediate values such as generated random IDs or local key material.

Every resource type belongs to a provider. A provider is a Terraform plugin that implements one or more resource types and data source types.

A module needs providers for every resource it uses, and provider configuration is usually supplied by the root module. Providers can also expose multiple configurations, often to target different regions or accounts.

Resources implicitly depend on their selected provider configuration, so Terraform will not try to create the resource before the provider is ready.

depends_on handles dependencies that expression analysis cannot see. It should be used sparingly.

count creates several similar resource instances from one block:

Instances are referenced with index syntax such as aws_instance.server[0].

for_each is more flexible than count when instances differ in meaningful ways. It accepts a map or a set(string).

Resources created by for_each are referenced with key syntax such as azurerm_resource_group.rg["a_group"].

The keys must be known before apply, cannot come from impure functions such as uuid or timestamp, and cannot be sensitive values.

You can also chain for_each from one resource to another:

The lifecycle block customizes replacement and update behavior:

Argument	Meaning
create_before_destroy	Create the replacement first, then delete the old object.
prevent_destroy	Fail if the plan would delete the resource.
ignore_changes	Ignore selected attribute differences when deciding whether an update is needed. The special value all suppresses all updates.

Some resource types provide a nested timeouts block:

Provisioners are the escape hatch for actions that do not fit Terraform's declarative model. Use them reluctantly. They add uncertainty and sit outside the normal planning model.

Terraform cannot reason very well about provisioner side effects. Provisioners also tend to need direct network access, credentials, and timing assumptions that make runs less predictable.

Provisioners use self to refer to the parent resource. They also support when and on_failure:

If a create-time provisioner fails, Terraform marks the resource tainted so the next apply can replace it.

Many provisioners need SSH or WinRM. Connection details can be declared at the resource level or on a specific provisioner:

null_resource exists for provisioner-driven workflows that are not tied to a real managed resource.

The common built-in provisioners are:

Provisioner	Meaning
file	Copy files or directories from the machine running Terraform to the target resource.
local-exec	Run a local command after a resource action.
remote-exec	Connect to the remote resource and run commands there.

A data source, declared with a data block, reads information from an external system and exposes the result to the configuration. It is still provider-backed, but it only reads.

If the query arguments are known during planning, Terraform reads the data source during refresh. If those arguments depend on values that will only exist after apply, Terraform delays the read until apply time.

Data sources support the same dependency patterns and most of the same meta-arguments as managed resources.

Modules in Terraform behave a bit like functions. Input variables are the parameters, outputs are the return values, and locals are internal named expressions.

Input variables parameterize a module so it can be reused in different configurations. Root module variables can be set from the CLI or variable files. Child module variables must be passed through the corresponding module block.

Variable values can come from -var, -var-file, environment variables, or automatically loaded files such as terraform.tfvars.

Locals are named expressions used to simplify or normalize configuration logic:

Locals can reference other locals as long as there is no dependency cycle.

Outputs expose values from a module to its caller or to the CLI:

Terraform makes more sense once you treat it as a graph engine wrapped around provider APIs. Configuration declares vertices and edges. State records which remote objects correspond to which addresses. Providers translate graph operations into API calls.

Most Terraform work is not about memorizing syntax. It is about knowing which values are known at plan time, where dependencies come from, what the provider can update in place, and when a resource has to be replaced. Once those four things are clear, the language stops feeling mysterious.