Quickstart Guide

This quickstart guide will walk you through installing Terraform and creating your first infrastructure. You’ll learn the basic Terraform workflow: write, initialize, plan, and apply.

This guide uses the local provider to create a file on your local system. This is a simple example to demonstrate Terraform’s workflow without requiring cloud credentials.

Prerequisites

Before you begin, make sure you have:

A terminal or command prompt
Basic familiarity with the command line
Approximately 10 minutes

Step 1: Install Terraform

First, you’ll need to install Terraform on your system. The easiest way is to download a pre-built binary from the HashiCorp releases website.

macOS
Linux
Windows

Using Homebrew:

brew tap hashicorp/tap
brew install hashicorp/tap/terraform

Download and install:

wget https://releases.hashicorp.com/terraform/1.7.0/terraform_1.7.0_linux_amd64.zip
unzip terraform_1.7.0_linux_amd64.zip
sudo mv terraform /usr/local/bin/

Using Chocolatey:

choco install terraform

Verify the installation:

terraform version

You should see output showing the Terraform version number. For detailed installation instructions, see the Installation guide.

Step 2: Create Your First Configuration

Create a new directory for your Terraform project and navigate to it:

mkdir terraform-demo
cd terraform-demo

Create a file named main.tf with the following content:

main.tf

terraform {
  required_providers {
    local = {
      source  = "hashicorp/local"
      version = "~> 2.4"
    }
  }
}

provider "local" {}

resource "local_file" "hello" {
  filename = "${path.module}/hello.txt"
  content  = "Hello, Terraform!\n"
}

resource "local_file" "config" {
  filename = "${path.module}/config.json"
  content = jsonencode({
    message     = "Welcome to Terraform"
    environment = "development"
    timestamp   = "2024-03-15"
  })
}

output "hello_file_path" {
  description = "Path to the hello.txt file"
  value       = local_file.hello.filename
}

output "config_content" {
  description = "Content of the config file"
  value       = jsondecode(local_file.config.content)
}

This configuration uses the local provider to create two files on your local filesystem. The terraform block specifies the required provider, and the resource blocks define the infrastructure.

Step 3: Initialize Terraform

Before you can use Terraform, you need to initialize the working directory. This downloads the required provider plugins.

terraform init

You should see output similar to:

Initializing the backend...

Initializing provider plugins...
- Finding hashicorp/local versions matching "~> 2.4"...
- Installing hashicorp/local v2.4.1...
- Installed hashicorp/local v2.4.1 (signed by HashiCorp)

Terraform has been successfully initialized!

The terraform init command is safe to run multiple times. It will only download providers that aren’t already present.

Step 4: Preview Changes with Plan

Before creating any infrastructure, it’s a good practice to preview what Terraform will do:

terraform plan

Terraform will show you the execution plan:

Terraform will perform the following actions:

  # local_file.config will be created
  + resource "local_file" "config" {
      + content              = jsonencode(
            {
              + environment = "development"
              + message     = "Welcome to Terraform"
              + timestamp   = "2024-03-15"
            }
        )
      + filename             = "./config.json"
      + id                   = (known after apply)
    }

  # local_file.hello will be created
  + resource "local_file" "hello" {
      + content              = "Hello, Terraform!\n"
      + filename             = "./hello.txt"
      + id                   = (known after apply)
    }

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

The + symbol indicates that Terraform will create these resources.

Step 5: Apply the Configuration

Now, let’s create the infrastructure:

terraform apply

Terraform will show the plan again and ask for confirmation. Type yes to proceed:

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

After applying, you’ll see:

local_file.config: Creating...
local_file.hello: Creating...
local_file.hello: Creation complete after 0s [id=abc123...]
local_file.config: Creation complete after 0s [id=def456...]

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

Outputs:

config_content = {
  "environment" = "development"
  "message" = "Welcome to Terraform"
  "timestamp" = "2024-03-15"
}
hello_file_path = "./hello.txt"

Terraform has created two files in your directory: hello.txt and config.json. You can verify this by running ls or cat hello.txt.

