Installation and Configuration

Before you can manage infrastructure with Terraform, you need the Terraform CLI installed and a clean working directory in which Terraform can operate. Installation itself is straightforward; understanding what Terraform creates around your configuration is what will save you confusion later.

Installing Terraform

Terraform is distributed as a command-line application. You can install it using the method appropriate for your operating system, then verify that the executable is available on your PATH.

Use the official installation instructions for your platform rather than copying an installation command from an unrelated tutorial. Terraform releases change over time, and package-manager availability differs between operating systems.

After installation, verify it:

terraform version

You should see the installed Terraform version and the platform for which the executable was built.

For example, the exact version will depend on what you installed:

Terraform vX.Y.Z
on linux_amd64

The important part is that Terraform responds successfully.

Terraform Versions Matter

Terraform configurations are interpreted by a particular Terraform language implementation, and providers have their own independent release cycles.

That means there are at least two version concepts to keep in mind:

Terraform CLI
     │
     └── Terraform language + CLI behavior

Provider
     │
     └── Provider resources + provider behavior

Do not assume that upgrading Terraform also upgrades your providers. They are separate dependencies.

For a project that needs to remain reproducible, it is useful to declare which Terraform versions the configuration supports. A terraform block can contain a required_version constraint.

For example:

terraform {
  required_version = ">= 1.9.0, < 2.0.0"
}

The exact constraint you choose should be based on the versions your project supports. Do not blindly copy the example into production.

When Terraform encounters a configuration whose required version is incompatible with the installed CLI, it can stop before attempting to manage the infrastructure.

A Terraform Configuration Directory

Terraform works with a configuration directory.

A simple directory might look like this:

my-project/
├── main.tf
├── variables.tf
└── outputs.tf

The .tf files are Terraform configuration files.

One important point often surprises people:

Terraform does not treat one .tf file as the program and another .tf file as something that runs later.

Terraform loads the configuration files in the directory together as one configuration.

So these two files:

main.tf
providers.tf

are not two sequential scripts. Terraform combines the configuration represented by both files when evaluating the module.

The file split exists primarily to make a configuration easier for humans to navigate.

What Is .terraform/?

After you initialize a configuration, Terraform commonly creates a .terraform directory.

For example:

my-project/
├── .terraform/
├── main.tf
└── .terraform.lock.hcl

This directory contains Terraform’s working data, including installed provider packages and other initialization-related information.

You should generally not treat .terraform/ as part of your source configuration.

A common Git ignore entry is:

.terraform/

The important distinction is:

.tf files
    = your configuration

.terraform/
    = Terraform's local working data

Terraform can recreate the working directory contents when you initialize the configuration again.

What Is .terraform.lock.hcl?

Initialization also commonly creates a dependency lock file:

.terraform.lock.hcl

This file records the provider selections Terraform made, along with checksums for the provider packages.

That matters because a provider may have several compatible versions.

Suppose your configuration says:

terraform {
  required_providers {
    example = {
      source  = "example/vendor"
      version = "~> 1.5"
    }
  }
}

The version constraint describes which versions are acceptable. The lock file records the particular version Terraform selected.

The distinction is:

Configuration
    │
    └── acceptable provider versions

Lock file
    │
    └── selected provider version + checksums

This makes repeated initialization more predictable.

Unlike .terraform/, the lock file should normally be committed to version control. When several people work on the same Terraform configuration, they should generally use the same provider selections unless intentionally changing them.

If you intentionally want Terraform to reconsider the selected provider versions, terraform init -upgrade can be used.

Environment Variables

Terraform uses environment variables in several places.

Some are used by Terraform itself. Others are used by providers for configuration or authentication.

For example, a provider may support credentials supplied through environment variables rather than placing credentials directly in a .tf file.

This is useful because configuration can remain free of credentials:

Terraform configuration
        │
        ├── infrastructure definition
        │
        └── no hard-coded secret

Environment
        │
        └── credentials supplied at runtime

Terraform also recognizes environment variables for some CLI behavior and variable inputs. You will see the variable-specific mechanism later in the course.

The important lesson is that environment variables are one possible input mechanism, not a universal secret-management system.

Handling Credentials Safely

Avoid putting long-lived credentials directly into Terraform configuration files.

For example, avoid a pattern like:

provider "example" {
  token = "super-secret-value"
}

A credential written into a configuration file can end up in:

• Git history
• pull requests
• backups
• shared directories
• logs
• Terraform artifacts

Use the authentication mechanisms recommended by the provider and your operating environment instead.

For cloud providers, prefer the provider’s supported authentication mechanisms and short-lived or externally managed credentials where appropriate. The exact authentication method depends on the provider and environment.

A Clean Project Workflow

A useful initial workflow is:

mkdir terraform-example
cd terraform-example

Create your Terraform configuration files in this directory.

Then initialize the directory:

terraform init

After initialization, you will normally see:

terraform-example/
├── .terraform/
├── .terraform.lock.hcl
└── your .tf files

At this point Terraform has prepared the working directory and installed the dependencies required by the configuration.

You can inspect the installed Terraform version at any time:

terraform version

And once you have a valid configuration, you can ask Terraform to validate it:

terraform validate

Initialization must happen before validation when the configuration depends on provider information that Terraform needs to load.

What Should Go Into Version Control?

For a typical Terraform project, the important source files and the dependency lock file belong in version control.

A simplified example:

terraform-example/
├── main.tf
├── variables.tf
├── outputs.tf
├── .terraform.lock.hcl
├── terraform.tfstate
└── .gitignore

The .terraform/ directory is normally excluded:

.terraform/

Do not commit credentials just because they happen to be stored in a Terraform-related file. Treat secrets as secrets regardless of whether Terraform is involved.

The general rule is:

Commit:
    Terraform configuration
    .terraform.lock.hcl

Usually ignore:
    .terraform/

Never casually commit:
    credentials and secrets
    terraform.tfstate

Before You Continue

You should now be able to distinguish three things that are often confused:

That distinction becomes especially useful when you run terraform init for the first time in the next hands-on exercises.

Terraform installation gets the CLI onto your machine, but installation is only the beginning. The next step is to put Terraform configuration into a directory and see how the language itself works.