DEV Community

1suleyman
1suleyman

Posted on

🛠️ Terraform Tips You’ll Wish You Knew Earlier (Bug Reporting, Code Formatting, and File Structure)

#terraform #aws #beginners #documentation

Hey everyone 👋

If you're learning Terraform — whether for cloud engineering, DevOps, or just building better infrastructure — you've probably run into moments where something breaks, the code looks messy, or the file structure becomes a mess.

Been there.

Today I want to walk you through three essential concepts every Terraform user should know:

  • 🐛 How to troubleshoot and report Terraform bugs
  • 🎨 How to clean up your code with terraform fmt
  • 📦 How Terraform loads .tf files — and why file structure matters in production

Let’s break it down the way I wish someone had for me early on 👇

🐛 1. Terraform Bug Reporting — Know Where to Look Before You Blame Yourself

Terraform errors aren’t always your fault.

When you run terraform plan or apply and get a cryptic error, it’s tempting to assume your syntax is wrong — but sometimes the bug lies deeper:

Here’s how I think about Terraform errors:

🧩 Layer 🛠️ What Might Break
Language HCL syntax errors (your code)
State State file out of sync or locked
Core Terraform engine bug
Provider AWS/GCP/etc. plugin-specific bugs

If your config looks fine, and your state is clean, but something’s still not working — it might be a Terraform core bug or a provider plugin bug.

🧑‍💻 How to Report a Bug (Properly)

  1. Visit the correct GitHub repo:
  • Terraform Core

  • AWS Provider

    1. Click "New Issue"
    2. Fill out the Bug Report template:

  • Terraform version

  • Config snippet

  • Debug output (TF_LOG=TRACE)

  • Expected vs actual behavior

  • Steps to reproduce

✅ Real engineers will look at this — so be kind, clear, and detailed.

🎨 2. terraform fmt — Because Sloppy Code Is Like a Messy Desk

Just like in regular programming, formatting matters. Sloppy code is harder to read, maintain, and debug.

Terraform gives us a simple fix:

terraform fmt
Enter fullscreen mode Exit fullscreen mode

That’s it. It will:

  • Align your = signs
  • Fix your indentation
  • Clean up the structure

Here’s a before and after:

# Before
provider "aws" {region= "us-east-1"
access_key= "abc"
secret_key="xyz"}

# After
provider "aws" {
  region     = "us-east-1"
  access_key = "abc"
  secret_key = "xyz"
}
Enter fullscreen mode Exit fullscreen mode

💡 Bonus: You can run it recursively through subfolders with:

terraform fmt -recursive
Enter fullscreen mode Exit fullscreen mode

It won’t fix syntax errors — that’s what terraform validate is for — but it will make your code look like it came from a seasoned DevOps engineer 😎

📦 3. Load Order & Semantics — How Terraform Loads Files (And Why Structure Matters)

Here’s something I didn’t know at first:

Terraform loads all .tf and .tf.json files in a directory alphabetically — and treats them like one giant configuration.

This means:

  • You don’t need one huge main.tf
  • You can split your code across multiple files
  • Terraform will read them all — regardless of file name — as long as they end in .tf

🗂️ Recommended File Structure (For Production)

📄 File Name 💡 Purpose
provider.tf Cloud provider config
variables.tf All variable declarations
ec2.tf EC2-related resources
iam_user.tf IAM user resources

🧠 Why This Helps:
When your team grows, or you revisit code after weeks — proper naming makes it easy to find what you need. Want to add a new IAM user? Go to iam_user.tf. Easy.

⚠️ Watch Out for Duplicate Resource Names

If you define two blocks with the same name:

resource "aws_instance" "myec2" { ... }
resource "aws_instance" "myec2" { ... } # ❌ Error
Enter fullscreen mode Exit fullscreen mode

Terraform will scream:

Resource already declared.

✅ Fix it like this:

resource "aws_instance" "myec2" { ... }
resource "aws_instance" "newec2" { ... }
Enter fullscreen mode Exit fullscreen mode

💡 Each resource is uniquely identified by its type and name.

🧠 Final Thoughts

Learning Terraform is like learning a new language — and these three concepts are part of the grammar:

  • Format your code with terraform fmt to make it clean and readable.
  • Split your files across logical groups to make collaboration and maintenance easier.
  • Understand the error layers so you don’t waste time debugging things that aren’t your fault.

And when all else fails — report the bug like a pro.

I’m still learning Terraform every day, and sharing what I learn one block at a time.

Let me know if you’ve ever run into a weird Terraform bug — or if you’ve got tips for keeping code clean and organized. Let’s connect on LinkedIn! 💬

Top comments (0)