Step 6: Modify Infrastructure

Let’s modify the configuration to see how Terraform handles changes. Edit main.tf and update the content of the hello file:

main.tf

resource "local_file" "hello" {
  filename = "${path.module}/hello.txt"
  content  = "Hello, Terraform! Updated at $(date)\n"
}

Run terraform plan again to see what will change:

terraform plan

You’ll see that Terraform detects the change and plans to update the resource:

  # local_file.hello must be replaced
-/+ resource "local_file" "hello" {
      ~ content  = "Hello, Terraform!\n" -> "Hello, Terraform! Updated...\n"
      ~ id       = "abc123..." -> (known after apply)
        # (1 unchanged attribute hidden)
    }

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

Apply the changes:

terraform apply

Step 7: Inspect State

Terraform keeps track of your infrastructure in a state file. You can inspect the current state:

terraform show

To see a list of resources in your state:

terraform state list

Step 8: Destroy Infrastructure

When you’re done experimenting, you can destroy the infrastructure:

terraform destroy

Terraform will show you what it plans to destroy and ask for confirmation. Type yes to proceed:

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

Do you really want to destroy all resources?
  Terraform will destroy all your managed infrastructure, as shown above.
  There is no undo. Only 'yes' will be accepted to confirm.

  Enter a value: yes

The terraform destroy command permanently deletes all resources managed by your Terraform configuration. Always double-check before confirming.

Understanding the Terraform Workflow

You’ve now experienced the core Terraform workflow:

Write

Define infrastructure in configuration files using HCL syntax

Initialize

Run terraform init to download provider plugins

Plan

Run terraform plan to preview changes

Apply

Run terraform apply to create or update infrastructure

Destroy

Run terraform destroy to clean up resources when done

Next Steps

Now that you understand the basics, explore these topics:

Core Concepts

Learn about providers, resources, variables, and state

CLI Reference

Explore all available Terraform commands

Configuration Language

Deep dive into HCL syntax and features

Cloud Providers

Work with AWS, Azure, GCP, and other providers

Common Commands Reference

Command	Description
`terraform init`	Initialize a working directory
`terraform validate`	Validate configuration files
`terraform plan`	Show changes required to reach desired state
`terraform apply`	Create or update infrastructure
`terraform destroy`	Destroy all managed infrastructure
`terraform fmt`	Format configuration files to canonical style
`terraform show`	Display the current state or a saved plan
`terraform state list`	List resources in the state
`terraform output`	Show output values

Use terraform -help to see all available commands, or terraform <command> -help for help with a specific command.

Getting Started

Core Concepts

Configuration Language

Workflow

State Management

Providers

Advanced Features

Prerequisites

Step 1: Install Terraform

Step 2: Create Your First Configuration

Step 3: Initialize Terraform

Step 4: Preview Changes with Plan

Step 5: Apply the Configuration

Step 6: Modify Infrastructure

Step 7: Inspect State

Step 8: Destroy Infrastructure

Understanding the Terraform Workflow

Next Steps

Core Concepts

CLI Reference

Configuration Language

Cloud Providers

Common Commands Reference

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Configuration Language

Workflow

State Management

Providers

Advanced Features

Documentation Index

​Prerequisites

​Step 1: Install Terraform

​Step 2: Create Your First Configuration

​Step 3: Initialize Terraform

​Step 4: Preview Changes with Plan

​Step 5: Apply the Configuration

​Step 6: Modify Infrastructure

​Step 7: Inspect State

​Step 8: Destroy Infrastructure

​Understanding the Terraform Workflow

​Next Steps

Core Concepts

CLI Reference

Configuration Language

Cloud Providers

​Common Commands Reference

Build docs developers (and LLMs) love

Prerequisites

Step 1: Install Terraform

Step 2: Create Your First Configuration

Step 3: Initialize Terraform

Step 4: Preview Changes with Plan

Step 5: Apply the Configuration

Step 6: Modify Infrastructure

Step 7: Inspect State

Step 8: Destroy Infrastructure

Understanding the Terraform Workflow

Next Steps

Common Commands Reference