Core Features & Commands

Relevant source files

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

• README.md
• main.go
• internal/plans/planproto/planfile.proto
• internal/cloud/backend.go
• internal/command/test_test.go
• internal/command/fmt_test.go
• CHANGELOG.md
• BUGPROCESS.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 blueprints of datacenters to be versioned, shared, and reused. This document provides an overview of Terraform's core features and the primary commands that drive its workflow.

The main principles of Terraform revolve around Infrastructure as Code, Execution Plans, a Resource Graph, and Change Automation. These principles enable users to manage infrastructure with confidence, avoiding surprises and human error. The core workflow consists of writing configuration, planning changes, and applying those changes.

Sources: README.md

Core Features

Terraform's design is centered around several key features that facilitate safe and efficient infrastructure management.

Feature	Description
Infrastructure as Code	Infrastructure is described using a high-level configuration syntax. This allows a blueprint of your datacenter to be versioned and treated as you would any other code.
Execution Plans	Terraform has a "planning" step where it generates an execution plan. The plan shows what Terraform will do when apply is called, preventing surprises.
Resource Graph	Terraform builds a graph of all resources, parallelizing the creation and modification of any non-dependent resources for maximum efficiency.
Change Automation	Complex changesets can be applied to infrastructure with minimal human interaction, reducing the risk of human error.

Sources: README.md

Command-Line Interface (CLI)

The Terraform CLI is the primary interface for managing infrastructure. The main entry point parses arguments and dispatches to the appropriate command. It supports global options like -chdir to change the working directory before executing a command.

The CLI also processes arguments from environment variables, such as TF_CLI_ARGS for general arguments and TF_CLI_ARGS_<command> for command-specific arguments.

Sources: main.go:102-120, main.go:204-240

Standard Workflow Commands

The standard Terraform workflow is executed through a series of commands.

This diagram shows the standard Terraform workflow, from writing configuration to provisioning infrastructure.

Sources: README.md

terraform init

The init command is used to initialize a working directory containing Terraform configuration files. This is the first command that should be run after writing a new Terraform configuration. It performs several initialization steps:

• Backend Initialization: Configures the backend where state snapshots are stored.
• Child Module Installation: Downloads and installs modules from sources like the Terraform Registry.
• Plugin Installation: Downloads and installs the necessary provider plugins.

The init command can be run with -input=false for automation, and it will configure the backend based on the terraform block in the configuration files.

Sources: internal/command/e2etest/automation_test.go:37-46, internal/command/cloud_test.go:136-141

terraform plan

The plan command creates an execution plan, which lets you preview the changes that Terraform plans to make to your infrastructure. By default, creating a plan consists of:

1. Reading the current state of any already-existing remote objects to make sure it is up-to-date.
2. Comparing the current configuration to the prior state and noting any differences.
3. Proposing a set of change actions that would, if applied, make the remote objects match the configuration.

The output of terraform plan is a binary plan file. The structure of this file is defined by a Protocol Buffers schema.

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

Plan File Structure

The plan file is a serialized Plan message. The diagram below illustrates its key components.

This diagram shows the main entities within a Terraform plan file and their relationships, as defined in the protobuf schema.

Sources: internal/plans/planproto/planfile.proto

Key fields in the Plan message include:

Field	Description
version	The serialization format version.
applyable	true if the plan can be safely applied.
complete	true if the plan includes an action for every resource.
errored	true if an error occurred during plan creation.
resource_changes	A set of proposed changes to resource instances.
resource_drift	Detected changes made to resources outside of Terraform.
output_changes	Proposed changes to root module outputs.
terraform_version	The version of the Terraform binary that created the plan.
backend	A description of the backend configuration at plan time.

Sources: internal/plans/planproto/planfile.proto:8-118

terraform apply

The apply command executes the actions proposed in a Terraform plan. It can be run with a plan file generated by terraform plan or without one, in which case it will automatically create a new plan and prompt for approval before applying it.

For automation, it is recommended to use a saved plan file to ensure that only the exact changes previewed are applied.

terraform apply "tfplan"

The apply process can be run with -auto-approve to skip the interactive approval, which is useful in automated CI/CD pipelines.

Sources: internal/command/e2e/automation_test.go:103-107, internal/command/e2etest/automation_test.go:160-162

Utility Commands

Terraform includes several utility commands to help manage configurations and state.

terraform fmt

The fmt command is used to rewrite Terraform configuration files to a canonical format and style. This command applies a subset of the Terraform language style conventions, along with other minor adjustments for readability.

It can operate on individual files, directories, or from standard input (-). The command will format .tf and .tf.json files by default. Tests indicate it also formats .tftest.hcl and .tfquery.hcl files.

Sources: internal/command/fmt_test.go:18-154

terraform test

The terraform test command runs automated tests on the modules in the configuration. Test files, typically ending in .tftest.hcl, define run blocks that execute plan or apply operations and assert conditions on the results.

Key features of terraform test include:

• Run Blocks: Define a sequence of operations to test. Each run block can have its own variables and provider configurations.
• Assertions: assert blocks check for expected outcomes, comparing output values, resource attributes, and other conditions.
• Mocking: The ability to mock providers and their data, allowing for unit-style testing without real infrastructure.
• Cleanup: Terraform automatically destroys any infrastructure created during a test run, though this can be skipped for debugging. If cleanup fails, a manifest of leftover resources is created.

The following diagram illustrates the lifecycle of a test run.

This flowchart shows the execution flow of the terraform test command, from loading test files to reporting results.

Sources: internal/command/test_test.go

Cloud Integration

Terraform has deep integration with HCP Terraform and Terraform Enterprise, managed through the cloud backend. This backend enables remote operations, state storage, and more.

Configuration

The cloud backend is configured in the terraform block of a .tf file.

terraform {
  cloud {
    organization = "my-org"
    workspaces {
      name = "my-workspace" # or tags
    }
  }
}

The configuration resolves settings from the config block, environment variables (TF_CLOUD_HOSTNAME, TF_CLOUD_ORGANIZATION), and defaults.

Sources: internal/cloud/backend.go:118-154, internal/cloud/backend.go:440-541

Remote Operations

When the cloud backend is configured, commands like plan and apply can execute remotely on HCP Terraform workers. This provides a consistent execution environment and centralized management of runs.

The following diagram shows the sequence of a remote apply operation.

This sequence diagram illustrates the interactions between the local CLI and the HCP Terraform API during a remote apply operation.

Sources: internal/cloud/backend.go:872-965

Bug and Changelog Process

The project maintains a structured process for bug triage and changelog generation.

• Bug Triage: New issues are filtered, categorized, and reproduced by the core team. Labels like new, confirmed, explained, and working as designed track the issue lifecycle. This process aims to get bugs ready for engineering to fix or to close them with an explanation.
  Sources: BUGPROCESS.md

• Changelog Generation: A script, scripts/changelog.sh, automates the update of CHANGELOG.md. It uses changie to merge unreleased changes into a new version section. The script supports different release types like dev, alpha, beta, rc, patch, and release.
  Sources: scripts/changelog.sh:20-130

Summary

Terraform provides a powerful and robust set of features and commands to manage infrastructure as code. The core workflow of init, plan, and apply ensures a safe and predictable process for infrastructure changes. Utility commands like fmt and test enhance developer productivity and code quality. Furthermore, the seamless integration with HCP Terraform μέσω the cloud backend enables collaboration, governance, and automation at scale.