Zum Inhalt springen
Trainingslager IT-Trainingslager

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 du tofu apply aufrufst, ist das Root-Modul; es kann andere Module mit module "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 init lä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 .
ls

Erwartet:

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 = true hä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 -1

Erwartet:

  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 nach dem Repository ist das Unterverzeichnis, ?ref=v1.0.0 das Git-Tag. Mit https://… oder git@… statt file:// 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 console

Erwartet:

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 tag

Erwartet:

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.