Skip to content
Hands-on IT IT Drills

Day 5: Modules

Goal: Package the notes stack into a module with clear inputs and outputs, call it several times, load it from a Git repository with a pinned version, and roll out a new module version. · Duration: approx. 90 min · Prerequisite: Day 4

Briefing

  • Every directory with .tf files is a module. The one where you run tofu apply is the root module; it can call other modules with module "name" { … }.
  • A module has inputs (variable) and outputs (output). What happens inside stays inside – the caller only sees the interface.
  • Modules come from a local path, a Git repository (git::…?ref=v1.0.0), or a registry. tofu init downloads them to .terraform/modules.
  • Addresses get the module name as a prefix: module.blau.docker_container.db.
 tag05/main.tf
   module "blau"  ─┐                         ┌─► blau-db, blau-api-a, blau-proxy :8085
   module "gruen" ─┴─► ~/tf-lab/module/notes-docker ─► gruen-db, gruen-api-a, … :8086
                        (variables · main · outputs)

Drill 1: The Module

M=~/tf-lab/module/notes-docker
mkdir -p "$M" && cd "$M"
cat > versions.tf <<'EOF'
terraform {
  required_version = ">= 1.13.0"
  required_providers {
    docker = {
      source  = "kreuzwerker/docker"
      version = "~> 4.6"
    }
  }
}
EOF
cat > variables.tf <<'EOF'
variable "name" {
  description = "Präfix für alle Namen, z. B. blau"
  type        = string
}

variable "port" {
  description = "Port des Proxys auf 127.0.0.1"
  type        = number
}

variable "instanzen" {
  description = "Namen der notes-api-Instanzen"
  type        = set(string)
  default     = ["a"]
}

variable "db_passwort" {
  type      = string
  sensitive = true
}
EOF
cat > main.tf <<'EOF'
locals {
  db_url = "postgres://notes:${var.db_passwort}@${var.name}-db:5432/notes"
}

data "docker_image" "notes_api" {
  name = "notes-api:0.4.0"
}

resource "docker_image" "postgres" {
  name         = "postgres:18.6-alpine"
  keep_locally = true
}

resource "docker_image" "nginx" {
  name         = "nginx:1.31.8-alpine"
  keep_locally = true
}

resource "docker_network" "netz" {
  for_each = toset(["backend", "frontend"])
  name     = "${var.name}-${each.key}"
}

resource "docker_volume" "db" {
  name = "${var.name}-db"
}

resource "docker_container" "db" {
  name  = "${var.name}-db"
  image = docker_image.postgres.image_id
  env = [
    "POSTGRES_USER=notes",
    "POSTGRES_PASSWORD=${var.db_passwort}",
    "POSTGRES_DB=notes",
  ]
  networks_advanced {
    name = docker_network.netz["backend"].id
  }
  volumes {
    volume_name    = docker_volume.db.name
    container_path = "/var/lib/postgresql"
  }
  healthcheck {
    test     = ["CMD-SHELL", "pg_isready -U notes -d notes"]
    interval = "2s"
    retries  = 15
  }
  wait = true
}

resource "docker_container" "migrate" {
  name     = "${var.name}-migrate"
  image    = data.docker_image.notes_api.id
  command  = ["migrate"]
  env      = ["NOTES_DB_URL=${local.db_url}"]
  must_run = false
  attach   = true
  networks_advanced {
    name = docker_network.netz["backend"].id
  }
  depends_on = [docker_container.db]
}

resource "docker_container" "api" {
  for_each = var.instanzen
  name     = "${var.name}-api-${each.key}"
  image    = data.docker_image.notes_api.id
  env      = ["NOTES_API_KEY=lab-api-key-123", "NOTES_DB_URL=${local.db_url}"]
  dynamic "networks_advanced" {
    for_each = docker_network.netz
    content {
      name = networks_advanced.value.id
    }
  }
  depends_on = [docker_container.migrate]
}

