Home

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• BUGPROCESS.md
• internal/cloud/backend.go
• internal/command/test_test.go
• internal/plans/planproto/planfile.proto
• scripts/changelog.sh
• internal/command/e2etest/automation_test.go
• internal/cloud/e2e/migrate_state_multi_to_tfc_test.go
• website/README.md

Terraform is a tool for building, changing, and versioning infrastructure safely and efficiently. It uses a high-level configuration syntax to describe infrastructure, allowing a blueprint of a datacenter to be versioned, shared, and reused. This document provides a high-level overview of the Terraform Core project, its key features, and its development processes.

The core of the project includes the command-line interface (CLI) and the main graph engine. Providers, which manage specific services, are implemented as plugins and can be automatically downloaded from the Terraform Registry.

Sources: README.md

Core Concepts

Terraform's workflow is built on several key concepts that ensure safe and efficient infrastructure management.

Sources: README.md:12-28

Execution Plans

Terraform features a "planning" step that generates an execution plan. This plan details the actions Terraform will take to modify the infrastructure to match the desired state in the configuration. This allows operators to review changes before they are applied, preventing surprises. The structure of a plan is defined in a protocol buffer format.

Sources: README.md:18-20, internal/plans/planproto/planfile.proto

The diagram below shows the high-level structure of a Terraform plan file.

Resource Graph

Terraform builds a dependency graph of all resources defined in the configuration. This allows it to parallelize the creation and modification of any non-dependent resources, leading to efficient infrastructure provisioning. The graph also provides operators with insight into the dependencies within their infrastructure.

Sources: README.md:22-25

Change Automation

Complex changesets can be applied to infrastructure with minimal human interaction. The combination of the execution plan and the resource graph provides a clear understanding of what Terraform will change and in what order, which helps to avoid many potential human errors.

Sources: README.md:27-30

HCP Terraform Integration (cloud backend)

Terraform Core integrates deeply with HCP Terraform and Terraform Enterprise through the cloud backend. This backend is an implementation detail and not directly configured by users in the same way as other backends. It facilitates both remote operations on HCP Terraform and using HCP Terraform as a state storage backend for local operations.

Sources: internal/cloud/backend.go:42-46, internal/cloud/backend.go:498-501

Configuration

The cloud backend is configured through a combination of the cloud block in a Terraform configuration file and environment variables.

Attribute	Type	Environment Variable	Description
hostname	string	TF_CLOUD_HOSTNAME	The Terraform Enterprise hostname. Defaults to app.terraform.io for HCP Terraform.
organization	string	TF_CLOUD_ORGANIZATION	The name of the organization containing the target workspaces. This is a required field.
token	string	-	The authentication token. It is recommended to use terraform login instead of setting this directly.
workspaces	object	-	A block to configure workspace mapping using either a name or tags.
workspaces.name	string	TF_WORKSPACE	The name of a single workspace to use. Conflicts with tags.
workspaces.tags	set/object	-	A set of tags (or key/value map) to select remote workspaces. Conflicts with name.
workspaces.project	string	TF_CLOUD_PROJECT	The name of the project where workspaces will be created.

Sources: internal/cloud/backend.go:149-188, internal/cloud/backend.go:535-555, internal/cloud/backend.go:1388-1419

The following diagram illustrates the logic for resolving the final configuration from file blocks and environment variables.

Operation Modes

When using the cloud backend, Terraform can execute operations either remotely on HCP Terraform/TFE or locally.

• Remote Execution: This is the default mode for workspaces with operations enabled. plan and apply commands are executed within the HCP Terraform environment.
• Local Execution: Operations run on the local machine, using HCP Terraform as a remote state backend. This mode is activated if:
  • The TF_FORCE_LOCAL_BACKEND environment variable is set.
  • The remote workspace has its "Execution Mode" set to "local".

The Operation function in the cloud backend determines which mode to use.

Sources: internal/cloud/backend.go:498-501, internal/cloud/backend.go:872-879

This sequence diagram shows how Terraform decides whether to run an operation locally or remotely.

Development and Contribution

The project has well-defined processes for handling bugs and managing releases.

Bug Triage Process

The bug triage process aims to quickly categorize and clarify new bug reports. Issues move through several stages, managed by labels on GitHub.

Label	Description
new	A new issue that has not yet been triaged.
waiting for reproduction	The issue could not be reproduced and requires more information.
confirmed	A core team member has reproduced the issue.
explained	A core team member has described the root cause of the issue in the code.
working as designed	The reported behavior is intended.
duplicate	The issue is already tracked by another issue.
not reproducible	A reproduction case could not be generated.
pending project	The issue is confirmed but requires a significant project to fix.

Source: BUGPROCESS.md:100-110

The lifecycle of a bug report is illustrated below.

Release Process

The release process is managed by the changelog.sh script, which automates updating the CHANGELOG.md and version files. It supports several types of releases.

Testing Framework

Terraform includes a dedicated testing framework invoked via the terraform test command. This allows developers to write automated tests for their modules in HCL.

Test Execution Flow

Tests are defined in *.tftest.hcl files. Each file can contain multiple run blocks, which define a specific test case. A run block executes a Terraform command (like plan or apply) and then runs assert blocks to validate the outcome.

The general flow of a test execution is as follows:

1. Terraform initializes the configuration.
2. It discovers all *.tftest.hcl files.
3. For each run block, it executes the specified command.
4. It evaluates the assert conditions within the run block.
5. After all runs in a file are complete, it performs a cleanup (destroy) operation.

Sources: internal/command/test_test.go:40-70, internal/command/test_test.go:1070-1100

Running in Automation

Terraform is designed to be run in automated CI/CD pipelines. Setting the TF_IN_AUTOMATION environment variable to any non-empty value adjusts Terraform's output to be more machine-friendly, suppressing interactive prompts and unnecessary human-oriented text. Common automation workflows include init -> plan -> apply or init -> apply -auto-approve.

Source: internal/command/e2etest/automation_test.go:27-33, internal/command/e2etest/automation_test.go:121-124

Conclusion

Terraform Core provides a powerful and extensible foundation for Infrastructure as Code. Its key strengths lie in its declarative configuration, predictable execution plans, and dependency-aware resource graph. The integration with HCP Terraform via the cloud backend enables advanced features like remote state management, collaborative workflows, and policy enforcement. The project's mature development practices, including a structured bug triage system and a robust testing framework, ensure its stability and reliability for managing critical infrastructure.

Sources: README.md, internal/cloud/backend.go, BUGPROCESS.md