Terraform Administrator & Architecture Guide

This guide is the deep, source-based reference for operators, platform engineers, and architects who deploy, integrate, secure, and extend Terraform — and for anyone who needs to understand how Terraform core actually works internally. It complements the User Guide, which covers day-to-day CLI usage. Where the User Guide shows you how to drive Terraform, this guide explains how it is built, what it requires, how to run it at scale, and how to keep it secure.

It documents Terraform 1.16.0-dev (Go 1.25.10, license BUSL-1.1). This repository is Terraform core only: the command-line interface and the graph engine. All cloud-specific logic lives in external provider plugins.

1. Executive Summary

Terraform is a single, statically-linked Go binary that turns declarative HCL configuration into ordered API calls against infrastructure platforms. Its defining architectural decisions are:

• Declarative + graph-based. Terraform builds a directed acyclic graph (DAG) of all resources and their dependencies, then walks it with bounded parallelism (default 10) to create, update, or destroy objects in the correct order.
• Plan/apply separation. Every change is first computed as a plan (a reviewable diff) and only then applied. Plans can be saved to a file and applied verbatim.
• Core/plugin split over gRPC. Terraform core contains no provider logic. Each provider and provisioner runs as a separate OS process, launched by core and driven over a gRPC protocol (go-plugin). This is why providers are independently versioned binaries downloaded from a registry.
• State as the source of record. Terraform records the mapping between configuration and real objects in state, stored locally or in one of 14 pluggable backends, with locking to make team workflows safe.

2. Architecture

2.1 High-level component map

                         ┌───────────────────────────────────────────────┐
   terraform CLI         │  main.go → realMain()                          │
   (package main)        │   • LoadConfig (CLI config, ~/.terraformrc)    │
                         │   • service discovery + credentials (svchost)  │
                         │   • providerSource / providerDevOverrides      │
                         │   • backendInit.Init(services)                 │
                         │   • initCommands() → Commands map              │
                         │   • hashicorp/cli runner dispatches subcommand │
                         └───────────────────┬───────────────────────────┘
                                             │ command.Meta (shared deps)
                  ┌──────────────────────────┼──────────────────────────┐
                  ▼                          ▼                           ▼
        ┌──────────────────┐     ┌───────────────────────┐    ┌──────────────────┐
        │ internal/command │     │  internal/configs     │    │ internal/backend │
        │  ~45 commands +  │     │  HCL parse → Config    │    │ local/remote/s3/ │
        │  arguments/views │     │  (blocks, schema)      │    │ gcs/azurerm/...  │
        └────────┬─────────┘     └───────────┬───────────┘    └────────┬─────────┘
                 │                            │                         │
                 ▼                            ▼                         ▼
        ┌─────────────────────────────────────────────────────────────────────┐
        │                       internal/terraform                             │
        │   Context.{Plan,Apply,Refresh,Validate,Import,Eval}                  │
        │   GraphBuilder (plan/apply/eval/init) → applies ~58 Transformers     │
        │   → DAG (internal/dag) → graph walk (parallelism N) → node Execute   │
        └───────────┬───────────────────────────────────┬─────────────────────┘
                    │ providers.Interface               │ states / plans
                    ▼                                    ▼
        ┌────────────────────────────┐      ┌────────────────────────────────┐
        │ internal/plugin (+plugin6)  │      │ internal/states, internal/plans │
        │ GRPCProvider over go-plugin │      │ state model, planfile, diffs    │
        │ tfplugin5 / tfplugin6 stubs │      └────────────────────────────────┘
        └────────────┬───────────────┘
                     │ gRPC (separate process per plugin)
                     ▼
        ┌────────────────────────────┐
        │  Provider plugin binary     │  (aws, azurerm, google, kubernetes…)
        │  downloaded via registry    │
        └────────────────────────────┘

2.2 The Context — the core engine

