docker stack deploy: Grundlagen für Swarm Stacks in der Praxis

1. Was docker stack deploy konkret leistet

Der Befehl docker stack deploy überführt eine deklarative Compose Definition in einen vollständigen Swarm Stack, bestehend aus mehreren Services, die gemeinsam als logische Einheit verwaltet werden. Anders als docker compose up, das primär für lokale Entwicklung gedacht ist, spricht docker stack deploy direkt mit der Swarm API und erzeugt Services statt einzelner Container. Jeder Service kann in mehreren Replikaten laufen, wird vom Swarm Scheduler auf verfügbare Nodes verteilt und bei einem Ausfall automatisch neu gestartet.

Der zentrale Vorteil von docker stack deploy liegt in der Ein Schritt Bereitstellung. Eine einzige Compose Datei beschreibt Services, Netzwerke, Volumes, Secrets und Configs gemeinsam, und ein einziger Aufruf bringt alle Bestandteile in den gewünschten Zustand. Das reduziert die Fehleranfälligkeit gegenüber manuellem Anlegen einzelner Ressourcen erheblich, weil Docker die Differenz zwischen Ist Zustand und der Compose Definition selbst berechnet und nur die notwendigen Änderungen anwendet.

2. Compose Datei für Swarm anpassen

Nicht jede lokale Compose Datei funktioniert unverändert mit docker stack deploy. Der Befehl ignoriert bestimmte Felder, die nur für die lokale Entwicklung Sinn ergeben, allen voran build. Ein Stack Deployment erwartet fertige Images aus einer Registry, nicht das lokale Bauen aus einem Dockerfile. Wer lokal mit build arbeitet, muss vor dem Stack Deployment ein Image bauen, taggen und in eine erreichbare Registry pushen.

Stattdessen nutzt docker stack deploy den deploy Schlüssel der Compose Spezifikation, der lokal komplett ignoriert wird. Darin werden Replika Anzahl, Ressourcenlimits, Update Strategien und Platzierungsbeschränkungen definiert. Diese Trennung zwischen Entwicklungs relevanten und Produktions relevanten Feldern erlaubt es, dieselbe Grunddatei für beide Umgebungen zu pflegen, solange man versteht, welche Felder in welchem Kontext ausgewertet werden.

# docker-compose.prod.yml — production stack for docker stack deploy
version: "3.9"

services:
  api:
    image: registry.example.com/shop-api:1.4.0   # pre-built image, no "build" key
    ports:
      - "8080:8080"
    networks:
      - backend
    deploy:
      replicas: 4
      resources:
        limits:
          cpus: "0.50"
          memory: 512M
        reservations:
          memory: 256M
      restart_policy:
        condition: on-failure
        max_attempts: 3
      placement:
        constraints:
          - node.role == worker

  db:
    image: mysql:8.4
    volumes:
      - db-data:/var/lib/mysql
    networks:
      - backend
    deploy:
      replicas: 1
      placement:
        constraints:
          - node.labels.storage == fast-disk

networks:
  backend:
    driver: overlay

volumes:
  db-data:

3. Der erste Stack Rollout Schritt für Schritt

Ein Stack Rollout mit docker stack deploy beginnt immer mit einem initialisierten Swarm Cluster. Ohne aktiven Swarm Modus lehnt Docker den Befehl mit einer klaren Fehlermeldung ab. Ist der Cluster bereit, genügt docker stack deploy -c docker-compose.prod.yml shop, um den kompletten Stack unter dem Namen shop auszurollen. Docker legt dabei automatisch alle im Compose File definierten Netzwerke und Volumes an, sofern sie noch nicht existieren, und startet anschließend die Services in der angegebenen Replika Anzahl.

Nach dem ersten Rollout empfiehlt sich eine unmittelbare Prüfung mit docker stack services shop, um zu sehen, ob alle Services die gewünschte Anzahl an Replikaten erreicht haben. Der Zustand 4/4 in der Spalte REPLICAS zeigt, dass alle vier Instanzen erfolgreich gestartet sind. Weicht die Zahl ab, etwa 2/4, lohnt sich der Blick in die Task Historie, um zu verstehen, warum einzelne Replikate nicht starten konnten.

# Verify Swarm mode is active before deploying
docker info --format '{{.Swarm.LocalNodeState}}'

