Terraform basics: state, plan and apply

A Terraform configuration never says "create a server, then write a file". It says what should exist. Terraform compares that with what it already manages and proposes the difference. That is what declarative means here: you edit the destination, never the route.

resource "random_pet" "server" {}

resource "local_file" "motd" {
  filename = "${path.module}/motd.txt"
  content  = "hello from ${random_pet.server.id}\n"
}

(random and local need no cloud account, so every example in this unit runs on a laptop. An aws_db_instance follows exactly the same rules.)

The vocabulary:

• A provider is the plugin that talks to one API — hashicorp/aws, hashicorp/random. terraform init downloads the ones you declare and pins their exact versions in .terraform.lock.hcl, which you commit.
• A resource block declares one object that Terraform creates and owns. Type plus name, random_pet.server, is its address.
• A reference such as random_pet.server.id is also a dependency. Terraform creates the pet before the file because the file's content needs the pet's name.

Then the loop, with real output:

$ terraform plan
  # local_file.motd will be created
  + resource "local_file" "motd" {
      + content  = (known after apply)
      + filename = "./motd.txt"
      ...
  # random_pet.server will be created
  + resource "random_pet" "server" {
      + id = (known after apply)
      ...
Plan: 2 to add, 0 to change, 0 to destroy.

$ terraform apply
random_pet.server: Creation complete after 0s [id=smashing-scorpion]
local_file.motd: Creation complete after 0s [id=f5820057…]
Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

• plan changes nothing. It reads the real objects, compares them with the configuration, and proposes actions. (known after apply) marks values that won't exist until the object is created — the pet's name, so also the file's content.
• apply makes a plan real. Run bare, it computes a fresh plan, shows it, and waits for yes.
• Run plan again right after, and it reports No changes: the real world now matches the file. Editing the file is how you change infrastructure; the next plan shows the difference.

The configuration has one variable, env, used in three places:

variable "env" {
  type    = string
  default = "staging"
}

resource "random_pet" "server" {
  keepers = { env = var.env }      # a new env means a new pet
}

resource "terraform_data" "config" {
  input = { env = var.env, replicas = 2 }
}

resource "local_file" "motd" {
  filename = "${path.module}/motd.txt"
  content  = "hello from ${random_pet.server.id}\n"
}

It was applied with staging. Here is the real plan for -var env=production, with the checksum lines of the file trimmed:

  ~ update in-place
-/+ destroy and then create replacement

  # local_file.motd must be replaced
-/+ resource "local_file" "motd" {
      ~ content = <<-EOT
            hello from evident-satyr
        EOT -> (known after apply) # forces replacement
      ~ id      = "dd375f8f…" -> (known after apply)

  # random_pet.server must be replaced
-/+ resource "random_pet" "server" {
      ~ id      = "evident-satyr" -> (known after apply)
      ~ keepers = { # forces replacement
          ~ "env" = "staging" -> "production"
        }

  # terraform_data.config will be updated in-place
  ~ resource "terraform_data" "config" {
        id    = "4971ef44-…"
      ~ input = {
          ~ env = "staging" -> "production"

Plan: 2 to add, 1 to change, 2 to destroy.

Line by line:

• ~ update in place. The same object (note the unchanged id) gets a new value. Cheap and usually safe.
• -/+ must be replaced. The provider can't change that attribute on a live object, so the object is destroyed and a new one created — new ID, new identity. # forces replacement names the attribute responsible. For a database, a disk or a DNS record, that is the line to read before anything else.
• Replacement spreads. Nothing about the file changed directly, but its content embeds the pet's name, which will be new — so the file is replaced too.
• The summary counts objects, not resources. Each replacement destroys one object and creates one, so two replacements plus one update read 2 to add, 1 to change, 2 to destroy. "1 to change" is only the in-place update. Skim the summary for "change" and you'll miss that a replace is a destroy.

Two more symbols you'll meet:

• +/- create replacement and then destroy — the same replacement, reversed, when the resource sets lifecycle { create_before_destroy = true }. The default is destroy-then-create.
• <= read — a data source being read during apply because something it depends on is still changing. Reads never appear in the add/change/destroy line.

Plan once, apply that plan

terraform apply with no argument re-plans, and the world may have moved since you reviewed. In CI, save the plan and apply exactly it:

terraform plan -out=tfplan           # the file you review (or a bot summarises)
terraform apply tfplan               # applies those actions — no new plan, no prompt

Terraform's own hint after -out reads "To perform exactly these actions, run …". A plan file contains the configuration and variable values, sensitive ones included, so treat it like state. For scripts, terraform plan -detailed-exitcode exits 0 for no changes, 2 for changes and 1 for an error.

Drift is a difference between a real object and what Terraform last recorded: someone edited a security group in the console, an autoscaler changed a count, a person "just fixed it" on the server. Every normal plan starts by refreshing — asking the provider what each object looks like now — and then plans from that.

Here someone overwrote motd.txt by hand. The next normal plan:

  # local_file.motd will be created
  + resource "local_file" "motd" {
      ...
Plan: 1 to add, 0 to change, 0 to destroy.

A plan that only creates looks harmless, but nothing in the configuration changed — this is Terraform undoing the hand edit. To see what it detected, ask for a refresh-only plan:

$ terraform plan -refresh-only
Note: Objects have changed outside of Terraform

  # local_file.motd has been deleted
  - resource "local_file" "motd" { ... }

This is a refresh-only plan, so Terraform will not take any actions to undo
these. If you were expecting these changes then you can apply this plan to
record the updated values in the Terraform state without changing any remote
objects.

How drift is reported depends on the provider. local compares the file's checksum and reports a file with different content as gone, so the fix is a create. A cloud provider usually reports the changed attribute, and the normal plan shows a ~ update that puts the configured value back. (A normal plan prints its own "Objects have changed outside of Terraform" note only for changes that may have affected the plan; -refresh-only lists everything it found.) Either way: a normal plan makes reality match the configuration again.

So you choose, per change:

The trap is the third row. -refresh-only updates state, never the configuration. After accepting the hand edit that way, the very next normal plan still read:

  # local_file.motd will be created
Plan: 1 to add, 0 to change, 0 to destroy.

The configuration still declares the file, so Terraform still wants it. Keeping an outside change means editing the code; -refresh-only is for looking, and for refreshing outputs that other configurations read from your state.

ignore_changes is for attributes something else legitimately owns — tags a compliance tool manages, a count an autoscaler moves — not for silencing drift you don't understand.