resource "docker_container" "proxy" {
  name  = "${var.name}-proxy"
  image = docker_image.nginx.image_id
  ports {
    internal = 80
    external = var.port
    ip       = "127.0.0.1"
  }
  networks_advanced {
    name = docker_network.netz["frontend"].id
  }
  upload {
    file = "/etc/nginx/conf.d/default.conf"
    content = templatefile("${path.module}/nginx.conf.tftpl", {
      instanzen = [for c in docker_container.api : c.name]
    })
  }
}
EOF
cat > outputs.tf <<'EOF'
output "url" {
  description = "Adresse von notes"
  value       = "http://127.0.0.1:${var.port}"
}

output "container" {
  description = "Namen aller Container"
  value = concat(
    [docker_container.db.name, docker_container.proxy.name],
    [for c in docker_container.api : c.name],
  )
}
EOF
cp ~/tf-lab/tag04/nginx.conf.tftpl .
ls

Expected:

main.tf
nginx.conf.tftpl
outputs.tf
variables.tf
versions.tf
  • The module has no provider block. The caller configures providers; the module only says which ones it needs (required_providers).
  • sensitive = true keeps the password out of the plan and output (Day 12).
  • All names start with var.name – that’s the only way two copies can run side by side.

Save your progress? Sign up for free

Drill 2: Calling It Twice

mkdir -p ~/tf-lab/tag05 && cd ~/tf-lab/tag05
cat > main.tf <<'EOF'
provider "docker" {}

module "blau" {
  source      = "../module/notes-docker"
  name        = "blau"
  port        = 8085
  instanzen   = ["a", "b"]
  db_passwort = "lab-db-pw-123"
}

module "gruen" {
  source      = "../module/notes-docker"
  name        = "gruen"
  port        = 8086
  db_passwort = "lab-db-pw-123"
}

output "urls" {
  value = { blau = module.blau.url, gruen = module.gruen.url }
}
EOF
tofu init -no-color 2>&1 | grep -E 'does not have a|Did you intend'

Expected:

hashicorp/docker: provider registry registry.opentofu.org does not have a
Did you intend to use kreuzwerker/docker? If so, you must specify that source

The module requires kreuzwerker/docker. But the root module only says provider "docker" – and without further information, OpenTofu assumes the hashicorp namespace. Every module that configures a provider therefore needs its own mapping:

cat > versions.tf <<'EOF'
terraform {
  required_version = ">= 1.13.0"
  required_providers {
    docker = {
      source  = "kreuzwerker/docker"
      version = "~> 4.6"
    }
  }
}
EOF
tofu init -no-color | grep -E 'blau|gruen|initialized'
tofu apply -auto-approve -no-color | grep 'Apply complete'
for f in blau gruen; do
  u=$(tofu output -json urls | jq -r ".$f")
  curl -s -o /dev/null -w "$f %{http_code}\n" "$u/healthz"
done
tofu state list | grep -c '^module.blau'
tofu state list | grep 'docker_container.api'

Expected:

OpenTofu has been successfully initialized!
Apply complete! Resources: 19 added, 0 changed, 0 destroyed.
blau 200
gruen 200
11
module.blau.docker_container.api["a"]
module.blau.docker_container.api["b"]
module.gruen.docker_container.api["a"]

Two complete notes stacks from one module, distinguished only by their inputs. The root module configures the provider once; both module calls use the same connection.

Save your progress? Sign up for free

Drill 3: Module from Git, with a Version

Modules that several teams use live in their own repository and are called with a pinned version:

cd ~/tf-lab/module
git init -q -b main && git add -A
git -c user.name=Lab -c [email protected] commit -qm "notes-docker 1.0.0"
git tag v1.0.0
cd ~/tf-lab/tag05
Q='git::file:///home/ubuntu/tf-lab/module//notes-docker?ref=v1.0.0'
sed -i "s|\"../module/notes-docker\"|\"$Q\"|" main.tf
grep -m1 'source' main.tf
tofu init -no-color 2>&1 | grep -E 'Downloading|initialized'
tofu plan -no-color | tail -1

Expected:

  source      = "git::file:///home/ubuntu/tf-lab/module//notes-docker?ref=v1.0.0"
