Getting Started with Terraform

Source: Install Terraform

To update later, run brew update followed by brew upgrade hashicorp/tap/terraform.

Source: Install Terraform

The first command imports HashiCorp’s signing key; the second registers the repository for the distribution’s codename. After that, apt upgrade delivers new Terraform releases like any other package — fine on a workstation, but CI should pin an exact version (see the version managers below).

Source: Install Terraform

The official install page offers the signed zip archives (386, AMD64 and ARM64); the install tutorial additionally mentions Chocolatey. Either way the result must be a terraform.exe on the PATH:

Source: Install Terraform (tutorial)

For the manual route, download terraform_<version>_windows_amd64.zip from releases.hashicorp.com, extract terraform.exe into a folder such as C:\tools\terraform and add that folder to the user Path environment variable. Open a new terminal afterwards: an already-open shell does not see the changed Path.

HashiCorp publishes a verified image whose entrypoint is the terraform executable, so subcommands are passed as the container command. Pin a release tag in anything but a quick experiment:

Source: hashicorp/terraform on Docker Hub

The container only sees what is mounted and passed in: configuration files via the bind mount, provider credentials via -e flags or mounted files, and, for the Docker provider used below, the Docker socket. That makes the image a good fit for pipelines (see CI/CD with GitHub Actions) and an awkward one for the local Docker tutorial, so the rest of this page assumes a native install.

terraform -help begins with Usage: terraform [global options] <subcommand> [args]; adding -help to any subcommand prints its options. The output of terraform version varies with the platform and installed providers (it lists providers once a directory has been initialized).

Source: Install Terraform (tutorial)

Source: tenv on GitHub

Because tenv also manages OpenTofu (tenv tofu ...), it is the natural choice when a team runs both tools; OpenTofu explains how they differ.

Source: tfenv on GitHub

With no argument, tfenv install takes the version from TFENV_TERRAFORM_VERSION, then from .terraform-version, and otherwise uses latest. min-required and latest-allowed scan required_version in the .tf files, but only look at the first constraint, so a compound constraint can resolve to a surprising version. Treat them as a convenience and prefer an explicit file.

Source: terraform-switcher on GitHub

tfswitch’s documentation describes the full set of version sources and flags on tfswitch.warrensbox.com; the exact precedence between its sources was not checked for this page, so confirm it there before relying on it in automation.

CI/CD and Automation shows the pinned-version pattern in a pipeline.

The HashiCorp Terraform extension (ID HashiCorp.terraform) provides syntax highlighting for Terraform 1.x, validation as you type, and formatting through terraform fmt. It bundles the Terraform language server (terraform-ls) and keeps it updated, so no separate install is needed. Formatting requires the terraform binary on the PATH. The extension’s recommended format-on-save setting, repeated for each Terraform language ID (terraform, terraform-vars, terraform-stack, terraform-test and the others it lists):

Source: HashiCorp Terraform extension

Enhanced validation (deprecations, missing required attributes) is on by default and controlled by terraform.validation.enableEnhancedValidation; the extension’s terraform validate integration needs a prior terraform init. Use terraform.languageServer.terraform.path to point the server at a specific binary, for example one managed by tenv.

terraform-ls is the official language server (LSP) behind the extension. Editors without a bundled integration use it directly:

Source: terraform-ls installation

On Linux, terraform-ls is also published in HashiCorp’s apt and RPM repositories under that package name. The terraform-ls usage guide lists client setup for Vim and Neovim (coc.nvim, vim-lsp, nvim-lspconfig and others), Emacs (lsp-mode) and Sublime Text (LSP-terraform).

JetBrains publishes its own plugin, listed on the Marketplace as Terraform and HCL; its settings page is Tools | Terraform and OpenTofu, where the executable path can be set (the IDE usually detects it) and where run configurations for Terraform are available. The terraform-ls usage guide describes an alternative LSP-based setup for JetBrains IDEs and warns that combining it with the JetBrains plugin can produce duplicate completions, so use one of the two.

Source: Terraform and OpenTofu in IntelliJ IDEA

Create an empty directory and a file main.tf. The first version creates only the nginx image and container for the web service, exactly the shape the tutorial uses:

Source: Build Infrastructure (Docker tutorial)

What each block does:

The HCL language itself is the subject of HCL Syntax and Configuration Files; providers are covered in depth in Providers.

Source: Build Infrastructure (Docker tutorial)

The output is the tutorial’s, abbreviated; the version numbers follow the pin in this page’s configuration. init is the first command to run in any directory and it is safe to repeat: it never deletes configuration or state. It performs three steps: initialize the backend (where state is stored; the default is a local file), install child modules, and install provider plugins. It must be re-run whenever the backend configuration, a module source or the provider requirements change; other commands detect a stale directory and say so.

Useful options:

