Glossary

Terms used throughout the Terraform codebase. Unless stated otherwise, types listed here live in internal/.

Configuration and language

• Configuration. The user's .tf and .tf.json source. Parsed by internal/configs into a tree rooted at configs.Config, with one configs.Module per directory.
• Module. A directory of .tf files. The root module is whatever you point Terraform at; child modules are pulled in via module blocks. Module installation lives in internal/initwd/ and internal/configs/configload/.
• HCL. HashiCorp Configuration Language, the syntax in which .tf files are written. Terraform extends bare HCL with its own block schema, expressions (for, splat, dynamic), and functions.
• Body / Expression. Low-level HCL types (hcl.Body, hcl.Expression) that the configs package keeps un-evaluated for parts of the configuration whose meaning depends on runtime state.
• Schema. The expected shape of a block or attribute. Resource and data-source schemas come from providers; provider, backend, and language-level schemas live in internal/configs/configschema/.
• Reference. A symbolic mention of another object in an expression, e.g. aws_instance.web[0].id. Parsed by internal/lang/langrefs and internal/lang.References.
• cty.Value. The dynamic-value type used for everything Terraform evaluates. cty comes from zclconf/go-cty and supports unknown values, marked values (sensitive, ephemeral), and structural types.

Addressing

Defined in internal/addrs.

• Resource address. Identifies a resource block, e.g. module.web.aws_instance.example. The unparsed type is addrs.Resource; with module path it becomes addrs.AbsResource.
• Resource instance address. A specific instance produced by count / for_each, e.g. aws_instance.example[0] (addrs.AbsResourceInstance).
• Module address / ModuleInstance. The path of module calls leading to a given module, optionally with count/for_each keys.
• Provider address. A fully qualified provider source like registry.terraform.io/hashicorp/aws. The unqualified short name (aws) is resolved against required_providers to find the source.
• Reference target. Any address kind that can appear on the right side of an expression: resources, data sources, locals, variables, outputs, path, terraform, count, each, self, ephemeralresources, etc.

State

Defined in internal/states.

• State. Terraform's record of what it manages and what attributes those objects had last time it talked to the provider. The in-memory form is states.State; the on-disk form is JSON, serialized by internal/states/statefile.
• State manager. An implementation of states.statemgr.Full that knows how to persist and load a State snapshot. Backends create and own state managers.
• Workspace. A named state slot within a backend. The default workspace is called default. Workspace listing/selection lives in internal/command/workspace_*.go.
• Resource instance object. A single record in state — what's stored under one resource instance address. May be a current object or one or more deposed objects (left over from a create_before_destroy swap).
• SyncState. A mutex-wrapped wrapper around states.State (internal/states/sync.go). The graph walk is concurrent, so reads and writes during walking go through this synchronizer.

Planning and applying

• Operation. A unit of work the CLI hands to a backend: plan, apply, refresh, query, test, etc. The struct is backendrun.Operation.
• Plan. A description of changes Terraform proposes (internal/plans/plan.go). Contains Changes, the prior state, the per-resource provider schemas, the variables, and metadata. Persisted via internal/plans/planfile.
• Change. A single proposed action on a single resource instance: Create, Read, Update, Delete, NoOp, Replace, CreateThenDelete, DeleteThenCreate, Forget. See internal/plans/changes.go.
• Action. Used in two senses. (1) The plans.Action enum above. (2) The new "actions" feature — first-class operations a provider can perform that aren't tied to managed-resource lifecycle (internal/configs/action.go, internal/plans/action_invocation.go).
• Refresh. A read-only synchronization step that updates the prior state from the real infrastructure before planning.
• Plan quality. A field on plans.Plan indicating whether the plan is complete, errored, or no-changes. See internal/plans/quality.go.

Providers and plugins

