Introduction
Terraform Core is built on a sophisticated architecture that enables declarative infrastructure management through a well-defined workflow. Understanding these core concepts is essential for working with Terraform effectively, whether you’re using it as an operator or contributing to its development.The Terraform Workflow
At the highest level, Terraform follows a consistent pattern for managing infrastructure:Core Architecture Components
Terraform’s architecture consists of several interconnected subsystems that work together to execute infrastructure operations:Configuration Layer
The configuration layer handles parsing and validation of Terraform configuration files:- Configuration Loader (
internal/configs) - Parses.tffiles and builds a hierarchical configuration model - Module System - Manages composition and reuse of configuration through modules
- Expression Evaluation (
internal/lang) - Interprets HCL expressions and references
Configuration files use HCL (HashiCorp Configuration Language), which is parsed into an Abstract Syntax Tree (AST) that Terraform processes during the graph walk.
Execution Engine
The core execution engine orchestrates all Terraform operations:- Context (
terraform.Context) - The central coordinator for all Terraform operations - Graph Builder - Constructs dependency graphs for different operations (plan, apply, destroy)
- Graph Walker - Traverses graphs and executes vertices in dependency order
- Vertex Execution - Performs the actual work at each graph node
State Management
State management tracks the current state of managed infrastructure:- State (
states.State) - In-memory representation of infrastructure state - State Manager (
statemgr) - Persists state to storage backends - Sync State - Provides thread-safe concurrent access to state during graph walks
Provider System
Providers are the plugins that interact with external APIs:- Provider Plugins - Implement CRUD operations for specific platforms
- Provider Protocol - gRPC-based communication between Core and providers
- Schema System - Defines resource types and their attributes
Key Design Principles
Infrastructure as Code
Terraform treats infrastructure configuration as source code that can be versioned, reviewed, and tested. The declarative approach focuses on describing the desired end state rather than the steps to achieve it.Learn more about Infrastructure as Code principles in the Infrastructure as Code guide.
Immutable Execution Plans
Plans are immutable snapshots of proposed changes that can be reviewed before execution. This separation of planning and execution enables:- Safe review workflows
- Predictable infrastructure changes
- Audit trails of what changed and why
Explore how plans work in the Execution Plans documentation.
Dependency Graphs
Terraform automatically builds directed acyclic graphs (DAGs) to determine the correct order of operations based on resource dependencies.Understand graph construction in the Resource Graph guide.
State as Source of Truth
The state file serves as the source of truth for what infrastructure exists, enabling Terraform to calculate the difference between desired and actual state.Dive deeper into state management in the State Management documentation.
Request Flow
Here’s how a typical Terraform command flows through the system:This diagram shows the simplified flow. The actual implementation in
internal/terraform/ includes additional steps for validation, optimization, and error handling.Operation Types
Terraform Core supports several operation types, each with its own graph builder:| Operation | Purpose | Graph Builder |
|---|---|---|
| Plan | Calculate proposed changes | PlanGraphBuilder |
| Apply | Execute a plan | ApplyGraphBuilder |
| Refresh | Update state from remote | Specialized refresh graph |
| Validate | Check configuration syntax | Validation graph |
| Destroy | Remove all resources | Destroy graph variant |
Concurrency and Parallelism
Terraform executes operations concurrently when possible:- Default parallelism: 10 concurrent operations
- Configurable via
-parallelismflag - Thread-safe state access via
SyncState - Graph walker respects dependencies while maximizing parallelism
Module System
Modules enable composition and reuse:- Root Module - The main configuration directory
- Child Modules - Reusable configuration components
- Module Instances - Specific instantiations via
countorfor_each - Module Expansion - Dynamic graph expansion for module instances
Next Steps
Now that you understand the high-level architecture, explore each core concept in detail:Infrastructure as Code
Learn how Terraform implements declarative infrastructure management
Execution Plans
Understand how Terraform calculates and represents changes
Resource Graph
Explore how dependency graphs enable correct operation ordering
State Management
Discover how Terraform tracks infrastructure state