# Deploy the full stack from a compose file
docker stack deploy -c docker-compose.prod.yml shop

# Check rollout status: replica counts per service
docker stack services shop

# Watch tasks for a specific service in real time
watch -n 2 'docker service ps shop_api --no-trunc'

4. Netzwerke und Volumes im Stack Kontext

Netzwerke innerhalb eines docker stack deploy Rollouts sind standardmäßig Overlay Netzwerke, die Container Kommunikation über mehrere Nodes hinweg ermöglichen. Anders als das Standard Bridge Netzwerk von docker compose up funktioniert ein Overlay Netzwerk clusterweit, sodass ein Service auf Node A einen Service auf Node B über dessen Namen erreichen kann, ohne dass IP Adressen manuell verwaltet werden müssen. Jeder Stack erhält außerdem automatisch ein eigenes Default Netzwerk mit dem Präfix des Stack Namens, sofern kein explizites Netzwerk definiert wurde.

Volumes verhalten sich in einem Swarm Stack anders als viele erwarten. Ein benanntes Volume wird lokal auf dem Node erstellt, auf dem der jeweilige Container Task läuft, nicht automatisch clusterweit repliziert. Bei einem Datenbank Service mit nur einem Replikat und einer festen Node Platzierungsregel ist das unkritisch, bei mehreren Replikaten, die auf verschiedene Nodes verteilt werden, braucht es dagegen eine externe Storage Lösung wie NFS, GlusterFS oder einen Cloud Storage Treiber, damit alle Instanzen auf dieselben Daten zugreifen.

5. Secrets und Configs statt Umgebungsvariablen

docker stack deploy unterstützt native Secrets und Configs, die deutlich sicherer sind als Umgebungsvariablen in der Compose Datei. Ein Secret wird verschlüsselt im Raft Log der Swarm Manager gespeichert und nur zur Laufzeit als temporäre Datei unter /run/secrets/ in den Container gemountet, niemals als Umgebungsvariable, die in Logs oder Prozesslisten sichtbar werden könnte. Configs funktionieren ähnlich, sind aber für nicht sensible Konfigurationsdateien wie Nginx Templates oder Anwendungskonfigurationen gedacht.

Der Workflow beginnt mit dem Anlegen des Secrets über die Docker CLI, bevor der Stack referenziert wird. Ändert sich ein Secret Wert, muss ein neues Secret mit neuem Namen angelegt und im Compose File referenziert werden, ein bestehendes Secret lässt sich aus Sicherheitsgründen nicht nachträglich ändern. Dieses Verhalten erzwingt eine saubere Versionierung sensibler Werte, verhindert aber auch, dass ein einzelner falscher Wert unbemerkt alle laufenden Container beeinflusst.

# Create a secret from a file (never commit the source file to git)
docker secret create db_password ./secrets/db_password.txt

# Create a config from a template file
docker config create nginx_conf ./config/nginx.conf

# Reference both in the compose file under the "secrets" and "configs" keys,
# then deploy — Docker mounts them at runtime automatically
docker stack deploy -c docker-compose.prod.yml shop

# List currently registered secrets and configs
docker secret ls
docker config ls

6. Stack Updates und erneutes Deployment

Ein wesentlicher Vorteil von docker stack deploy ist die Idempotenz des Befehls. Ein erneuter Aufruf mit derselben Compose Datei, aber geändertem Image Tag, aktualisiert nur die betroffenen Services und lässt unveränderte Services unangetastet. Docker vergleicht die neue Definition mit dem aktuellen Zustand und wendet ausschließlich die Differenz an, statt den kompletten Stack neu zu erstellen. Das macht wiederholte Deployments sicher und vorhersehbar, auch wenn sich zwischen zwei Rollouts nur ein einzelner Wert geändert hat.

Für Rolling Updates einzelner Services greift die update_config Sektion im deploy Block, die Parallelität und Verzögerung zwischen den Batches steuert. Ein erneutes docker stack deploy mit aktualisiertem Image Tag löst automatisch einen Rolling Update aus, bei dem die alten Container schrittweise durch neue ersetzt werden, ohne dass der Service komplett offline geht. Diese Eigenschaft macht den Befehl zum zentralen Werkzeug für kontinuierliche Deployments in CI Pipelines.

