Your first resource

Terraform told Theo exactly what it would do. He just couldn’t read it yet.

This lesson builds one real resource and teaches you to read what Terraform says it will do with it.

A Terraform project is a folder of .tf files. Terraform reads all of them together, so how you split them into files is up to you. A few names are usual:

Providers: how Terraform talks to AWS

Terraform itself knows nothing about AWS. A provider is a plugin that teaches it one platform: every resource type, and how to create, change and delete each one. There are providers for AWS, Azure, Google Cloud, GitHub and hundreds more.

You say which provider you need, and which versions are allowed, in a terraform block:

A major version is the first number. When it goes up, things you rely on may change or disappear. That’s why ~> stops before it.

Resources: the things you build

A resource is one thing in AWS that Terraform creates and looks after. Its first line has two names:

orders and quickcart-orders are different names for different readers. One is for your code; the other is what you see in the console.

Four commands

Reading a plan

Each resource in a plan starts with a symbol. It tells you how careful to be.

Inside a resource, each line has a symbol too, and a few phrases matter:

Which settings force replacement is decided by AWS, not by you. You can’t memorise them all, and you don’t need to. The plan always tells you.

What init leaves in the folder

Here is QuickCart’s repository in code. Pick a change, and see the plan Terraform makes for it.

main.tf

resource "aws_ecr_repository" "orders" {
  name                 = "quickcart-orders"
  image_tag_mutability = "IMMUTABLE"
  force_delete         = true

  tags = {
    Project = "quickcart"
    Team    = "platform"
  }
}

$ terraform plan

  # aws_ecr_repository.orders will be updated in-place
  ~ resource "aws_ecr_repository" "orders" {
        id                   = "quickcart-orders"
        name                 = "quickcart-orders"
      ~ tags                 = {
            "Project" = "quickcart"
          + "Team"    = "platform"
        }
        # (6 unchanged attributes hidden)
    }

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

What to notice: adding a tag and renaming the repository are both one-line changes. One is a harmless ~. The other is a -/+ that deletes every image inside. The size of the change in your code tells you nothing; only the plan does.

Free — one empty ECR repository, which costs nothing, created and destroyed in the same lab.

You’ll build QuickCart’s image repository with Terraform, change it in place, see a change that would force replacement, and destroy it. About 30 minutes.

You need Terraform (see Why Terraform) and a working AWS login in your terminal (Set up your computer covers it). Terraform uses the same login as the AWS CLI. Check it:

aws sts get-caller-identity

{
    "UserId": "AIDAEXAMPLEUSERID1234",
    "Account": "111122223333",
    "Arn": "arn:aws:iam::111122223333:user/quickcart-admin"
}

Your account number and user name will be your own. If this command fails, fix your login first: Terraform will fail the same way.

1. Make the project folder

   TerminalCopy

   mkdir quickcart-tf

   Part	What it means
   mkdir	make a directory
   quickcart-tf	its name. Later lessons build on this folder

   TerminalCopy

   cd quickcart-tf

   Part	What it means
   cd	change directory. Every later command runs in here
   quickcart-tf	the folder you just made

2. Write the code

   Create main.tf in that folder:

   main.tfCopy

   terraform {
     required_version = ">= 1.10.0"
   
     required_providers {
       aws = {
         source  = "hashicorp/aws"
         version = "~> 6.0"
       }
     }
   }
   
   provider "aws" {
     region = "us-east-1"
   }
   
   resource "aws_ecr_repository" "orders" {
     name                 = "quickcart-orders"
     image_tag_mutability = "IMMUTABLE"
     force_delete         = true
   
     tags = {
       Project = "quickcart"
     }
   }

   Setting	What it does	If you leave it out	When you’d change it
   terraform block	Settings for Terraform itself, not for AWS	Terraform runs with no version rules at all	—
   required_version	Refuse to run on a Terraform older than 1.10	An older Terraform may fail later, with a confusing error	When you start using a newer Terraform feature
   required_providers → aws	Which provider this code needs, under the local name aws	Terraform guesses hashicorp/aws and takes the newest version, even a new major one	When you add another provider
   source	Where to download it: hashicorp/aws on the public Terraform Registry	Terraform assumes hashicorp/aws. Saying it is clearer	Almost never
   version	Which versions are allowed: any 6.x	Always the newest, which one day brings breaking changes	When you deliberately move to a new major version
   provider "aws"	Settings for the AWS provider	Terraform still uses the provider, with default settings	—
   region	Where the resources are built	Terraform uses the region from your AWS login settings, which may not be what you expect	To build somewhere else
   resource "aws_ecr_repository" "orders"	One ECR repository. orders is your code’s name for it	—	—
   name	The repository’s name in AWS	Required: plan stops with an error	Never casually. Changing it replaces the repository, as you’ll see
   image_tag_mutability	IMMUTABLE: once v1 is pushed, no other image can take that tag	Defaults to MUTABLE: someone can push a different image under an old tag	Rarely. Storing images: ECR explains why immutable is safer
   force_delete	Let terraform destroy delete the repository even if it holds images	Destroy fails while any image is inside	Set it to false for production, so images can’t be deleted by accident
   tags	Labels to find and cost everything that belongs to QuickCart	No labels. Harder to find later	Add owner and environment tags in real projects

   Now tidy the formatting:

   TerminalCopy

   terraform fmt

   Part	What it means
   terraform fmt	line up the = signs and fix the spacing in every .tf file here

   It prints the name of any file it changed, or nothing if the file was already tidy. Everyone running fmt means code reviews show real changes, not spacing.

