OpenTofu: The Definitive Reference

Infrastructure as Code for Modern Cloud and On-Premises Environments

Chapter 1: The OpenTofu Story: From Terraform to Open Source

1. What Is OpenTofu?
2. The Terraform License Change: A Turning Point
3. HashiCorp vs. Linux Foundation: The Fork That Changed Everything
4. OpenTofu vs. Terraform: Compatibility, Differences, and Trade-offs
5. When to Choose OpenTofu (and When Not To)

Chapter 2: Architecture and Core Concepts

1. The Declarative Paradigm: What You Define vs. What Happens
2. OpenTofu’s Execution Model: Plan, Apply, Destroy
3. Providers: The Bridge Between Configuration and Reality
4. Resources: The Fundamental Building Blocks
5. State: Why It Exists and How It Works
6. Data Sources: Reading the World Without Creating It

Chapter 3: Installation and Project Structure

1. Installing OpenTofu: Linux, macOS, Windows, and Containerized Options
2. Verifying Your Installation and Checking Versions
3. The Minimal Working Project
4. Directory Layout Conventions: Single Project vs. Modular Organization
5. Configuration File Naming Rules: main.tf, variables.tf, and Beyond
6. .terraform-version, .gitignore, and Essential Project Files

Chapter 4: HCL Syntax and Language Fundamentals

1. Blocks, Arguments, Comments, and Basic Structure
2. Attributes and Types: Strings, Numbers, Booleans, Lists, Maps, Objects
3. Expressions: Interpolation, Conditionals, and Operators
4. For Expressions: Transforming Collections Elegantly
5. Dynamic Blocks: Generating Repetitive Configuration Programmatically
6. Null, Unknown, and Type Conversion: Gotchas Every Engineer Must Know

Chapter 5: Variables, Locals, and Outputs

1. Input Variables: Types, Defaults, Validation Rules, and Sensitive Values
2. Variable Files (.tfvars): Environment-Specific Configuration Management
3. Locals: Organizing Complex Logic and Avoiding Repetition
4. Outputs: Exposing Information and Connecting Modules
5. Passing Data Between Modules: The Parent-Child Contract

Chapter 6: Providers, Resources, and Data Sources in Depth

1. How Providers Work: Plugins, Authentication, and Configuration Blocks
2. Resource Arguments: Required, Optional, Computed, and Deprecated
3. Creating Resources Across Clouds: AWS, Azure, GCP Examples
4. Data Sources: Querying Existing Infrastructure Safely
5. Provider Aliases: Managing Multiple Configurations Simultaneously
6. Version Constraints: Pinning Providers for Stability

Chapter 7: State Management and Backends

1. Understanding State: What It Stores and Why Local Is Not Enough
2. Backend Types: Local, S3, Azure Blob, GCS, Consul, and More
3. Remote State Configuration: Locking, Encryption, and Versioning
4. Reading Remote State: Cross-Referencing Infrastructure Between Projects
5. State Migration: Moving Between Backends Safely
6. State Troubleshooting: Corruption, Drift, and Recovery Procedures

Chapter 8: Modules: Building Reusable Infrastructure Components

1. What Is a Module?: Root Modules, Child Modules, and Published Modules
2. Designing Your First Module: Inputs, Outputs, and Responsibility Boundaries
3. Calling Modules: Local Paths, Registry Sources, and Git Repositories
4. The OpenTofu Registry: Publishing and Consuming Community Modules
5. Advanced Module Patterns: Stacks, Composition, and Versioned Releases
6. Anti-Patterns: Monolithic Modules, Hidden Dependencies, and Over-Abstraction

Chapter 9: Workspaces, Lifecycle Rules, and Dependencies

1. Workspaces: Multiple Environments from One Configuration
2. When Workspaces Help (and When They Hurt): Practical Guidance
3. Lifecycle Arguments: create_before_destroy, prevent_destroy, ignore_changes
4. Dependency Management: Explicit depends_on vs. Implicit References
5. The Dependency Graph: Visualizing and Debugging Execution Order
6. Tainting Resources: Forcing Recreation When Needed

Chapter 10: Provisioners and Importing Existing Infrastructure

1. The Problem With Provisioners: Why They Are Discouraged
2. When Provisioners Make Sense: file, local-exec, remote-exec, and Beyond
3. Best Practices If You Must Use Provisioners: Idempotency and Error Handling
4. Importing Existing Resources: The import Command and Workflow
5. Generating Configuration for Imported Resources: State Inspection Techniques
6. Migration Strategies: Bringing Legacy Infrastructure Under OpenTofu Control

Chapter 11: Testing, Validation, Formatting, and Policy Enforcement

1. Formatting and Linting: tofu fmt, tofu validate, and Custom Rules
2. Pre-commit Hooks: Catching Errors Before They Reach the Repository
3. Testing Strategies: Unit Tests, Integration Tests, and Plan Validation
4. OpenTofu Test Framework: Built-in Testing Capabilities
5. Policy as Code: Sentinel, OPA, and openpolicyagent Integration
6. Security Scanning: Detecting Misconfigurations with tfsec, checkov, and Trivy

Chapter 12: Security Best Practices and Secrets Management

1. Securing State Files: Encryption at Rest and in Transit
2. Managing Secrets: Never Hardcoding Credentials
3. Provider Authentication Patterns: IAM Roles, Service Principals, Workload Identity
4. Least Privilege for OpenTofu Execution: IAM Policies and RBAC
5. Audit Logging and Compliance: Tracking Who Changed What and When
6. Common Security Pitfalls: Exposed Keys, Overly Permissive Policies, and Insecure Backends

Chapter 13: CI/CD Integration, GitOps, and Automation Workflows

1. The Infrastructure Pipeline: Commit, Plan, Review, Apply
2. GitHub Actions Integration: Complete Workflow Examples
3. GitLab CI, Jenkins, and Azure DevOps: Multi-Platform Pipeline Patterns
4. GitOps With OpenTofu: Declarative Deployment Using ArgoCD and Flux
5. Approval Gates and Change Management: Human Review in Automated Workflows
6. Parallel Execution and Performance Optimization: Scaling Plans and Applies

Chapter 14: Enterprise-Scale Patterns and Production Operations

1. Multi-Cloud and Hybrid Infrastructure: Managing AWS, Azure, GCP, and On-Premises Together
2. Organizational Structure: Team-Based Repository Layouts and Shared Responsibility
3. Environment Strategy: Development, Staging, Production Separation Patterns
4. Versioning and Upgrades: OpenTofu Versions, Provider Updates, and Breaking Changes
5. Debugging and Logging: Tracing Failures in Complex Deployments
6. Real-World Case Studies: Production Patterns from Leading Organizations

Conclusion: Delivering on the Infrastructure-as-Code Promise

References