7. Diagnose: Stack, Services und Tasks inspizieren

Wenn ein Rollout nicht wie erwartet läuft, liefert die Docker CLI mehrere Ebenen der Diagnose. docker stack ps shop zeigt alle Tasks des gesamten Stacks mit ihrem aktuellen Status, inklusive fehlgeschlagener Versuche und deren Fehlermeldungen. Diese Übersicht ist der erste Anlaufpunkt, wenn Replikate nicht die gewünschte Anzahl erreichen, weil sie sofort zeigt, ob ein Task wiederholt neu gestartet wird oder dauerhaft im Zustand Rejected hängen bleibt.

Für tiefere Diagnose einzelner Services liefert docker service logs shop_api die zusammengeführten Logs aller Replikate eines Services, was besonders hilfreich ist, wenn ein Fehler nur auf bestimmten Nodes auftritt. docker service inspect shop_api --pretty zeigt die vollständige Konfiguration inklusive angewendeter Ressourcenlimits und Platzierungsregeln, was oft aufdeckt, dass ein Constraint versehentlich keinen passenden Node im Cluster findet.

# Show all tasks in the stack, including failed attempts
docker stack ps shop --no-trunc

# Aggregate logs from all replicas of a single service
docker service logs -f shop_api

# Full configuration dump for troubleshooting placement issues
docker service inspect shop_api --pretty

# Force a full re-evaluation of a stuck service
docker service update --force shop_api

8. Typische Stolperfallen bei docker stack deploy

Der häufigste Fehler beim ersten Einsatz von docker stack deploy ist die Verwendung eines build Schlüssels, der stillschweigend ignoriert wird. Das Ergebnis ist eine Fehlermeldung, dass ein Image nicht gefunden werden kann, obwohl es lokal existiert, weil der Swarm nicht auf dem lokalen Image Cache des Entwicklungsrechners zugreift. Jeder Node im Cluster muss das referenzierte Image entweder selbst gebaut haben oder aus einer für alle Nodes erreichbaren Registry ziehen können.

Ein zweiter häufiger Fehler betrifft Platzierungsregeln, die keinen passenden Node finden. Ein Constraint wie node.labels.storage == fast-disk führt dazu, dass ein Service dauerhaft im Zustand Pending verharrt, wenn kein Node dieses Label trägt. Der Task Status zeigt in diesem Fall meist eine unauffällige Meldung wie no suitable node, die leicht übersehen wird, wenn man nur die Replika Zahl in der Übersicht prüft, statt die Task Details anzusehen.

9. docker stack deploy im Vergleich zu docker compose up

Beide Befehle nutzen dieselbe Grundsyntax, unterscheiden sich aber deutlich im Zielverhalten. Die folgende Tabelle stellt die wichtigsten Unterschiede gegenüber, die beim Übergang von lokaler Entwicklung zu Produktion relevant werden.

In der Praxis pflegen viele Teams zwei Compose Dateien: eine Basisdatei mit gemeinsamen Einstellungen und eine Overlay Datei speziell für docker stack deploy, die per docker compose -f base.yml -f prod.yml config zusammengeführt und anschließend an den Stack Befehl übergeben wird. Diese Trennung hält Entwicklungs und Produktionsfelder sauber getrennt, ohne zwei komplett unabhängige Dateien pflegen zu müssen.

10. Zusammenfassung

docker stack deploy ist der zentrale Befehl für produktive Swarm Deployments und ersetzt manuelles Anlegen einzelner Services durch eine deklarative, wiederholbare Definition. Die Compose Datei muss dabei bewusst für Produktion angepasst werden: kein build Schlüssel, dafür der deploy Block mit Replika Anzahl, Ressourcenlimits und Update Strategie. Native Secrets und Configs ersetzen unsichere Umgebungsvariablen und werden verschlüsselt im Cluster verwaltet.

Die Diagnose Werkzeuge docker stack ps, docker service logs und docker service inspect decken die häufigsten Probleme ab, von fehlenden Images bis zu unerfüllbaren Platzierungsregeln. Wer diese Grundlagen einmal verstanden hat, kann docker stack deploy zuverlässig in CI Pipelines integrieren und erhält damit einen reproduzierbaren, versionierten Deployment Prozess ohne manuellen Eingriff auf dem Server.

11. FAQ: docker stack deploy