The heart of Terraform is terraform.Context in internal/terraform. It is constructed with NewContext(*ContextOpts) (where Parallelism is set) and exposes the operations that every CLI command ultimately calls:

2.3 Graph construction and the walk

Terraform models every operation as a graph. The flow is:

1. Parse — internal/configs reads .tf/.tf.json into a configs.Config tree (root module + descendants). BuildConfigWithGraph resolves module sources/versions with full expression evaluation before loading descendants.
2. Build — an operation-specific GraphBuilder (graph_builder_plan.go, graph_builder_apply.go, graph_builder_eval.go, graph_builder_init.go) produces the graph by applying a pipeline of ~58 transformers (transform_*.go). Transformers add nodes for resources, providers, provisioners, variables, outputs, locals, module expansion (count/for_each), and then wire edges for references, depends_on, provider attachment, destroy ordering, pruning, and more.
3. Reduce — the graph is transitively reduced and validated as a DAG (internal/dag), which detects cycles (surfaced as Error: Cycle: ...).
4. Walk — the DAG is walked concurrently with up to Parallelism (default 10) workers. Each node's Execute runs in dependency order. The walk type selects behavior: walkPlan, walkApply, walkDestroy, walkPlanDestroy, walkValidate, walkImport, walkEval.

Note

Because ordering is derived from the graph, you rarely need depends_on. Implicit dependencies (attribute references like aws_instance.web.id) create graph edges automatically and are preferred.

2.4 The provider/provisioner plugin protocol

Providers and provisioners are out-of-process gRPC servers. Core is the client.

• Transport: github.com/hashicorp/go-plugin. Core launches the plugin binary as a child process; the plugin performs a handshake (magic cookie + protocol version) over stdio, then serves gRPC on a local socket. plugin.CleanupClients() (deferred in realMain) tears down all plugin processes at exit.
• Protocol versions: internal/tfplugin5 (protocol 5) and internal/tfplugin6 (protocol 6) hold the generated gRPC stubs. internal/plugin and internal/plugin6 wrap them as providers.Interface via GRPCProvider.
• Provider RPCs include GetProviderSchema, ValidateProviderConfig, ConfigureProvider, ReadResource, PlanResourceChange, ApplyResourceChange, ImportResourceState, ReadDataSource, and GetResourceIdentitySchemas.
• Values on the wire: all values are go-cty values serialized as msgpack. Marks carry sensitivity and ephemerality across the boundary.

This isolation is a deliberate reliability and security boundary: a crashing provider cannot corrupt core's memory, and internal/logging surfaces plugin panics separately (PluginPanics()).

2.5 Built-in plugins

A few plugins are compiled into core and served from sub-binaries for testing:

• Built-in provider terraform (internal/builtin/providers/terraform): supplies terraform_data (a managed resource for arbitrary values, including the new ephemeral/sensitive store block in 1.16) and the terraform_remote_state data source.
• Built-in provisioners (internal/builtin/provisioners): file, local-exec, remote-exec. The latter two use internal/communicator for SSH/WinRM.

3. Repository & Component Inventory

