Tag 11: Import, moved, removed
Ziel: Von Hand angelegte Ressourcen in OpenTofu übernehmen, Ressourcen umbenennen, ohne sie neu zu bauen, und Ressourcen aus der Verwaltung entlassen, ohne sie zu löschen. · Dauer: ca. 75 min · Voraussetzung: Tag 9
Briefing
- Altlasten gibt es überall: Ressourcen, die jemand
vor OpenTofu von Hand angelegt hat. Ein
import-Block trägt sie in den State ein. Danach verwaltet OpenTofu sie wie selbst gebaute. tofu plan -generate-config-out=datei.tfschreibt zu jedem Import einen Konfigurationsvorschlag. Der ist ein Rohentwurf – aufräumen musst du selbst.- Ein
moved-Block sagt OpenTofu: „Diese Ressource heißt jetzt anders.“ Ohne ihn plant OpenTofu Löschen und Neuanlegen. - Ein
removed-Block nimmt eine Ressource aus dem State. Mitdestroy = falsebleibt sie in der echten Welt stehen.
von Hand import moved removed
─────────► [ State ] ───► [ neuer Name ] ───► nicht mehr verwaltet
docker volume create gleiche Ressource Ressource bleibt
Drill 1: Altlasten von Hand anlegen
So sieht es aus, wenn jemand vor dir am Werk war:
docker network create altnetz
docker volume create altdaten
docker run -d --name altweb --network altnetz -v altdaten:/usr/share/nginx/html \
-p 127.0.0.1:8099:80 nginx:1.31.8-alpine
docker exec altweb sh -c 'echo "Altdaten von Hand" > /usr/share/nginx/html/index.html'
curl -s http://127.0.0.1:8099/Erwartet (die IDs weichen ab):
0657c4de822c...
altdaten
93aefacb57ba...
Altdaten von Hand
Fortschritt speichern? Kostenlos registrieren
Drill 2: Import mit generierter Konfiguration
mkdir -p ~/tf-lab/tag11 && cd ~/tf-lab/tag11
sed 's|tag05/terraform.tfstate|tag11/terraform.tfstate|' ~/tf-lab/tag05/backend.tf \
> backend.tf
cp ~/tf-lab/tag05/versions.tf .
NETZ_ID=$(docker network ls -q --no-trunc --filter name=^altnetz$)
cat > import.tf <<EOF
provider "docker" {}
import {
to = docker_volume.altdaten
id = "altdaten"
}
import {
to = docker_network.altnetz
id = "$NETZ_ID"
}
EOF
tofu init -no-color >/dev/null
tofu plan -generate-config-out=generated.tf -no-color | grep -E 'Warning|Plan:'
cat generated.tfErwartet (Gateway und Subnetz können abweichen):
Plan: 2 to import, 0 to add, 0 to change, 0 to destroy.
Warning: Config generation is experimental
# __generated__ by OpenTofu
# Please review these resources and move them into your main configuration files.
# __generated__ by OpenTofu from "altdaten"
resource "docker_volume" "altdaten" {
driver = "local"
driver_opts = {}
name = "altdaten"
}
# __generated__ by OpenTofu from "0657c4de822c..."
resource "docker_network" "altnetz" {
attachable = false
driver = "bridge"
...
ipam_config {
aux_address = {}
gateway = "172.28.0.1"
ip_range = ""
subnet = "172.28.0.0/16"
}
}
- Die ID hängt vom Ressourcentyp ab: beim Volume der Name, beim Netzwerk die volle ID. Welche ID ein Typ erwartet, steht in der Provider-Doku im Abschnitt Import.
- Der generierte Code schreibt jedes Attribut aus, auch Standardwerte. Für Volume und Netzwerk ist das harmlos, du räumst ihn in Drill 4 auf.
Erst importieren, dann prüfen, dass nichts mehr zu tun ist:
tofu apply -auto-approve -no-color | grep 'Apply complete'
tofu plan -no-color | tail -1
tofu state listErwartet:
Apply complete! Resources: 2 imported, 0 added, 0 changed, 0 destroyed.
No changes. Your infrastructure matches the configuration.
docker_network.altnetz
docker_volume.altdaten
Ein Import ist erst fertig, wenn der Plan danach leer ist. Die
import-Blöcke kannst du stehen lassen – auf schon
importierte Ressourcen wirken sie nicht mehr. Viele Teams löschen sie
nach dem Merge, damit der Code aufgeräumt bleibt.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Die Container-Falle
Jetzt der Container. Der Ablauf ist derselbe:
WEB_ID=$(docker ps -q --no-trunc --filter name=^altweb$)
cat > import-web.tf <<EOF
import {
to = docker_container.altweb
id = "$WEB_ID"
}
EOF
tofu plan -generate-config-out=web.tf -no-color 2>&1 | grep -m1 '^Error'
grep -n 'cpu_set' web.tf
wc -l < web.tfErwartet:
Error: '' doesn't match the pattern '^\d+([,-]\d+)*$'
13: cpu_set = ""
64
Der Vorschlag für den Container hat über 60 Zeilen und ist nicht einmal gültig. Du schreibst die Konfiguration darum selbst, nur mit dem, was wirklich zählt:
cat > web.tf <<'EOF'
resource "docker_container" "altweb" {
name = "altweb"
image = "nginx:1.31.8-alpine"
networks_advanced {
name = docker_network.altnetz.id
}
volumes {
volume_name = docker_volume.altdaten.name
container_path = "/usr/share/nginx/html"
}
ports {
internal = 80
external = 8099
ip = "127.0.0.1"
}
}
EOF
tofu plan -no-color > plan.txt
grep -E '^ [~+-] [a-z_]+ .*forces replacement' plan.txt | tr -s ' '
grep 'Plan:' plan.txtErwartet:
+ env = (known after apply) # forces replacement
~ network_mode = "altnetz" -> "bridge" # forces replacement
+ networks_advanced { # forces replacement
+ ports { # forces replacement
+ volumes { # forces replacement
Plan: 1 to import, 1 to add, 0 to change, 1 to destroy.
Lies die letzte Zeile genau: „1 to import, 1 to add, 1 to destroy“. OpenTofu würde den Container importieren und sofort ersetzen. Der Docker-Provider liest beim Import nicht alle Container-Attribute zurück – es bleiben Lücken, die eine Ersetzung erzwingen.
Hier ist das vertretbar: Der Container hält keine Daten, die Seite liegt im Volume. Bei einer Datenbank-VM würdest du an dieser Stelle abbrechen. Dieser Container wird ersetzt:
tofu apply -auto-approve -no-color | grep 'Apply complete'
curl -s http://127.0.0.1:8099/
tofu plan -no-color | tail -1Erwartet:
Apply complete! Resources: 1 imported, 1 added, 0 changed, 1 destroyed.
Altdaten von Hand
No changes. Your infrastructure matches the configuration.
Der Container ist neu, die Daten im Volume sind geblieben.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Aufräumen und umbenennen mit moved
Die Namen altdaten und altnetz passen nicht
mehr. Im Code soll es daten und netz heißen –
die echten Docker-Namen bleiben. Zuerst ohne moved:
rm generated.tf import.tf import-web.tf plan.txt
cat > daten.tf <<'EOF'
resource "docker_volume" "daten" {
name = "altdaten"
}
EOF
cat > netz.tf <<'EOF'
resource "docker_network" "netz" {
name = "altnetz"
ipam_config {
subnet = "172.28.0.0/16"
gateway = "172.28.0.1"
}
}
EOF
printf 'provider "docker" {}\n' > provider.tf
sed -i 's/docker_network.altnetz/docker_network.netz/' web.tf
sed -i 's/docker_volume.altdaten/docker_volume.daten/' web.tf
tofu plan -no-color | grep -E 'will be (created|destroyed)|Plan:'Erwartet:
# docker_network.altnetz will be destroyed
# docker_network.netz will be created
# docker_volume.altdaten will be destroyed
# docker_volume.daten will be created
Plan: 3 to add, 0 to change, 3 to destroy.
Für OpenTofu ist ein neuer Name eine neue Ressource. Das Volume samt
Daten wäre weg – und der Container würde gleich mit ersetzt. Ein
moved-Block verhindert das:
cat > moved.tf <<'EOF'
moved {
from = docker_volume.altdaten
to = docker_volume.daten
}
moved {
from = docker_network.altnetz
to = docker_network.netz
}
EOF
tofu plan -no-color | grep -E 'has moved|Plan:|No changes'Passen die Werte, meldet der Plan nur die Umbenennung (Subnetz und Gateway aus deinem Lauf aus Drill 2 übernehmen, falls sie abweichen):
# docker_network.altnetz has moved to docker_network.netz
# docker_volume.altdaten has moved to docker_volume.daten
Plan: 0 to add, 0 to change, 0 to destroy.
tofu apply -auto-approve -no-color | grep 'Apply complete'
tofu state listErwartet:
Apply complete! Resources: 0 added, 0 changed, 0 destroyed.
docker_container.altweb
docker_network.netz
docker_volume.daten
movedgilt auch für Module (module.alt→module.neu) und für den Wechsel voncountzufor_each(docker_volume.x[0]→docker_volume.x["a"]).- Der Block bleibt stehen, solange irgendwo noch ein State mit dem alten Namen existiert – bei einem Modul, das andere Teams nutzen, über mehrere Versionen.
tofu state mvmacht dasselbe auf der Kommandozeile, hinterlässt aber keine Spur im Code. Einmoved-Block durchläuft Review und Plan wie jede andere Änderung.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Aus der Verwaltung entlassen mit removed
Das Netzwerk soll künftig das Plattform-Team verwalten. Du nimmst es aus deinem State, ohne es zu löschen. Der Container braucht die Netzwerk-ID aber weiterhin. Die liefert künftig eine Datenquelle – sie liest, verwaltet aber nicht:
sed -i 's/docker_network.netz.id/data.docker_network.netz.id/' web.tf
cat > netz.tf <<'EOF'
data "docker_network" "netz" {
name = "altnetz"
}
EOF
cat > moved.tf <<'EOF'
moved {
from = docker_volume.altdaten
to = docker_volume.daten
}
EOF
cat > removed.tf <<'EOF'
removed {
from = docker_network.netz
lifecycle {
destroy = false
}
}
EOF
tofu plan -no-color | grep -oE 'docker_network.netz will be removed.*|Plan:.*'Erwartet:
docker_network.netz will be removed from the OpenTofu state but will not be destroyed
Plan: 0 to add, 0 to change, 0 to destroy, 1 to forget.
„1 to forget“ ist die neue Kategorie: raus aus dem State, die Ressource bleibt.
tofu apply -auto-approve -no-color | grep 'Apply complete'
tofu state list
docker network ls --format '{{.Name}}' | grep altnetzErwartet:
Apply complete! Resources: 0 added, 0 changed, 0 destroyed, 1 forgotten.
data.docker_network.netz
docker_container.altweb
docker_volume.daten
altnetz
Die Datenquelle steht auch im State – sie wird bei jedem Plan neu gelesen.
Ohne lifecycle { destroy = false } würde OpenTofu das
Netzwerk löschen – removed ist dann nur ein ausdrücklicher
Weg, eine Ressource abzuschaffen.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
cd ~/tf-lab/tag11 && tofu plan -no-color | tail -1Erwartet:
No changes. Your infrastructure matches the configuration.
tofu state list | grep -c '^docker_'Erwartet: Container und Volume, das Netzwerk nicht mehr.
2
curl -s http://127.0.0.1:8099/Erwartet:
Altdaten von Hand
Challenge
Lege von Hand ein weiteres Volume fremd an und übernimm
es – diesmal mit dem Kommandozeilenbefehl tofu import statt
mit einem Block. Der Plan muss danach leer sein.
Hinweis: tofu import braucht die
Ressource schon in der Konfiguration.
Lösung
cd ~/tf-lab/tag11
docker volume create fremd
cat > fremd.tf <<'EOF'
resource "docker_volume" "fremd" {
name = "fremd"
}
EOF
tofu import -no-color docker_volume.fremd fremd | grep 'Import successful'
tofu plan -no-color | tail -1Erwartet:
fremd
Import successful!
No changes. Your infrastructure matches the configuration.
tofu import ändert den State sofort, ohne Plan und ohne
Review. Der import-Block ist darum der bessere Weg im Team
– er läuft durch Pull-Request und Plan.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Import in Etappen: Große Altbestände übernimmt man Ressource für Ressource, mit einem leeren Plan nach jedem Schritt. Ein Import, der „nebenbei“ ersetzt, ist ein Ausfall.
- Generierten Code nie ungeprüft übernehmen: Er schreibt Standardwerte und Laufzeit-Details fest. Gekürzter, eigener Code ist lesbarer und verträgt Provider-Updates besser.
- Refactoring ohne Ausfall:
movedundremovedmachen Umbauten im Code reviewbar. Sie gehören in denselben Pull-Request wie die Umbenennung selbst.