Downloading git::file:///home/ubuntu/tf-lab/module?ref=v1.0.0 for blau...
Downloading git::file:///home/ubuntu/tf-lab/module?ref=v1.0.0 for gruen...
OpenTofu has been successfully initialized!
No changes. Your infrastructure matches the configuration.
  • //notes-docker after the repository is the subdirectory, ?ref=v1.0.0 the Git tag. With https://… or git@… instead of file:// it works the same way with GitLab, GitHub, or Gitea.
  • Same code, different source: the plan shows no change. The state is tied to the addresses, not to where the module comes from.

Save your progress? Sign up for free

Drill 4: A New Module Version

The module gets another output:

cd ~/tf-lab/module/notes-docker
cat >> outputs.tf <<'EOF'

output "instanzen" {
  description = "Anzahl der notes-api-Instanzen"
  value       = length(var.instanzen)
}
EOF
cd .. && git add -A
git -c user.name=Lab -c [email protected] commit -qm "Ausgang instanzen"
git tag v1.1.0
cd ~/tf-lab/tag05
sed -i 's/?ref=v1.0.0"/?ref=v1.1.0"/' main.tf
tofu plan -no-color 2>&1 | grep -m1 'tofu init'
tofu init -no-color >/dev/null
tofu apply -auto-approve -no-color | grep 'Apply complete'
echo 'module.blau.instanzen' | tofu console

Expected:

module was installed. Run "tofu init" to install all modules required by this
Apply complete! Resources: 0 added, 0 changed, 0 destroyed.
2

The plan aborts: the new version isn’t installed yet. It only arrives after tofu init – plan alone doesn’t download modules. That way nobody switches the module version by accident: if you want to change it, you change the ref and initialize again.

Save your progress? Sign up for free

Checkpoint

tofu output -json urls | jq -c .

Expected:

{"blau":"http://127.0.0.1:8085","gruen":"http://127.0.0.1:8086"}
git -C ~/tf-lab/module tag

Expected:

v1.0.0
v1.1.0
tofu plan -detailed-exitcode -no-color >/dev/null; echo "Exit: $?"

Expected:

Exit: 0

Challenge

Instead of two blocks module "blau" and module "gruen", a single block with for_each over a map { blau = 8085, gruen = 8086 } should describe both stacks – without any container being recreated.

Hint: The addresses change from module.blau to module.notes["blau"]. A moved { from = … to = … } block tells OpenTofu that these are the same objects.

Solution

cat > main.tf <<'EOF'
provider "docker" {}

locals {
  stacks = {
    blau  = { port = 8085, instanzen = ["a", "b"] }
    gruen = { port = 8086, instanzen = ["a"] }
  }
}

module "notes" {
  for_each    = local.stacks
  source      = "git::file:///home/ubuntu/tf-lab/module//notes-docker?ref=v1.1.0"
  name        = each.key
  port        = each.value.port
  instanzen   = each.value.instanzen
  db_passwort = "lab-db-pw-123"
}

moved {
  from = module.blau
  to   = module.notes["blau"]
}

moved {
  from = module.gruen
  to   = module.notes["gruen"]
}

output "urls" {
  value = { for k, m in module.notes : k => m.url }
}
EOF
tofu init -no-color >/dev/null
tofu plan -no-color > umzug.txt
grep -c 'has moved to' umzug.txt
grep 'Plan:' umzug.txt
tofu apply -auto-approve -no-color | grep 'Apply complete'

Expected:

19
Plan: 0 to add, 0 to change, 0 to destroy.
Apply complete! Resources: 0 added, 0 changed, 0 destroyed.

19 objects move within the state; nothing is recreated. Without the moved blocks, the plan would have deleted 19 resources and created 19 new ones – databases included. More on that on Day 11.

Save your progress? Sign up for free

Enterprise Note

  • Version modules like software: semantic versions, a changelog, and a breaking change (renamed variable, removed resource) gets a new major version – with moved blocks in the module itself.
  • A private registry (e.g. in GitLab or Artifactory) makes versions with version = "~> 1.1" possible, instead of maintaining ?ref= by hand.
  • Small modules: A module does one thing. Huge “everything” modules with dozens of switches quickly become unmaintainable.