Fundamental Workshop 1 — Terraform: One Block, One Plan, One State

Duration

20 min

Module

1/7

Prerequisites

Terraform installed (terraform version answers) and the kit cloned into lab-terraform (Project 01, Appendix A.1 to A.4 or B.1 to B.4)

You will build

a Terraform project stripped to the bone, a single three-line block, a bonjour.txt file created by Terraform, and a state that you will read

Deliverable

the output of terraform state show local_file.bonjour from step 9

How to read this page. Ten steps, one command at a time. For each: the command to type, the exact output from the course machine (Terraform 1.12.2), and what to look at in it. Type each command yourself (no copy-paste): it is by writing init, plan, apply, state that the words sink in. The "To understand better" blocks are optional; open them if a step leaves you in doubt. The terraform … commands are identical on Windows, Linux and macOS; when a command depends on the system (creating, reading, listing a file), both versions are given, one below the other. If Terraform is not installed or the kit is not cloned, go back to Project 01, section In short (kit: https://github.com/hrhouma2/aiopsatlas-terraform-labo-fr).

Objective

Project 01 had you run thirteen commands on a fifteen-line main.tf, with a terraform block, a provider block and a resource block. You saw the sentences scroll by, but fifteen lines is already a lot when you want to know what is essential. Here, you start from zero with three useful lines: a single resource block, with nothing around it. You will see Terraform refuse to work without init, then have it write its estimate, carry it out, and read what it noted in its record. At the end, you know what a block, a plan and a state are because you built them yourself, one after the other.

The vocabulary in one image

Take the architect from Lesson 01 again. A resource block is one line of the architect's blueprint: "here, a file, with this name and this content". The plan (the command) is the estimate: what Terraform would do so that reality looks like the drawing. The state is the record: what Terraform actually built, under which identifier, with which values. Three objects, three commands to see them: the block is read in main.tf, the estimate with terraform plan, the record with terraform state show.

Where to type

A terminal (PowerShell on Windows; bash or zsh on Linux, macOS, WSL 2 or Git Bash), opened at the root of the lab-terraform kit, the one containing labo.ps1 and labo.sh. And VS Code to write the file. The terraform … commands are written exactly the same way everywhere; only the commands to create, read or list a file change, and they are given in both versions each time.

Step 1 — Create an empty folder

Windows (PowerShell):

.\labo.ps1 nouveau atelier-1
cd travail\atelier-1

Linux, macOS, WSL 2, Git Bash:

./labo.sh nouveau atelier-1
cd travail/atelier-1

Dossier travail/atelier-1 créé (ignoré par Git). Tapez :
  cd travail/atelier-1

What the command asks: create an empty working folder for me, travail/atelier-1, which Git will ignore (on Windows the script writes travail\atelier-1, with the backslash).

What to look at: the folder is empty. Nothing is a Terraform project yet: main.tf, then init, will make it one.

Step 2 — Write one block, three lines

In VS Code (code . from the folder), create a main.tf file and type exactly:

resource "local_file" "bonjour" {
  filename = "${path.module}/bonjour.txt"
  content  = "Bonjour Terraform"
}

What the file asks: "Terraform, manage a file on disk for me (local_file), which I call bonjour; it is named bonjour.txt, in this folder, and it contains Bonjour Terraform."

What to look at: there is neither a terraform block nor a provider block. Nothing but the resource. Terraform will infer everything else from the word local_file. Check that the file is there and correctly named:

Windows (PowerShell):

Get-ChildItem
Get-Content .\main.tf

Linux, macOS, WSL 2, Git Bash:

ls -la
cat main.tf

A single entry, main.tf, and the four lines of the file. If you see main.tf.txt, rename it.

Step 3 — Ask for a plan too early

terraform plan

Error: Inconsistent dependency lock file

The following dependency selections recorded in the lock file are
inconsistent with the current configuration:
  - provider registry.terraform.io/hashicorp/local: required by this configuration but no version is selected

To make the initial dependency selections that will initialize the dependency
lock file, run:
  terraform init

What the command asks: "Tell me what you would do so that reality looks like my code."

What to look at: Terraform refuses, and explains. It read local_file, inferred that it needs the registry.terraform.io/hashicorp/local provider, and notices it does not have it (no version is selected). The last line is the solution: terraform init. This is the error every beginner meets once; now you know how to read it.

Step 4 — Open the construction site

terraform init

Initializing the backend...
Initializing provider plugins...
- Finding latest version of hashicorp/local...
- Installing hashicorp/local v2.9.1...
- Installed hashicorp/local v2.9.1 (signed by HashiCorp)
Terraform has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so that Terraform can guarantee to make the same selections by default when
you run "terraform init" in the future.

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.
…

What the command asks: "Download the providers my code requires and prepare this folder."

What to look at: Finding latest version of hashicorp/local...: without a required_providers block, Terraform takes the most recent version (v2.9.1 on the course machine; on yours, maybe newer). In Project 01, the same line said Finding hashicorp/local versions matching "~> 2.5"... because the code set a constraint. Then the sentence to expect: Terraform has been successfully initialized!

List the folder, including hidden files:

Windows (PowerShell):

Get-ChildItem -Force

Linux, macOS, WSL 2, Git Bash:

ls -la

Three entries: .terraform (a folder, the downloaded provider), .terraform.lock.hcl (the chosen version, recorded) and your main.tf. No bonjour.txt yet, no terraform.tfstate yet: init built nothing.

Step 5 — Read the estimate

terraform plan

Terraform used the selected providers to generate the following execution
plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # local_file.bonjour will be created
  + resource "local_file" "bonjour" {
      + content              = "Bonjour Terraform"
      + content_base64sha256 = (known after apply)
      + content_base64sha512 = (known after apply)
      + content_md5          = (known after apply)
      + content_sha1         = (known after apply)
      + content_sha256       = (known after apply)
      + content_sha512       = (known after apply)
      + directory_permission = "0777"
      + file_permission      = "0777"
      + filename             = "./bonjour.txt"
      + id                   = (known after apply)
    }

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

─────────────────────────────────────────────────────────────────────────────

Note: You didn't use the -out option to save this plan, so Terraform can't
guarantee to take exactly these actions if you run "terraform apply" now.

What the command asks: the same as in step 3. This time Terraform has its provider, and it answers.

What to look at, line by line, because this is the output you will read most often in your whole life with Terraform:

Nothing has been created. Check: bonjour.txt still does not exist in the folder.

Step 6 — Have the estimate carried out

terraform apply

Terraform used the selected providers to generate the following execution
plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # local_file.bonjour will be created
  + resource "local_file" "bonjour" {
      + content              = "Bonjour Terraform"
      …
      + filename             = "./bonjour.txt"
      + id                   = (known after apply)
    }

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

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

local_file.bonjour: Creating...
local_file.bonjour: Creation complete after 0s [id=fd9aee5556589b4d797e6d49f8ec894e29e57713]

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

What the command asks: "Recompute the estimate, show it to me, wait for my agreement, then do it."

What to look at: the same plan as in step 5, then the question. Type yes, in full, then Enter. Then Creating..., Creation complete after 0s [id=fd9aee55…]: the id that was (known after apply) is now known. And the sentence to expect: Apply complete! Resources: 1 added, 0 changed, 0 destroyed. The three numbers are those of the plan.

If you type y instead of yes, Terraform answers Apply cancelled. and does nothing. Try it once, to have seen it; then rerun with yes.

Step 7 — Read the file, list the folder

Windows (PowerShell):

Get-Content .\bonjour.txt
Get-ChildItem -Force

Linux, macOS, WSL 2, Git Bash:

cat bonjour.txt
ls -la

Bonjour Terraform

total 14
drwxr-xr-x 1 rehou 197609    0 sept. 15 14:55 .
drwxr-xr-x 1 rehou 197609    0 sept. 15 14:55 ..
drwxr-xr-x 1 rehou 197609    0 sept. 15 14:55 .terraform
-rw-r--r-- 1 rehou 197609 1228 sept. 15 14:55 .terraform.lock.hcl
-rw-r--r-- 1 rehou 197609   17 sept. 15 14:55 bonjour.txt
-rw-r--r-- 1 rehou 197609  111 sept. 15 14:55 main.tf
-rw-r--r-- 1 rehou 197609 1634 sept. 15 14:55 terraform.tfstate

(ls -la listing from the course machine; Get-ChildItem -Force displays the same five names, with other columns.)

What the commands ask: "Show me the content of bonjour.txt, then everything in the folder, hidden files included."

What to look at: Bonjour Terraform, 17 bytes, exactly your content, without a trailing newline (under bash, your prompt may appear glued to the text: that is normal). And two new things in the folder since step 4: bonjour.txt, the resource, and terraform.tfstate, the state. It is apply that created both, at the same time: the file on disk, and the note "I created it" in the record.

Step 8 — Read the record: the list

terraform state list

local_file.bonjour

What the command asks: "List everything you manage in this folder."

What to look at: one line, one resource, designated by its address local_file.bonjour, the same as in the plan. It is the proof that Terraform tied your block to the real file. Before step 6, the same command would have answered No state file was found!: there was no record yet.

Step 9 — Read the record: the detail

terraform state show local_file.bonjour

# local_file.bonjour:
resource "local_file" "bonjour" {
    content              = "Bonjour Terraform"
    content_base64sha256 = "SvXkP5Iqo1rJKHgTVJnjanxfsNVGhb+r52mzUqZJYyg="
    content_base64sha512 = "r3+PevYNJRFsHMz4H4U1DK+lg89nhO9SLJZMAqqtzPKiIv3ilrmbx5sYh2JCW9o5EF0NXanYmuxMvI2QN4Z1Ag=="
    content_md5          = "ff3a967c227a58691a3d34a931d3eeb5"
    content_sha1         = "fd9aee5556589b4d797e6d49f8ec894e29e57713"
    content_sha256       = "4af5e43f922aa35ac92878135499e36a7c5fb0d54685bfabe769b352a6496328"
    content_sha512       = "af7f8f7af60d25116c1cccf81f85350cafa583cf6784ef522c964c02aaadccf2a222fde296b99bc79b188762425bda39105d0d5da9d89aec4cbc8d9037867502"
    directory_permission = "0777"
    file_permission      = "0777"
    filename             = "./bonjour.txt"
    id                   = "fd9aee5556589b4d797e6d49f8ec894e29e57713"
}

What the command asks: "Show me everything you know about local_file.bonjour."

What to look at: the same shape as the plan of step 5, but without any + and without any (known after apply): everything is known, everything is recorded. The id is the SHA-1 fingerprint of the content (fd9aee55…), identical to content_sha1 and to the [id=…] displayed by apply. Your two arguments (filename, content) are there, along with the nine attributes computed by the provider. This is your deliverable answer: keep it.

Step 10 — Ask for a plan again: nothing to do

terraform plan

local_file.bonjour: Refreshing state... [id=fd9aee5556589b4d797e6d49f8ec894e29e57713]

No changes. Your infrastructure matches the configuration.

Terraform has compared your real infrastructure against your configuration
and found no differences, so no changes are needed.

What the command asks: the same as in steps 3 and 5.

What to look at: two new things compared to step 5. Refreshing state... [id=…]: before comparing, Terraform went to reread the real file to check that it still matches the record. Then No changes. Your infrastructure matches the configuration.: the code, the record and reality say the same thing, the estimate is empty. That is the idempotence from Lesson 01, in the terminal: rerunning does nothing more.

Do not destroy anything. Fundamental Workshop 2 starts exactly from this folder, with this file and this state. If you do not chain it right away, leave the folder as is: nothing is billed, nothing moves. (If you really want to erase everything now: terraform destroy, yes, and you will redo Workshop 1 before Workshop 2.)

Final check

Go back up to the root of the kit and run the counter:

Windows (PowerShell):

cd ..\..
.\labo.ps1 etat

Linux, macOS, WSL 2, Git Bash:

cd ../..
./labo.sh etat

travail atelier-1 : 1 ressource dans le state
Ressources encore gérées : 1 (0 attendu à la fin d'une séance).

Expected answer: 1 ressource dans le state (1 resource in the state). The (0 attendu à la fin d'une séance) (0 expected at the end of a session) is the kit's reminder; here it is normal to be at 1, since Workshop 2 is going to destroy this resource.

• You wrote a single-block main.tf, without terraform {} or provider {}, and it was enough.
• You saw Error: Inconsistent dependency lock file and you know the solution is in the last line.
• init created .terraform/ and .terraform.lock.hcl, and nothing else.
• You know how to read a plan: + create, will be created, (known after apply), Plan: 1 to add, 0 to change, 0 to destroy.
• apply asked for yes, created bonjour.txt and terraform.tfstate.
• state list returns local_file.bonjour; state show returns the full block with a forty-character id.
• A second plan returns No changes.
• You kept the output of terraform state show local_file.bonjour (step 9) as the deliverable.

When things go wrong