• Provider. A plugin that implements one or more resource and data types. Communicates with Terraform Core via gRPC; protocol definitions live in docs/plugin-protocol/.
• Provider source. A fully qualified address (hostname/namespace/name) telling Terraform where the provider lives in a registry.
• Provider installer. The subsystem in internal/getproviders that resolves required providers, downloads packages, verifies signatures, and writes the dependency lock file.
• Provider cache. A local directory of already-downloaded provider packages. Managed by internal/providercache/.
• Dependency lock file. .terraform.lock.hcl, written and consumed by internal/depsfile/. Records which provider versions and package hashes were selected on the last terraform init.
• Reattach. A debugging/test mechanism where Terraform connects to an already-running provider process via TF_REATTACH_PROVIDERS instead of spawning a new one. See internal/getproviders/reattach.

Graph and execution

• Graph. A directed acyclic graph of "happens-after" relationships, type terraform.Graph.
• Vertex / node. A point in the graph, often (but not always) corresponding to one configuration object. The codebase uses both terms interchangeably.
• Edge. A "happens after" relationship. If A points at B then B must complete before A.
• Graph builder. Constructs a graph by composing GraphTransformers. There is one per operation: plan, apply, init, eval.
• Graph transformer. An implementation of terraform.GraphTransformer that mutates a graph (adds/removes vertices, adds edges). Hundreds exist; see the transform_*.go files in internal/terraform.
• Graph walk. The DAG traversal that calls Execute on each vertex in topological order, with as much parallelism as the edges permit. The low-level walker is dag.AcyclicGraph.Walk; the Terraform-specific wrapper is terraform.ContextGraphWalker.
• EvalContext. Per-module execution context (internal/terraform/eval_context.go). Holds the providers, the in-progress state and plan, and the expression scope.
• Dynamic expand. A vertex's ability to produce its own sub-graph at evaluation time. Implemented by GraphNodeDynamicExpandable. Used for count/for_each, modules, and provider configuration.

Backends and HCP Terraform

• Backend. A pluggable destination for state. Listed in internal/backend/init/init.go.
• Operations backend. A backend that can also run operations remotely. Only local, remote (HCP Terraform pre-cloud-block), and cloud (HCP Terraform via the cloud {} block) implement this.
• HCP Terraform / Terraform Cloud. HashiCorp's hosted Terraform service. Integration lives in internal/cloud/ and internal/backend/remote/. The newer cloud {} block uses internal/backend/remote under the hood.
• Pluggable state storage. A more recent extension point letting providers themselves implement state storage; see internal/backend/pluggable/ and internal/configs/state_store.go.

Stacks

A newer construct (in active development) for managing multiple Terraform configurations together with explicit inputs/outputs and component graphs.

• Stack. A collection of components, each of which is itself a Terraform configuration. Configuration types: internal/stacks/stackconfig.
• Stack runtime. The orchestrator that plans and applies an entire stack. Lives in internal/stacks/stackruntime.
• Component. One Terraform module-like unit inside a stack, planned and applied as part of the stack.
• See internal/stacks/README.md and the stacks command implementation in internal/command/stacks.go.

Testing

• terraform test. The native test runner for .tftest.hcl files. Implementation in internal/command/test.go; the runtime in internal/moduletest/.
• Test file. A .tftest.hcl file containing one or more run blocks. Parsed by internal/configs/test_file.go.
• Mock provider. Test scaffolding (internal/configs/mock_provider.go) that replaces a real provider with deterministic responses inside a test run.

Other recurring terms

• Diagnostics (tfdiags). Terraform's structured error/warning type. Almost every public function returns tfdiags.Diagnostics instead of error. See internal/tfdiags.
• Hooks. Callbacks invoked during graph walk (internal/terraform/hook.go). Used by the CLI's view layer to render progress.
• Views. The CLI rendering layer (internal/command/views). Each major command has a view interface with Human and JSON implementations selected by -json.
• Promising. A custom dependency-tracking library at internal/promising/ used by the stacks runtime.
• Deferred actions. Changes a plan declares it can't fully determine yet (internal/plans/deferring), surfaced when -target is used or when unknown values prevent expansion.
• Ephemeral resources / values. Values that exist only for the duration of one operation and are never persisted to state. Marked with cty.NewValueMarks(marks.Ephemeral).