3. Initialise the folder

   TerminalCopy

   terraform init

   Part	What it means
   terraform init	download the AWS provider and prepare this folder

   You should see

   Initializing the backend...
   
   Initializing provider plugins...
   - Finding hashicorp/aws versions matching "~> 6.0"...
   - Installing hashicorp/aws v6.66.0...
   - Installed hashicorp/aws v6.66.0 (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!

   Your version number will probably be newer. Now check the code makes sense:

   TerminalCopy

   terraform validate

   Part	What it means
   terraform validate	check the code for mistakes — wrong types, unknown settings — without contacting AWS

   You should see

   Success! The configuration is valid.

   Open .terraform.lock.hcl in your editor. It starts like this:

   The start of .terraform.lock.hcl

   # This file is maintained automatically by "terraform init".
   # Manual edits may be lost in future updates.
   
   provider "registry.terraform.io/hashicorp/aws" {
     version     = "6.66.0"
     constraints = "~> 6.0"
     hashes = [

   version is what was chosen; constraints is the range you allowed. The hashes are checksums, so a tampered download is refused. When a colleague runs init, they get exactly this version, not whatever is newest that day.

4. Keep the right files out of git

   If this folder will go into git, create a file called .gitignore next to main.tf:

   .gitignoreCopy

   .terraform/
   *.tfstate
   *.tfstate.*

   Line	What it keeps out of git
   .terraform/	the downloaded plugin: large, and init fetches it again
   *.tfstate	the state file, which can hold secrets
   *.tfstate.*	the backup copy Terraform keeps, terraform.tfstate.backup

   .terraform.lock.hcl isn’t listed, so it is committed. That’s what you want.

5. Read the plan

   TerminalCopy

   terraform plan

   Part	What it means
   terraform plan	compare the code, the state and AWS, and show what would change. Changes nothing

   You should see

   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:
   
     # aws_ecr_repository.orders will be created
     + resource "aws_ecr_repository" "orders" {
         + arn                  = (known after apply)
         + force_delete         = true
         + id                   = (known after apply)
         + image_tag_mutability = "IMMUTABLE"
         + name                 = "quickcart-orders"
         + region               = "us-east-1"
         + registry_id          = (known after apply)
         + repository_url       = (known after apply)
         + tags                 = {
             + "Project" = "quickcart"
           }
         + tags_all             = {
             + "Project" = "quickcart"
           }
       }
   
   Plan: 1 to add, 0 to change, 0 to destroy.

   Every line starts with +: all new. arn, id and repository_url are (known after apply), because AWS makes them up when it creates the repository. tags_all is your tags plus any the provider adds for every resource; here they’re the same.

6. Apply it

   TerminalCopy

   terraform apply

   Part	What it means
   terraform apply	make the plan again, show it, and carry it out once you type yes

   It shows the same plan. Read the summary line, then type yes:

   You should see

   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
   
   aws_ecr_repository.orders: Creating...
   aws_ecr_repository.orders: Creation complete after 1s [id=quickcart-orders]
   
   Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

   Check it in the console:

   AWSIn the AWS console: Amazon ECR→Private registry→Repositories

   You should see

   quickcart-orders in the list, with Tag immutability shown as immutable. Built from one short file, and you can build it again identically whenever you like.

7. Change it in place

   Add a second tag, Team. The whole file now reads:

   main.tfCopy

   terraform {
     required_version = ">= 1.10.0"
   
     required_providers {
       aws = {
         source  = "hashicorp/aws"
         version = "~> 6.0"
       }
     }
   }
   
   provider "aws" {
     region = "us-east-1"
   }
   
   resource "aws_ecr_repository" "orders" {
     name                 = "quickcart-orders"
     image_tag_mutability = "IMMUTABLE"
     force_delete         = true
   
     tags = {
       Project = "quickcart"
       Team    = "platform"
     }
   }

   Setting	What changed
   tags → Team	a second label, saying which team owns the repository. Every other setting is as before

   TerminalCopy

   terraform apply

   Part	What it means
   terraform apply	plan the tag change, show it, and carry it out once you type yes

   You should see

   Terraform will perform the following actions:
   
     # aws_ecr_repository.orders will be updated in-place
     ~ resource "aws_ecr_repository" "orders" {
           id                   = "quickcart-orders"
           name                 = "quickcart-orders"
         ~ tags                 = {
               "Project" = "quickcart"
             + "Team"    = "platform"
           }
         ~ tags_all             = {
             + "Team"    = "platform"
               # (1 unchanged element hidden)
           }
           # (6 unchanged attributes hidden)
   
           # (2 unchanged blocks hidden)
       }
   
   Plan: 0 to add, 1 to change, 0 to destroy.

   ~: the same repository, updated. Type yes:

   You should see

   aws_ecr_repository.orders: Modifying... [id=quickcart-orders]
   aws_ecr_repository.orders: Modifications complete after 1s [id=quickcart-orders]
   
   Apply complete! Resources: 0 added, 1 changed, 0 destroyed.

8. See a change that forces replacement — and don't apply it

   Now do what Theo did. Change the name to quickcart-orders-api:

   main.tfCopy

   terraform {
     required_version = ">= 1.10.0"
   
     required_providers {
       aws = {
         source  = "hashicorp/aws"
         version = "~> 6.0"
       }
     }
   }
   
   provider "aws" {
     region = "us-east-1"
   }
   
   resource "aws_ecr_repository" "orders" {
     name                 = "quickcart-orders-api"
     image_tag_mutability = "IMMUTABLE"
     force_delete         = true
   
     tags = {
       Project = "quickcart"
       Team    = "platform"
     }
   }

   Setting	What changed
   name	quickcart-orders becomes quickcart-orders-api

   This time, only plan:

   TerminalCopy

   terraform plan

   Part	What it means
   terraform plan	show what the rename would do, without doing it

   You should see

   Terraform will perform the following actions:
   
     # aws_ecr_repository.orders must be replaced
   -/+ resource "aws_ecr_repository" "orders" {
         ~ arn                  = "arn:aws:ecr:us-east-1:111122223333:repository/quickcart-orders" -> (known after apply)
         ~ id                   = "quickcart-orders" -> (known after apply)
         ~ name                 = "quickcart-orders" -> "quickcart-orders-api" # forces replacement
         ~ registry_id          = "111122223333" -> (known after apply)
         ~ repository_url       = "111122223333.dkr.ecr.us-east-1.amazonaws.com/quickcart-orders" -> (known after apply)
           tags                 = {
               "Project" = "quickcart"
               "Team"    = "platform"
           }
           # (4 unchanged attributes hidden)
       }
   
   Plan: 1 to add, 0 to change, 1 to destroy.

   There are a few more lines about the repository’s settings blocks; they don’t matter here. Read the rest:

   Line	What it tells you
   must be replaced and -/+	the repository will be destroyed, then a new one created
   # forces replacement	the name change is the cause
   repository_url ... -> (known after apply)	the address changes, so anything pushing or pulling images breaks until it’s updated
   1 to add, 1 to destroy	not a rename. A delete and a create

   Don’t apply it. Change the name back to quickcart-orders, then plan again:

   TerminalCopy

   terraform plan

   Part	What it means
   terraform plan	check the code matches what’s built again

   You should see

   No changes. Your infrastructure matches the configuration.

9. Clean-up step: Clean up

   TerminalCopy

   terraform destroy

   Part	What it means
   terraform destroy	plan the removal of everything this folder built, and carry it out once you type yes

   It shows the plan, with every line starting -. Check the summary says 1 to destroy, then type yes:

   You should see

   Plan: 0 to add, 0 to change, 1 to destroy.
   
   Do you really want to destroy all resources?
     Terraform will destroy all your managed infrastructure, as shown above.
     There is no undo. Only 'yes' will be accepted to confirm.
   
     Enter a value: yes
   
   aws_ecr_repository.orders: Destroying... [id=quickcart-orders]
   aws_ecr_repository.orders: Destruction complete after 1s
   
   Destroy complete! Resources: 1 destroyed.

   Check Amazon ECR → Private registry → Repositories: quickcart-orders has gone.

   Keep the quickcart-tf folder. Terraform state starts from it.