Configuration and Working Directories

Scenario: A brand-new engineer runs terraform plan and gets "no configuration files found" - the command ran one directory above the intended project root, and Terraform has no idea which files were meant.

Terraform has to know exactly where your configuration lives before it can do anything. A root module is simply the folder you run Terraform commands from: Terraform loads every .tf (and .tf.json) file sitting directly in that folder and treats them as one combined configuration. Crucially, the filenames and the order the files sit in do not determine execution order - you already learned in the previous module that the dependency graph decides ordering, not file position, so splitting a project across main.tf, variables.tf, and outputs.tf is purely a human-readability convention.

When you first run terraform init (next section) inside a root module, it creates a hidden .terraform/ folder holding downloaded provider plugins and any modules you referenced, plus a .terraform.lock.hcl file recording exactly which provider versions were selected. Both are generated, reproducible artifacts - like a node_modules folder in JavaScript projects. Keep .terraform/, state files, and plan files out of Git; commit only your .tf configuration files and the lock file.

Analogy: A root module is like a compiled software project: several source files (.tf files) combine into one program, and the build cache (.terraform/) that gets generated along the way is not itself source code you'd commit or hand-edit.

A worked configuration

terraform {
  required_providers {
    fakecloud = {
      source  = "shellgenius/fakecloud"
      version = "~> 1.0"
    }
  }
}

In a real repository, make the execution boundary obvious from the folder structure alone. A junior engineer opening a directory should immediately know "running Terraform here only affects this one service's infrastructure," not an entire company's estate. A short README in each root stating the backend in use, required credentials, who owns it, and the exact commands to run saves enormous confusion during an incident, when the person reading it is stressed and has never touched this project before.

Common mistakes in production

• Running terraform commands from the wrong directory (a parent folder, or a sibling service's folder) - Terraform will happily plan against whatever .tf files it finds there, which may belong to a completely different system.
• Committing the generated .terraform/ directory to Git - it's large, machine-specific, and gets regenerated by init anyway.

Goal: Treat the plan as a change contract: understand every create, update, replacement, and destroy before approving it. Reinforce this lesson in the tf-version-lockfile Terraform lab. Open /labs/terraform and choose slug tf-version-lockfile; the lab runs real Terraform against the offline FakeCloud provider.