The codebase is overwhelmingly under internal/ (Go's enforced-private boundary). The largest and most important packages:

Other notable packages: internal/lang (expression/function evaluation, the 116-function registry), internal/instances (count/for_each expansion), internal/refactoring (moved/removed blocks), internal/moduletest (the test framework), internal/genconfig (config generation for import), internal/checks (check blocks / pre/postconditions), and internal/terminal (TTY handling).

Note

The internal/ prefix means none of these packages are importable by third parties — Terraform core is explicitly not a public Go library. Integrations should use the CLI, the JSON output formats, or (for HCP Terraform) the rpcapi.

4. System Requirements

5. Configuration Mastery

There are three distinct configuration surfaces an administrator manages: the CLI configuration file (machine-wide behavior), the backend configuration (where state lives), and environment variables (per-run overrides).

5.1 The CLI configuration file

Loaded by cliconfig.LoadConfig() at startup (before -chdir is applied). Location:

• Linux/macOS: ~/.terraformrc
• Windows: %APPDATA%\terraform.rc
• Override path: TF_CLI_CONFIG_FILE (historically TERRAFORM_CONFIG).

Key settings:

# Reuse downloaded providers across all working directories
plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"

# Control where providers are installed from
provider_installation {
  network_mirror {
    url = "https://terraform.example.com/providers/"
  }
  direct {
    exclude = ["registry.terraform.io/*/*"]
  }
}

# Pin a locally-built provider for development
provider_installation {
  dev_overrides {
    "example.com/acme/foo" = "/home/dev/go/bin"
  }
  direct {}
}

# Credentials for a host (prefer `terraform login` or env vars)
credentials "app.terraform.io" {
  token = "REDACTED"
}

Tip

plugin_cache_dir is the single highest-impact operational setting for CI and multi-directory monorepos — it eliminates redundant provider downloads. Set PluginCacheMayBreakDependencyLockFile (or the equivalent CLI flag) only if you understand the lock-file trade-off.

5.2 Provider installation methods

terraform init resolves providers through the provider_installation block (above) or, by default, directly from registries. For air-gapped or controlled environments:

The dependency lock file .terraform.lock.hcl (managed by internal/providercache) records selected versions and per-platform checksums. Use terraform providers lock -platform=os_arch ... to populate checksums for every platform your team and CI use, so init succeeds everywhere.

5.3 Backend configuration reference

Backends are registered by backendInit.Init() and configured in the terraform block. The 14 built-in backends:

Provide secrets and dynamic values via -backend-config (file or key=value) at init time rather than committing them:

terraform init -backend-config=backend-prod.hcl
terraform init -backend-config="bucket=my-state" -backend-config="region=us-east-1"

5.4 Environment variables (operational set)

See the User Guide §14 for the full list. The ones most relevant to operators:

6. The Plan/Apply Lifecycle (Internals)

  CONFIG (*.tf)            PRIOR STATE              REAL INFRASTRUCTURE
       │                       │                            │
       ▼                       ▼                            │
  configs.Config  ──┐    states.State                       │
                    │         │                             │
                    ▼         ▼                             ▼
              Context.Plan ── refresh (ReadResource via provider gRPC) ◀┘
                    │
                    ▼
      GraphBuilder(plan) → transformers → DAG → walkPlan
                    │   (PlanResourceChange RPC per resource)
                    ▼
              plans.Plan  ──(optional)──▶  plan file (planfile, planproto)
                    │
                    ▼
              Context.Apply → GraphBuilder(apply) → walkApply
                    │   (ApplyResourceChange RPC per resource, parallelism N)
                    ▼
              NEW states.State  ──▶  persisted via backend (with lock)

Key points for operators:

• Refresh happens by default during plan (disable with -refresh=false; review-only with -refresh-only). It issues ReadResource RPCs and can be slow for large states.
• Parallelism (-parallelism=n, default 10) bounds concurrent provider RPCs during the walk. Lower it to relieve API rate limits; raise it cautiously for throughput.
• Saved plans (-out) capture the exact intended changes; apply <planfile> replays them with no prompt. Plans go stale if state changes underneath them (Saved plan is stale).
• Targeting (-target) prunes the graph to a subset; it is an escape hatch, not a workflow.
• Detailed exit codes (-detailed-exitcode: 0/1/2) drive CI gating.

7. State Management (Operations)

State (internal/states) is Terraform's record of managed objects. Treat it as sensitive, authoritative, and fragile.

7.1 Safe operations

• All terraform state mutating subcommands write a timestamped backup first (this cannot be disabled for state mv).
• State locking prevents concurrent writers. The lock mechanism is backend-specific (DynamoDB, blob lease, advisory lock, etc.). terraform force-unlock LOCK_ID releases a stuck lock — only when you are certain nothing is running.
• terraform state pull / push move whole state documents; push refuses older serials or mismatched lineage unless -force is given.

7.2 Routine state hygiene

Warning

State frequently contains secrets (passwords, private keys, tokens) in plaintext. Always use a remote backend with encryption at rest and access controls for anything beyond local experimentation. Restrict who can read the state bucket/store as tightly as who can deploy. (See GitHub issue #34860 — minimizing secrets in state — for the ongoing upstream effort.)

8. Security

8.1 Threat surfaces and controls

8.2 Supply-chain integrity

• The dependency lock file records SHA256 checksums per platform; init verifies downloaded packages against them. Registry packages are GPG-signed (internal/releaseauth validates release authenticity).
• For regulated/air-gapped environments, run an internal network or filesystem mirror (terraform providers mirror) and set provider_installation to use only it.

8.3 Sensitive and ephemeral data

Terraform tracks sensitivity as a mark on go-cty values that propagates through expressions, so a value derived from a sensitive input stays sensitive. Ephemeral values (ephemeral resources/variables/outputs, and the terraform_data store block added in 1.16) exist only during a single operation and are never persisted to state or plan files — the correct mechanism for short-lived secrets.

Caution

sensitive = true hides values from CLI output but they are still stored in state in plaintext. For secrets that must never touch state, use ephemeral values, not just the sensitive flag.

8.4 Licensing

Terraform is licensed under BUSL-1.1, a source-available license that prohibits offering a competing commercial service. This is not OSI-approved open source. Audit obligations before redistributing, embedding, or building a hosted service on Terraform.

9. Operations & Automation

9.1 Running in CI/CD

The canonical non-interactive pipeline:

terraform init -input=false -lock-timeout=120s
terraform fmt -check -recursive
terraform validate
terraform plan -input=false -lock-timeout=120s -out=tfplan -detailed-exitcode
# exit 0 = no changes, 2 = changes (apply), 1 = error
terraform apply -input=false tfplan

• Set TF_IN_AUTOMATION=1 to suppress prompts-assuming messages.
• Use -lock-timeout so concurrent pipeline runs wait instead of failing.
• Provide variables via TF_VAR_* or -var-file; never echo secrets into logs.
• Persist .terraform.lock.hcl in the repo; CI should not silently upgrade providers.

9.2 Provider caching & throughput

• Set plugin_cache_dir / TF_PLUGIN_CACHE_DIR on CI images so providers are downloaded once.
• Bake the provider cache (and optionally a module mirror) into your CI base image for fully offline runs.
• Note GitHub issue #31964: concurrent writes to a shared plugin_cache_dir are not yet fully supported — give each concurrent runner its own cache, or pre-warm a read-only cache.

9.3 Logging & diagnostics

• TF_LOG=TRACE|DEBUG|INFO|WARN|ERROR plus TF_LOG_PATH=run.log capture detailed logs (internal/logging). The harness writes crash logs to TF_TEMP_LOG_PATH and surfaces plugin panics via PluginPanics().
• terraform graph -draw-cycles diagnoses dependency cycles.
• terraform providers schema -json and terraform metadata functions -json give machine-readable schema/function references for editor and tooling integration.
• OpenTelemetry tracing is built in: realMain starts a root span per invocation (terraform <args>), configurable via the OTEL exporter environment variable.

9.4 HCP Terraform / Terraform Enterprise

The cloud {} block (or remote backend) delegates state storage and optionally remote execution to HCP Terraform (internal/cloud, client go-tfe). terraform login/logout manage tokens; terraform-svchost performs service discovery. Force local execution with TF_FORCE_LOCAL_BACKEND. The experimental stacks and rpcapi subsystems exist specifically to integrate HCP Terraform with core and are not intended for direct end-user use.

10. The Module Subsystem

Module installation is handled by internal/initwd, internal/getmodules, internal/modsdir, and internal/registry, built on github.com/hashicorp/go-getter and go-slug.

• Source resolution: local paths, Terraform Registry, Git (git::), HTTP archives, and S3/GCS objects — each handled by a go-getter detector/getter.
• Manifest: installed modules are recorded in .terraform/modules/modules.json; terraform get -update refreshes them within version constraints.
• Refactoring: moved {} blocks let you rename or re-parent resources across module boundaries without destroy/recreate (internal/refactoring). Terraform 1.16 adds support for import blocks inside modules.

Important

Always pin registry and Git modules (version = "x.y.z" or ?ref=tag). Unpinned sources can change between runs, producing unexpected plans and breaking reproducibility — and are a supply-chain risk.

11. Code Quality, Patterns & Conventions

• Strict internal boundary. Nearly all code lives under internal/, enforcing that Terraform core is not a public library. Integrations go through the CLI, JSON outputs, or the HCP rpcapi.
• Address types as a first-class package. internal/addrs models every kind of address (resource, module instance, provider, etc.) with strong typing, avoiding stringly-typed bugs across the engine.
• Transformer pipeline. Graph construction is decomposed into ~58 small, composable transformers — each does one thing (add nodes of a kind, or wire one kind of edge). This makes the engine's behavior auditable and testable.
• Diagnostics over errors. internal/tfdiags provides rich diagnostics (severity, summary, detail, source location) used throughout, enabling the precise, snippet-annotated error output Terraform is known for.
• Views/arguments separation. Commands parse flags into typed arguments.* structs and render through views.*, cleanly separating input parsing, business logic, and output formatting (and enabling -json consistently).
• Generated code. The gRPC stubs (tfplugin5/tfplugin6/planproto) and the dynrpcserver wrappers are generated; tools/protobuf-compile and the dynrpcserver/generator drive this. Do not hand-edit generated files.

11.1 Testing strategy

• Extensive fixture-driven tests: the high file count is dominated by internal/*/testdata/* and testing/equivalence-tests/* — self-contained scenarios, not application code (a known characteristic of large Go repos).
• Equivalence tests (testing/equivalence-tests) snapshot plan/apply output to catch unintended changes in rendering and behavior.
• End-to-end tests (internal/command/e2etest, internal/cloud/e2e) exercise the real binary.
• Terraform also ships a user-facing test framework (internal/moduletest, terraform test).

12. Known Issues & Improvement Areas

Drawn from the project's own issue tracker and code structure — useful when planning rollouts.

12.1 Notable 1.16 changes for operators

• workspace list -json and state show -json machine-readable output.
• terraform_data gains a store block for ephemeral/sensitive values.
• import blocks supported inside modules.
• Linux s390x builds published.
• Experimental (alpha builds only): deferred actions (-allow-deferral), terraform test cleanup, and terraform test backend blocks + skip_cleanup.
• Upgrade note: provisioner bastion_host_key is now correctly applied — verify your configured key is correct before upgrading.

13. Quick Reference

13.1 Operator command cheat-sheet

# Air-gapped provider install
terraform providers mirror /srv/tf-mirror
terraform providers lock -platform=linux_amd64 -platform=darwin_arm64

# CI pipeline
terraform init -input=false -lock-timeout=120s
terraform plan -input=false -out=tfplan -detailed-exitcode
terraform apply -input=false tfplan

# Backend migration
terraform init -migrate-state            # move state to new backend
terraform init -reconfigure              # ignore old backend config

# State surgery (each backs up first)
terraform state mv A B
terraform state rm aws_instance.legacy
terraform force-unlock <LOCK_ID>

# Diagnostics
TF_LOG=DEBUG TF_LOG_PATH=tf.log terraform plan
terraform graph -draw-cycles | dot -Tsvg > graph.svg
terraform providers schema -json | jq

13.2 Architecture facts

13.3 Key file/dir glossary