Docker Compose zu Kubernetes migrieren: Anleitung

Docker Compose zu Kubernetes migrieren heißt nicht, eine YAML-Datei blind umzuwandeln. Kompose kann den Einstieg beschleunigen, doch Netzwerke, Speicher, Secrets und der Zugriff von außen brauchen anschließend eine Prüfung. Diese Anleitung führt dich von einem getesteten Compose-Projekt zu wartbaren Kubernetes-Manifests.

Stand: 17.10.2026

Auf einen Blick

• Kompose erzeugt einen ersten Satz Kubernetes-Ressourcen aus einer Compose-Datei.
• Prüfe jedes erzeugte Manifest vor dem Deployment, besonders Images, Ports, Volumes und Umgebungsvariablen.
• Persistente Daten brauchen im Cluster eine passende StorageClass und ein getestetes Backup.
• Für Updates, Skalierung und Rollbacks verwendest du Deployments und kubectl.

Wann lohnt es sich, Docker Compose zu Kubernetes zu migrieren?

Docker Compose ist für Entwicklung, Einzelserver und überschaubare Stacks sehr praktisch. Kubernetes lohnt sich dagegen, wenn mehrere Nodes, kontrollierte Rollouts, automatische Neustarts oder klar getrennte Umgebungen wichtig werden. Die Migration ist kein Muss: Ein gut gepflegtes Compose-Setup bleibt für viele Homelabs die einfachere Lösung.

Wenn du Docker Compose zu Kubernetes migrieren möchtest, beginne mit einer Anwendung, die bereits lokal zuverlässig läuft. Ein Fehler im Compose-Setup wird durch die Umwandlung nicht behoben. Teste daher Images, Datenbankverbindungen und Volumes vor dem ersten Schritt.

Welche Voraussetzungen brauchst du?

Du brauchst einen erreichbaren Cluster, eine funktionierende kubectl-Konfiguration und Zugriff auf die Container-Registry deiner Images. Für lokale Tests eignet sich etwa Minikube. Prüfe zuerst, ob der richtige Cluster aktiv ist:

kubectl config current-context
kubectl get nodes

Installiere außerdem Docker Compose und Kompose. Kompose wird vom Kubernetes-Projekt als Werkzeug für die Konvertierung von Compose-Dateien dokumentiert. Die Installationspakete und Releases findest du in der offiziellen Kompose-Dokumentation. Kontrolliere danach die installierte Version:

kompose version
docker compose version

Wie bereitest du die Compose-Datei vor?

Räume die Datei auf, bevor du Docker Compose zu Kubernetes migrierst. Verwende konkrete Image-Tags statt latest. Dokumentiere benötigte Ports, Variablen und Datenpfade. Starte den Stack anschließend lokal und lies die Logs.

1. Wechsle in das Projektverzeichnis.
2. Prüfe die aufgelöste Compose-Konfiguration.
3. Starte den Stack und teste die Anwendung funktional.

docker compose config
docker compose up -d
docker compose ps
docker compose logs --tail=100

Ein depends_on-Eintrag ist kein Ersatz für Gesundheitsprüfungen im Cluster. Definiere für Webanwendungen passende Readiness- und Liveness-Probes. Kubernetes schickt Traffic erst an bereit gemeldete Pods; bei einem Fehler kann es den Container neu starten.

Wie erzeugt Kompose Kubernetes-Manifeste?

Lege für die erzeugten Dateien ein eigenes Verzeichnis an. So bleiben dein Compose-Projekt und die Kubernetes-Konfiguration sauber getrennt. Der folgende Befehl wandelt die Compose-Datei um:

mkdir -p k8s
kompose convert --out k8s

Je nach Compose-Datei entstehen unter anderem Deployments, Services und Ressourcen für Volumes. Kompose ist dabei ein Startpunkt, kein Produktionsgenerator. Lies deshalb jede Datei. Insbesondere Namen, Labels, Service-Typen und die Anzahl der Replikate müssen zu deinem Ziel passen.

Eine typische Zuordnung sieht so aus:

Was musst du an den erzeugten Dateien anpassen?