Source: terraform init

After init the directory contains two new items:

An excerpt, using the shape documented by HashiCorp (hashes shortened):

Source: Dependency Lock File

terraform fmt rewrites the files in the current directory into the canonical style (indentation, aligned = signs, spacing) and lists the files it changed. Useful options are -recursive to include subdirectories, -diff to show what would change, and -check to change nothing and exit non-zero if any file needs formatting, which is how a CI job enforces the style. terraform validate checks syntax and internal consistency — attribute names, value types, references — regardless of variable values or state. It needs an initialized directory (use terraform init -backend=false to initialize without touching a backend) and does not contact remote services or provider APIs; -json produces machine-readable diagnostics for editors and pipelines.

Sources: terraform fmt and terraform validate

Source: Build Infrastructure (Docker tutorial)

plan compares three things — the configuration, the state, and (after refreshing it) the real objects — and prints the actions needed to make reality match the configuration. It changes nothing. The output is abbreviated here (... marks omitted attributes) and the attribute list varies with the provider version. A value shown as (known after apply) is computed by the provider when the object is created and cannot be known in advance.

The legend printed at the top of every plan lists the actions in use. The symbols are:

Source: terraform plan

The plan reference documents +, -, ~ and -/+. The +/- and <= rows come from the legend Terraform prints at the top of a plan and from the data source documentation, which only states that deferred reads are indicated in the plan; check the legend of your own plan output, since the exact wording is the CLI’s to define. Reading a plan is a skill of its own: Dependency Graph and Plan covers planning modes, saved plans and the situations that produce surprising replacements. The rule of thumb is: read every - and every -/+ line before approving, because those are the lines that delete data.

Source: Build Infrastructure (Docker tutorial)

Without a plan file, apply creates a plan, shows it and waits for the literal answer yes. Open http://localhost:8000 to see the nginx welcome page, and docker ps shows the container named bookshelf-web. Options worth knowing now:

Source: terraform apply

terraform show prints the latest state snapshot in human-readable form; given a saved plan file it prints that plan instead. -json produces the machine-readable form, in which sensitive values appear in plain text, so treat that output as sensitive. The state itself — the file terraform.tfstate that apply created next to the configuration — is what Terraform uses to map configuration addresses to real objects; it is explained in State.

Source: terraform show

Edit main.tf and change the published port from 8000 to 8080, then run terraform plan. The tutorial shows what happens:

Source: Change Infrastructure (Docker tutorial)

The excerpt is abbreviated: the tutorial documents the -/+ marker, the # forces replacement annotation on the external port and the Plan: 1 to add, 0 to change, 1 to destroy. summary; the surrounding attributes vary with the provider version. The container’s port mapping cannot be altered in place, so the provider declares the argument as forcing replacement: Terraform destroys the old container and creates a new one, and apply ends with Apply complete! Resources: 1 added, 0 changed, 1 destroyed. This is the most important lesson of the first hour: whether a change is an update or a replacement is a property of the provider’s schema, not of Terraform core, and the plan is where you learn it.

Hard-coded values do not scale, so the next step in the tutorial extracts them. Add variables.tf and outputs.tf, with the Bookshelf additions: a generated name suffix and a generated database password.

Sources: Define Input Variables (Docker tutorial) and Query Data with Outputs (Docker tutorial)

The tutorial’s variable is container_name with a description, type and default, and its outputs are container_id and image_id; the random resources, web_port, web_url and postgres_password are additions for Bookshelf. random_pet generates a readable name (two words separated by - by default) and random_password generates a password with a cryptographically secure generator. Its result is marked sensitive, so it is hidden in console output, but it is still stored in plain text in the state file — one of the reasons state must be treated as a secret (see State and Sensitive Data, Ephemeral Values and Write-only Arguments).

Variables can be overridden without editing files. Run terraform init again (a new provider was added), then:

Source: Query Data with Outputs (Docker tutorial)

terraform output lists all outputs of the root module; naming one prints that value, and a sensitive value is masked as <sensitive> unless it is requested by name (for example with -raw). Outputs are also the interface between modules and between configurations, which is why they get a page of their own: Variables, Outputs and Locals covers precedence (terraform.tfvars, -var-file, TF_VAR_ environment variables), validation, and sensitivity.

Source: Destroy Infrastructure (Docker tutorial)

destroy plans the removal of every object recorded in the current state and, after confirmation, deletes them in reverse dependency order: the container first, then the image it uses. It only affects the resources this configuration manages. With the Bookshelf additions the plan reports the random_* resources as well (they only exist in state, so their removal is instant). terraform apply -destroy creates the same plan; both honour -auto-approve. Destroy is the reason throwaway environments are cheap with Terraform, and the reason that production resources should carry prevent_destroy guards, covered in Lifecycle, Validation and Checks.