Tag 5: Module
Ziel: Den notes-Stack in ein Modul mit klaren Ein- und Ausgängen packen, es mehrfach einbinden, aus einem Git-Repository mit fester Version laden und eine neue Modulversion ausrollen. · Dauer: ca. 90 min · Voraussetzung: Tag 4
Briefing
- Jedes Verzeichnis mit
.tf-Dateien ist ein Modul. Das, in dem dutofu applyaufrufst, ist das Root-Modul; es kann andere Module mitmodule "name" { … }einbinden. - Ein Modul hat Eingänge (
variable) und Ausgänge (output). Was drinnen passiert, bleibt drinnen – der Aufrufer sieht nur die Schnittstelle. - Module kommen aus einem lokalen Pfad, einem Git-Repository
(
git::…?ref=v1.0.0) oder einer Registry.tofu initlädt sie nach.terraform/modules. - Adressen bekommen den Modulnamen vorangestellt:
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: Das Modul
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 .
lsErwartet:
main.tf
nginx.conf.tftpl
outputs.tf
variables.tf
versions.tf
- Das Modul hat keinen
provider-Block. Provider konfiguriert der Aufrufer; das Modul sagt nur, welche es braucht (required_providers). sensitive = truehält das Passwort aus Plan und Ausgabe heraus (Tag 12).- Alle Namen beginnen mit
var.name– nur so können zwei Kopien nebeneinander laufen.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Zweimal einbinden
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'Erwartet:
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
Das Modul verlangt kreuzwerker/docker. Das Root-Modul
sagt aber nur provider "docker" – und ohne Angabe nimmt
OpenTofu den Namensraum hashicorp an. Jedes Modul, das
einen Provider konfiguriert, braucht deshalb seine eigene Zuordnung:
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'Erwartet:
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"]
Zwei vollständige notes-Stacks aus einem Modul, unterschieden nur durch ihre Eingänge. Den Provider konfiguriert das Root-Modul einmal; beide Modulaufrufe nutzen dieselbe Verbindung.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Modul aus Git, mit Version
Module, die mehrere Teams nutzen, liegen in einem eigenen Repository und werden mit einer festen Version eingebunden:
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 -1Erwartet:
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-dockernach dem Repository ist das Unterverzeichnis,?ref=v1.0.0das Git-Tag. Mithttps://…odergit@…stattfile://geht es genauso mit GitLab, GitHub oder Gitea.- Gleicher Code, andere Quelle: Der Plan zeigt keine Änderung. Der State hängt an den Adressen, nicht an der Herkunft des Moduls.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Eine neue Modulversion
Das Modul bekommt einen weiteren Ausgang:
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 consoleErwartet:
module was installed. Run "tofu init" to install all modules required by this
Apply complete! Resources: 0 added, 0 changed, 0 destroyed.
2
Der Plan bricht ab: Die neue Version ist noch nicht installiert. Sie
kommt erst nach tofu init an – plan allein
lädt keine Module. So wechselt niemand versehentlich die Modulversion:
Wer sie ändern will, ändert die ref und initialisiert
neu.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
tofu output -json urls | jq -c .Erwartet:
{"blau":"http://127.0.0.1:8085","gruen":"http://127.0.0.1:8086"}
git -C ~/tf-lab/module tagErwartet:
v1.0.0
v1.1.0
tofu plan -detailed-exitcode -no-color >/dev/null; echo "Exit: $?"Erwartet:
Exit: 0
Challenge
Statt zwei Blöcken module "blau" und
module "gruen" soll ein einziger Block mit
for_each über eine Map
{ blau = 8085, gruen = 8086 } beide Stacks beschreiben –
ohne dass ein Container neu angelegt wird.
Hinweis: Die Adressen ändern sich von
module.blau zu module.notes["blau"]. Ein Block
moved { from = … to = … } sagt OpenTofu, dass es dieselben
Objekte sind.
Lösung
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'Erwartet:
19
Plan: 0 to add, 0 to change, 0 to destroy.
Apply complete! Resources: 0 added, 0 changed, 0 destroyed.
19 Objekte ziehen im State um, nichts wird neu angelegt. Ohne die
moved-Blöcke hätte der Plan 19 Ressourcen gelöscht und 19
neu angelegt – samt Datenbanken. Mehr dazu an Tag 11.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Module versionieren wie Software: Semantische
Versionen, Changelog, und ein Breaking Change (umbenannte Variable,
entfernte Ressource) bekommt eine neue Hauptversion – mit
moved-Blöcken im Modul selbst. - Eine private Registry (z. B. in GitLab oder
Artifactory) macht Versionen mit
version = "~> 1.1"möglich, statt?ref=von Hand zu pflegen. - Kleine Module: Ein Modul tut eine Sache. Riesige „Alles”-Module mit Dutzenden Schaltern werden schnell unwartbar.