Resources, providers and state

In the previous course, you created a managed database, a bucket and a container service by clicking in a console or typing commands. That works once. But how do you recreate exactly the same thing for staging? How do you know who changed a firewall rule, and when? Infrastructure as code (IaC) answers these questions: the infrastructure is described in text files, versioned in Git, reviewed in code review and applied by a tool.

Terraform (and its open source fork OpenTofu, compatible for most of this course) is the most widely used IaC tool for driving several clouds with a single language, HCL (HashiCorp Configuration Language).

A declarative approach

You do not describe the steps (“create a bucket, then enable versioning”), but the desired state (“a versioned bucket with this name exists”). Terraform compares this desired state with what exists and works out the actions itself. Re-running the same configuration does not create duplicates: if everything already matches, there is nothing to do.

A first main.tf file

terraform {
  required_version = ">= 1.6"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = "eu-west-3"   # Paris
}

resource "aws_s3_bucket" "exports" {
  bucket = "atelier-nova-exports-prod"
  tags = {
    projet = "exports"
    gere_par = "terraform"
  }
}

• The terraform block pins the version of Terraform and of the providers.
• A provider is a plugin that translates your resources into API calls (AWS, Google Cloud, Azure, Scaleway, GitHub…). There are also utility providers such as hashicorp/local (local files) and hashicorp/random (random values), perfect for practicing without a cloud account.
• A resource "TYPE" "NAME" block declares an object. Its address is TYPE.NAME, here aws_s3_bucket.exports. The local name is used to reference it elsewhere: aws_s3_bucket.exports.arn.

The workflow

terraform init       # downloads the providers, creates .terraform/ and .terraform.lock.hcl
terraform plan       # computes what will change, without modifying anything
terraform apply      # shows the plan, asks for "yes", then executes
terraform destroy    # removes all resources managed by this configuration

The plan is the key moment. Read its symbols:

Symbol	Meaning
+	creation
~	in-place modification
-/+	destroy then recreate (replacement)
-	destruction

It ends with a summary such as Plan: 1 to add, 0 to change, 0 to destroy. An unexpected replacement (-/+) on a database means data loss: this is exactly what reading the plan should catch. The # forces replacement note tells you which attribute causes the replacement.

The .terraform.lock.hcl file records the exact provider versions: it is committed to Git, so that the whole team and CI use the same ones. The .terraform/ folder is not committed.

The state file

After an apply, Terraform writes terraform.tfstate, a JSON file that maps each address (aws_s3_bucket.exports) to the real object (its identifier at AWS) and its attributes. Without it, Terraform would not know the bucket already exists and would try to create it again.

terraform state list                       # managed addresses
terraform state show aws_s3_bucket.exports # known attributes of a resource

Three rules:

1. Never edit the state by hand: use the terraform state commands or the moved and import blocks (lesson 5).
2. Never commit it to Git: it often contains sensitive values (generated passwords, keys) in plain text.
3. Never lose it: it is the memory of your infrastructure.

A locked remote backend

On a single machine, the state is a local file. In a team, you put it in a shared remote backend, encrypted and versioned, with a lock: if Alice runs an apply, Bruno cannot run a second one at the same time and corrupt the state.

terraform {
  backend "s3" {
    bucket       = "atelier-nova-tfstate"
    key          = "plateforme/prod/terraform.tfstate"
    region       = "eu-west-3"
    encrypt      = true
    use_lockfile = true   # native lock in S3 (recent Terraform versions)
  }
}

Older configurations use a DynamoDB table for the lock (dynamodb_table); the Google Cloud gcs backend locks natively. The state bucket itself is created once, separately (often by a small dedicated configuration), with versioning enabled so you can restore a previous state. After adding or changing a backend, run terraform init again: Terraform offers to migrate the existing state.