Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 37 Β· Infrastructure as Code Basics

How Terraform Works: Core, Providers, State and the Graph

Look inside Terraform: the core binary, provider plugins and their gRPC protocol, state, the resource graph, parallel execution, and the phases of plan and apply.

You can use Terraform for months without knowing what happens inside, but a clear mental model makes error messages, slow applies and odd plans much easier to understand. This lesson opens the box: the pieces of Terraform, what each does, and how they cooperate during a plan and an apply. The ideas are small. The picture to keep in mind is a core that builds a graph, and plugins that do the real work.

The two halves: core and providers

When you run terraform plan, two kinds of programs are involved.

Terraform core is the terraform binary. It reads your .tf files, builds a model of your configuration, loads state, builds the dependency graph, decides actions, and walks the graph. Core knows nothing about any cloud.

Providers are separate programs that core starts as child processes and talks to over a local RPC connection (gRPC). Each provider exposes a schema (which resource types, data sources and arguments it supports) and implements operations for each resource type: read, create, update, delete. When core wants an S3 bucket created, it calls the AWS provider, which calls the AWS API.

flowchart TB
    subgraph Core["Terraform core (terraform binary)"]
        C1["Parse .tf files"] --> C2["Build graph"]
        C2 --> C3["Plan / apply walker"]
        ST[("State")] <--> C3
    end
    C3 <-->|"gRPC"| PA["AWS provider"]
    C3 <-->|"gRPC"| PB["Cloudflare provider"]
    C3 <-->|"gRPC"| PC["random provider"]
    PA -->|"HTTPS"| API1["AWS API"]
    PB -->|"HTTPS"| API2["Cloudflare API"]

Core owns the graph and the state; providers own all knowledge of a particular API.

This split explains several things. Providers are versioned and downloaded independently (that is what init does). A bug in a resource's behavior is a provider bug, fixed by upgrading the provider, not Terraform. And writing support for a new platform means writing a provider, not changing Terraform.

What lives in a configuration

Terraform's own vocabulary has a few object kinds. Knowing them makes the docs readable.

Object Block Purpose
Resource resource A managed infrastructure object
Data source data A read-only lookup of existing information
Provider provider Settings for a provider (region, credentials)
Variable variable An input to the module
Local locals A named expression for reuse
Output output A value exposed after apply
Module module A reusable bundle of the above

Every one of these becomes a node in the graph.

The dependency graph

Terraform does not run your files top to bottom. It builds a directed acyclic graph (DAG): nodes are objects, and an edge means "must exist before." Edges come mostly from references. If aws_instance.web uses aws_subnet.main.id, the subnet node comes first.

Two big benefits follow:

  1. Correct order with no effort from you; you never write "do A, then B."
  2. Parallelism: nodes with no path between them run at the same time.

For destroy the order is reversed: the instance is deleted before the subnet.

Python Ordering a dependency graph (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The two subnets and the security group are created at the same moment because none depends on the others. This is why a large apply is faster than the sum of its parts.

If you make the graph circular, Terraform stops with Error: Cycle. Try it in the stand-in by making aws_vpc.main depend on aws_lb.front; it raises an error with the nodes involved, just like Terraform lists the cycle.

State: Terraform's memory

State is a JSON document that maps each resource address in your configuration (aws_instance.web) to a real object (i-0abc123) and stores the attributes the provider returned. Terraform needs it for three reasons:

  • Mapping. Without it, Terraform could not tell which of ten identical servers belongs to which block.
  • Metadata. It records dependencies, so deletion order is still right when you remove a block.
  • Performance. It caches attributes so a plan does not need to query everything when -refresh=false.

By default the file is terraform.tfstate next to your code. Teams store it remotely, with locking, so two people cannot apply at once. The State Management chapter covers this fully.

Phases of a plan and apply

flowchart LR
    A["Load config<br/>and state"] --> B["Refresh<br/>(read real objects)"]
    B --> C["Build graph"]
    C --> D["Diff: desired vs refreshed"]
    D --> E["Plan: list of actions"]
    E -->|"approve"| F["Walk graph:<br/>call provider create/update/delete"]
    F --> G["Write state"]

A plan stops after step E. An apply continues through F and G.

Some values are unknown at plan time, such as the ID of a server that does not yet exist. Terraform prints them as (known after apply) and fills them in as the walker finishes each node. If another resource's argument depends on an unknown value, that resource's final value is also unknown until apply. Certain constructs, such as count or for_each keys, must be known at plan time, which is why you sometimes get "The for_each value depends on resource attributes that cannot be determined until apply."

What providers do on your behalf

For every resource type a provider implements the same lifecycle:

  • Read: fetch the object by ID so Terraform can refresh state.
  • Create: make it, return the ID and computed attributes.
  • Update: change what can change live.
  • Delete: remove it.

The provider's schema labels each argument as required, optional, computed (set by the platform) or forcing a new resource. The plan's ~ versus -/+ decision is simply the provider saying which arguments force new. Providers also configure authentication from your provider block or environment variables, such as AWS_ACCESS_KEY_ID.

Terraform's parts

Core Parses, graphs, plans.
Providers Talk to platform APIs.
State Maps blocks to real objects.
Graph Decides order and parallelism.
1 / 2

Why terraform init needs the internet

Since providers are separate downloads, init fetches them from a registry (the public registry.terraform.io, or registry.opentofu.org for OpenTofu, or a private mirror). The lock file pins versions and records checksums so a tampered download is rejected. In locked-down networks you can configure a filesystem or network mirror and run terraform init without reaching the public registry.

Debugging with logs

When something fails mysteriously, set the log level and read the log:

Terminal
TF_LOG=DEBUG TF_LOG_PATH=terraform.log terraform plan

Levels from quiet to loud are ERROR, WARN, INFO, DEBUG, TRACE. The log shows provider calls and API requests, which is usually enough to see whether the problem is your configuration, the provider or the cloud. Remove secrets before sharing a log; it can contain tokens.

Check your understanding

Quick check Β· 4 questions

of 4 answered You scored / 4 Β· perfect!

  1. 1. Which part of Terraform knows how to create an Azure virtual machine?

    Core is platform-neutral. Providers implement create, read, update and delete for their platform's resource types.
  2. 2. Two resources have no reference between them. What does the graph allow?

    Without an edge between nodes, Terraform may run them concurrently (10 at once by default).
  3. 3. Why does Terraform store state?

    State links each address to a real object ID and caches attributes and dependencies.
  4. 4. What does (known after apply) mean in a plan?

    Some attributes, like generated IDs, do not exist until the object is created, so the plan cannot show them yet.

Summary

  • Core builds the graph and plans; providers (separate plugins over gRPC) talk to APIs.
  • Objects in a configuration (resources, data sources, variables, locals, outputs, modules) become graph nodes.
  • References create edges; independent nodes run in parallel; destroy runs in reverse.
  • State maps addresses to real objects and caches attributes.
  • A plan loads, refreshes, diffs and lists actions; an apply walks the graph and writes state.
  • Unknown values appear as (known after apply); TF_LOG helps debugging.

Next: HCL Syntax and Project Files