Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 37 ยท Infrastructure as Code Basics

Installing Terraform and Your First Configuration

Install Terraform or OpenTofu on Windows, macOS or Linux, write a first main.tf with the local and random providers, and run init, plan, apply and destroy safely.

Before you touch a cloud, you should be able to run Terraform on your own laptop and see it work without spending money. Terraform ships as a single binary with no dependencies, and a few harmless providers (local, random, null) let you practice the full workflow using nothing but files on your disk. This lesson installs the tool, writes a first configuration and walks through each command.

As explained in What Is Terraform?, the commands and hcl files below are read-only here. Install Terraform and type them yourself; the stand-ins on this page let you see the ideas in the browser.

Installing Terraform

Pick the way that matches your system. All of them put a terraform executable on your PATH.

Terminal
# macOS (Homebrew)
brew tap hashicorp/tap
brew install hashicorp/tap/terraform

# Windows (winget or Chocolatey)
winget install Hashicorp.Terraform
choco install terraform

# Debian / Ubuntu: add HashiCorp's apt repository, then
sudo apt-get install terraform

You can also download a zip from HashiCorp's release page, unzip it and put the file in a folder on your PATH. Check the install:

Terminal
terraform version
TEXT
Terraform v1.14.0
on linux_amd64

(Example output; your version number will differ.)

OpenTofu installs the same way (brew install opentofu, winget install OpenTofu.Tofu) and you run tofu version, tofu init and so on. Everything in this lesson works with either binary.

Enable tab completion and keep your editor happy: install the official HashiCorp Terraform extension for VS Code (syntax highlighting, formatting, validation) or the Terraform plugin for JetBrains IDEs.

Your first configuration

Make an empty folder, called a working directory or root module, and create a file named main.tf:

HCL
terraform {
  required_version = ">= 1.6"
  required_providers {
    local = {
      source  = "hashicorp/local"
      version = "~> 2.5"
    }
    random = {
      source  = "hashicorp/random"
      version = "~> 3.6"
    }
  }
}

resource "random_pet" "name" {
  length = 2
}

resource "local_file" "greeting" {
  filename = "${path.module}/greeting.txt"
  content  = "Hello from ${random_pet.name.id}!\n"
}

output "file_path" {
  value = local_file.greeting.filename
}

What each part does:

  • The terraform block pins the Terraform version and says which providers you need and from where (hashicorp/local is the registry address).
  • random_pet is a resource that generates a random two-word name such as happy-otter. It needs no cloud.
  • local_file writes a text file. Its content uses random_pet.name.id, which refers to the other resource; that reference is how Terraform learns the pet must exist first.
  • output prints a value after apply.

The configuration uses no credentials and changes nothing outside this folder, which makes it a safe first experiment.

terraform init

Terminal
terraform init

init prepares the folder. It downloads the providers you listed into a hidden .terraform/ directory and writes .terraform.lock.hcl, which records exactly which provider versions (and checksums) were chosen. You commit the lock file to Git so teammates use identical providers; you do not commit .terraform/. Run init again whenever you add a provider or module.

TEXT
Initializing the backend...
Initializing provider plugins...
- Installing hashicorp/local v2.5.3...
- Installing hashicorp/random v3.7.2...

Terraform has been successfully initialized!

(Example output.)

terraform plan

Terminal
terraform plan

plan reads the configuration, reads the state (empty at first) and prints what it would do. Nothing changes yet.

TEXT
Terraform will perform the following actions:

  # local_file.greeting will be created
  + resource "local_file" "greeting" {
      + content  = (known after apply)
      + filename = "./greeting.txt"
      + id       = (known after apply)
    }

  # random_pet.name will be created
  + resource "random_pet" "name" {
      + id        = (known after apply)
      + length    = 2
      + separator = "-"
    }

Plan: 2 to add, 0 to change, 0 to destroy.

(Example output.) The symbols matter: + create, - destroy, ~ update in place, -/+ replace (destroy then create). "(known after apply)" marks values that only exist once the real thing is created, such as the random name.

Python A toy plan printer (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

terraform apply

Terminal
terraform apply

apply prints the plan again and asks you to type yes. Terraform then creates resources in dependency order and writes the state to a local file named terraform.tfstate.

TEXT
random_pet.name: Creating...
random_pet.name: Creation complete after 0s [id=happy-otter]
local_file.greeting: Creating...
local_file.greeting: Creation complete after 0s [id=2f1c...]

Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

Outputs:

file_path = "./greeting.txt"

(Example output.) A greeting.txt file now exists. Run terraform plan once more and it says No changes. Your infrastructure matches the configuration. That is idempotence at work.

Now edit length = 3 and plan again. Because random_pet cannot change its length in place, the plan shows -/+ (replace), and the file's content changes too, since it depends on the pet name. You will learn why in lifecycle.

Python Apply twice (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

terraform destroy

Terminal
terraform destroy

destroy plans the removal of everything in the state and asks for yes. Use it to clean up experiments. On a real cloud this is the command that stops the bill, so get used to running it after practice sessions.

Files Terraform creates

File or folder Commit to Git? Purpose
main.tf and other .tf files Yes Your configuration
.terraform.lock.hcl Yes Locked provider versions and checksums
.terraform/ No Downloaded providers and modules
terraform.tfstate No State; may contain secrets (see State chapter later)
*.tfvars with secrets No Variable values (see input variables)

A common .gitignore for Terraform projects:

TEXT
.terraform/
*.tfstate
*.tfstate.*
crash.log
*.tfvars
!example.tfvars

Useful companion commands

  • terraform fmt rewrites files into the canonical style (two-space indentation, aligned =). Run it before every commit.
  • terraform validate checks syntax and internal consistency without calling any API.
  • terraform output prints output values from the state.
  • terraform show prints the state or a saved plan in readable form.

Add -auto-approve to apply or destroy only in automation. When you type commands yourself, the confirmation prompt is your last safety net.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does terraform init do?

    init installs the providers (and modules) you declared into .terraform/ and writes the dependency lock file. It does not change infrastructure.
  2. 2. Which file should be committed to Git so that teammates get the same provider versions?

    The lock file records the chosen provider versions and checksums. The .terraform directory and the state file stay out of version control.
  3. 3. In a plan, what does the symbol -/+ mean?

    -/+ is a replacement: Terraform destroys the old object and creates a new one, because the change cannot be made in place.
  4. 4. You run terraform apply twice without editing anything. What does the second plan show?

    State and configuration already match reality, so the plan is empty.

Summary

  • Terraform is one binary; install it with a package manager or a zip. OpenTofu uses tofu instead.
  • A root module is a folder of .tf files. terraform blocks pin versions; resource blocks declare things; output blocks print values.
  • init downloads providers, plan previews changes, apply performs them, destroy removes everything.
  • Commit .tf files and .terraform.lock.hcl; never commit .terraform/ or state files.
  • fmt and validate keep files tidy and consistent.

Next: The Core Terraform Workflow