Öffne die Manifeste vor dem Anwenden. Setze Ressourcenwünsche und -limits, damit ein einzelner Container den Node nicht unkontrolliert belastet. Ergänze außerdem Probes, wenn die Anwendung einen stabilen Health-Endpunkt anbietet. Ein Deployment ist laut Kubernetes-Dokumentation der Controller für deklarative Pod-Updates und Rollouts.

resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi
readinessProbe:
  httpGet:
    path: /health
    port: 8080
  initialDelaySeconds: 5

Übernimm keine Klartext-Passwörter aus environment in ein Repository. Lege sie als Secret an und binde sie gezielt ein. Ein Kubernetes-Secret ist jedoch keine Verschlüsselung im Git: Schütze die Quelldatei und kontrolliere den Zugriff im Cluster. Die Details beschreibt die offizielle Secret-Dokumentation.

Volumes verdienen besondere Aufmerksamkeit. Ein lokaler Host-Pfad aus Compose ist im Mehrnode-Cluster nicht automatisch verfügbar. Nutze stattdessen einen PersistentVolumeClaim, der zu deiner StorageClass passt. Prüfe das Speicher-Konzept anhand der Kubernetes-Dokumentation zu Persistent Volumes.

Wie testest du das Deployment sicher?

Erstelle zuerst einen eigenen Namespace. Damit kollidiert der Test nicht mit anderen Anwendungen. Wende anschließend nur die geprüften YAML-Dateien an und beobachte den Rollout.

1. Namespace erstellen und Manifeste anwenden.
2. Rollout und Pods prüfen.
3. Logs, Events und Services kontrollieren.

kubectl create namespace meine-app
kubectl apply -n meine-app -f k8s/
kubectl rollout status -n meine-app deployment/meine-app
kubectl get pods,svc,pvc -n meine-app
kubectl get events -n meine-app --sort-by=.lastTimestamp

Warte nicht nur auf den Status Running. Ein Pod kann laufen und trotzdem nicht bereit sein. Prüfe daher den Status READY, die Events und einen echten Aufruf der Anwendung. Für die lokale Fehlersuche kannst du einen Port temporär weiterleiten:

kubectl port-forward -n meine-app service/meine-app 8080:80

Wie gehst du mit Daten und Backups um?

Bevor du produktive Daten verschiebst, erstelle ein Backup und teste eine Wiederherstellung. Plane auch, wann Schreibzugriffe kurz pausieren müssen. Eine Datenbank im Container ist kein Backup-Konzept; sichere Daten außerhalb des Pods und dokumentiere den Restore.

Für Docker-Volumes findest du eine passende Grundlage im Beitrag Restic Docker Backup: Volumes sicher sichern. Nach der Migration brauchst du ein gleichwertiges Verfahren für die Persistent Volumes deines Clusters. Erst ein erfolgreich getesteter Restore macht das Backup belastbar.

Welche Fehler treten bei der Migration häufig auf?

• ImagePullBackOff: Das Image oder die Registry-Zugangsdaten stimmen nicht. Prüfe Image-Name, Tag und Pull-Secret.
• CrashLoopBackOff: Lies Logs und Events. Häufig fehlen Variablen, Datenbankzugriff oder ein passender Startbefehl.
• Kein Zugriff von außen: Ein ClusterIP-Service ist nur im Cluster erreichbar. Plane bei Bedarf Ingress oder einen geeigneten Service-Typ.
• Pending bei PVCs: Für die gewünschte StorageClass steht kein Speicher bereit.

Für komplexere Anwendungen helfen paketierte, versionierte Vorlagen. Der Einstieg in Helm Charts zeigt, wann Helm sinnvoller als eine lose Sammlung von YAML-Dateien sein kann.

Fazit

Wenn du Docker Compose zu Kubernetes migrieren willst, nutze Kompose für den ersten Entwurf und nicht als letzten Schritt. Prüfe Manifeste, Secrets, Speicher und Zugriffswege gezielt. Teste den Rollout in einem separaten Namespace und sichere Daten vorher. So wird aus einer schnellen Konvertierung ein wartbares Deployment.

Quellen

• Kompose: offizielle Dokumentation
• Kubernetes: Compose nach Kubernetes übertragen
• Kubernetes: Deployments
• Kubernetes: Persistent Volumes

Häufige Fragen