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
.tffiles is a module. The one where you runtofu applyis the root module; it can call other modules withmodule "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 initdownloads 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 .
lsExpected:
main.tf
nginx.conf.tftpl
outputs.tf
variables.tf
versions.tf
- The module has no
providerblock. The caller configures providers; the module only says which ones it needs (required_providers). sensitive = truekeeps 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 -1Expected:
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-dockerafter the repository is the subdirectory,?ref=v1.0.0the Git tag. Withhttps://…orgit@…instead offile://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 consoleExpected:
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 tagExpected:
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
movedblocks 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.