dockup.yaml: Config as Code sicher planen und anwenden

dockup.yaml macht aus der Service-Konfiguration ein überprüfbares Repository-Artefakt. Statt sich auf den bekannten Zustand eines Dashboards zu verlassen, kann ein Team Branch, Port, Build- und Startbefehle, Health Checks, normale Umgebungswerte und Domains in einer Datei deklarieren.

Dockup trennt Inspektion und Mutation. dockup plan zeigt die Unterschiede zwischen dem Manifest und dem Live-Service, ohne Änderungen vorzunehmen. dockup up wendet die deklarierten Änderungen an. Das Löschen bleibt über --prune eine explizite Opt-in-Aktion.

Was kann dockup.yaml deklarieren?

Ein Service-Manifest kann die produktiven Einstellungen enthalten, die von Code-Reviews profitieren:

service:
  branch: main
  port: 3000
  dockerfile: Dockerfile
  build: npm run build
  start: npm start
  healthcheck:
    path: /health
    interval: 5
    timeout: 3
    retries: 5
  env:
    NODE_ENV: production
    API_URL: https://api.example.com
  domains:
    - api.example.com
    - { domain: admin.example.com, port: 4000 }

Die Datei liegt standardmäßig im Root-Verzeichnis des Repositorys. Mit --file lässt sich ein anderer Pfad auswählen.

Lege keine Secrets im env-Mapping ab. Das Manifest wird wie andere Quelldateien committed, reviewed, gecacht und kopiert. Verwende für Zugangsdaten dockup env set --secret oder einen freigegebenen Prozess zur Secret-Injection.

Der Verbrauch von CPU, RAM und Speicherplatz bleibt nutzungsbasiert und wird pro Minute gegen das Guthaben des Plans gemessen. Das Manifest sollte daher die Service-Konfiguration und nicht Annahmen zur Abrechnung beschreiben.

Wie zeigt dockup plan Configuration Drift?

Führe vor jedem Apply einen schreibgeschützten Vergleich aus:

dockup plan production/api --json

Das Ergebnis enthält Änderungen mit Aspekten, Feldern, alten und neuen Werten sowie Aktionen. Ein Plan kann beispielsweise anzeigen, dass sich der Branch geändert hat, ein Health-Pfad abweicht, eine Domain hinzugefügt wird oder ein normaler Umgebungswert abgewichen ist.

Ein Plan ist in fünf Situationen besonders wertvoll:

Situation	Was der Plan zeigt
Pull-Request ändert das Manifest	Beabsichtigte Auswirkung auf die Produktion vor dem Merge
Dashboard wurde manuell bearbeitet	Abweichung von der Quelle im Repository
Agent schlägt eine Aktualisierung vor	Die genauen Felder, die der Agent ändern möchte
Wiederherstellung nach einem Incident	Ob der Live-Zustand bereits von der bekannten Konfiguration abweicht
Multi-Environment-Setup	Unterschiede zwischen Produktions- und Staging-Manifesten

Das Erstellen eines Plans sperrt den Service nicht. Der Live-Zustand kann sich zwischen Plan und Apply ändern. In risikoreichen Workflows sollten Review und up daher zeitlich eng aufeinanderfolgen, außerdem sollte das Apply-Ergebnis geprüft werden.

Ein Coding-Agent sollte das Plan-JSON oder eine knappe Zusammenfassung der einzelnen Felder zurückgeben. „Konfiguration sieht gut aus“ ist kein ausreichendes Review-Artefakt.

Wie wendet dockup up Config as Code an?

Wende das Standardmanifest an:

dockup up production/api --json

Wende es an und starte anschließend ein Deployment:

dockup up production/api --deploy --json

Verwende für Staging eine andere Datei:

dockup plan production/api \
  --file dockup.production.yaml \
  --json

dockup up production/api \
  --file dockup.production.yaml \
  --deploy \
  --json

Das Apply-Ergebnis zeigt, welche Änderungen angewendet oder übersprungen wurden. Bei Verwendung von --deploy kann es außerdem die Deployment-ID enthalten. Das anschließende Deployment sollte, sofern relevant, trotzdem anhand seines finalen Zustands geprüft werden. Eine Änderung der Konfiguration und ein gesundes Release in der Produktion sind zwei getrennte Ergebnisse.

Secret-Werte bleiben außerhalb des Manifests. Setze sie vor dem Anwenden der Konfiguration über den Secret-Environment-Workflow, führe anschließend das Deployment aus und prüfe den resultierenden Container, ohne den gespeicherten Wert auszugeben.

Warum ist Config as Code standardmäßig additiv?

Die sicherste Interpretation eines unvollständigen Manifests lautet: „Verwalte die hier deklarierten Werte“ – nicht: „Lösche alles andere“. Deshalb lässt Dockup Umgebungsvariablen und Domains, die in der Datei fehlen, unverändert.

Das ist bei einer schrittweisen Einführung wichtig. Ein Service kann bereits Secret-Variablen, operative Domains oder temporäre Konfiguration enthalten, die noch nicht modelliert wurde. Das erste up sollte diese Werte nicht löschen.

Die Sicherheitsgarantien sind konkret:

• dockup up löscht keine Services, Datenbanken oder Volumes.
• Vorhandene Secret-Variablen werden nicht durch normale Manifest-Werte überschrieben.
• Secret-Variablen werden nicht durch Prune entfernt.
• Eine automatische Manifest-Anwendung während des Deployments ist additiv.
• Ein ungültiges Manifest führt nicht stillschweigend zu einer destruktiven Bereinigung.

Das additive Verhalten macht dockup.yaml für einen schrittweisen GitOps-Workflow geeignet. Gleichzeitig bedeutet es, dass das Manifest nicht automatisch ein vollständiges Inventar darstellt, solange das Team Pruning für die unterstützten Felder nicht bewusst einführt.

Wie sollte --prune reviewed werden?

--prune entfernt normale Umgebungswerte und Domains, die vom Manifest nicht erfasst werden:

dockup plan production/api --json
dockup up production/api --prune --json

Behandle das Flag als destruktive Anforderung. Reviewe den Plan, benenne das genaue Ziel und hole bei einem Agenten, der in der Produktion arbeitet, eine menschliche Freigabe ein.

Die Aktion erstreckt sich nicht auf Secrets, Services, Datenbanken oder Volumes. Diese Ressourcen haben eigene Lebenszyklen und Bestätigungswege. Durch diese Trennung wird verhindert, dass eine kleine Manifeständerung eine weitreichende Löschung von Infrastruktur auslöst.

Eine hilfreiche Freigabe dokumentiert: „Wende dockup.yaml auf production/api an und entferne die zwei normalen Variablen und eine Domain, die in Plan X angezeigt werden.“ Sie sollte keine pauschale, wiederverwendbare Erlaubnis für zukünftige Pläne sein.

Das übergeordnete Bestätigungsmodell wird in Produktionsleitplanken für AI-Agenten erläutert.

Wie betreiben Teams mit dockup.yaml einen GitOps-Workflow?

Halte den Workflow einfach:

1. Ein Entwickler oder Agent bearbeitet dockup.yaml.
2. CI validiert die YAML-Syntax und führt Anwendungstests aus.
3. Ein schreibgeschütztes dockup plan läuft gegen das vorgesehene Ziel.
4. Der Pull-Request zeigt sowohl den Source-Diff als auch den Plan des Live-Zustands.
5. Ein Reviewer genehmigt die Änderung.
6. dockup up --deploy wendet sie an.
7. Das Deployment wartet auf den finalen Erfolg.
8. Status, Logs und Audit-Nachweise werden aufbewahrt.

Das Manifest sollte nicht zu einer Ablage für alles Mögliche werden. Die fachliche Anwendungskonfiguration gehört, sofern passend, in die Anwendung. Verwende dockup.yaml für Deployment- und Runtime-Einstellungen, die an der Service-Grenze verwaltet werden.

Umgebungsspezifische Dateien können klarer sein als eine einzelne Datei mit einer undokumentierten Templating-Schicht. Verwende beispielsweise dockup.staging.yaml und dockup.production.yaml und übergib die gewünschte Datei explizit.

Ein Branch-Preview ist ein isoliertes Deployment, während die Produktionskonfiguration ein separates Review-Ziel bleibt. In Projekten mit Private Networking können Previews dem Projektnetzwerk beitreten und schreibgeschützten Zugriff auf Datenbanken erhalten, ohne das Produktionsmanifest zu ändern.

Verwende den Leitfaden zu Umgebungsvariablen und Secrets für den Umgang mit Zugangsdaten und Zero-Downtime-Deployments für den Readiness-Gate.

Runbook für den Umgang mit Drift

Wenn dockup plan unerwartete Änderungen im Live-Zustand meldet, überschreibe sie nicht automatisch. Ermittle, ob die Dashboard-Änderung eine Notfallkorrektur, eine nicht autorisierte Änderung oder eine beabsichtigte Einstellung war, die nie committed wurde.

Wähle anschließend eine einzige Quelle der Wahrheit:

• Aktualisiere das Manifest, um den beabsichtigten Live-Wert beizubehalten.
• Wende das Manifest an, um den reviewed Wert wiederherzustellen.
• Dokumentiere eine temporäre Ausnahme mit Verantwortlichem und Ablaufdatum.
• Untersuche das Audit-Log, wenn die Herkunft unbekannt ist.

dockup audit --writes --json

So bleibt dockup.yaml maßgeblich, ohne den Kontext des Incidents zu löschen.

Die Dockup CLI-Referenz ist die Quelle für aktuelle Manifestfelder und Optionen von plan und up.

Reviewbare Manifeständerungen entwerfen

Halte jede Änderung so klein, dass der Plan einen eindeutigen Zweck hat. Wenn eine Branch-Änderung, eine Ressourcenerhöhung, eine neue Domain, eine Überarbeitung des Health Checks und eine Bereinigung von Umgebungswerten in einem Pull-Request kombiniert werden, erschwert das sowohl das Review als auch ein Rollback.

Verwende Kommentare, um ungewöhnliche Werte zu erklären, aber dupliziere keine operative Dokumentation in der Datei. Verlinke das Runbook des Repositorys mit dem Service-Ziel, der Bedeutung des Health Checks und der Freigaberichtlinie. Das Manifest sollte gültiges YAML bleiben und ohne einen benutzerdefinierten Preprocessor geparst werden können.

Eine hilfreiche Pull-Request-Vorlage fragt nach der Ausgabe von dockup plan --json, der erwarteten Auswirkung auf das Deployment, der Frage, ob --prune angefordert wird, sowie nach der ID des vorherigen Deployments. Dadurch erhalten ein AI-Agent oder ein menschlicher Reviewer dieselben Nachweise.

Manifest einführen, ohne den Live-Zustand zu beeinträchtigen

Beginne bei einem bestehenden Service mit den Feldern, die du verifizieren kannst. Führe dockup info production/api --json aus, erstelle ein minimales dockup.yaml und vergleiche es mit dockup plan. Füge Einstellungen schrittweise hinzu, statt zu versuchen, alle historischen Dashboard-Entscheidungen auf einmal zu rekonstruieren.

Da Apply additiv ist, bleiben nicht verwaltete normale Werte und Domains während der Einführung erhalten. Sobald das Manifest die gewünschte Konfiguration ohne Secrets korrekt abbildet, sollte das Team entscheiden, ob es jemals Pruning verwenden will. Manche Teams führen die Bereinigung weiterhin manuell durch, andere erlauben --prune nur in einer geschützten Pipeline nach einer Plan-Freigabe.

Das Ziel von Config as Code besteht nicht darin, möglichst viele Zeilen in Git zu sammeln. Es soll die Absicht für die Produktion verständlich, reviewbar und wiederherstellbar machen.

Pläne frei von Secret-Material halten

Ein Plan sollte sicher an einen Pull-Request oder einen Incident-Eintrag angehängt werden können. Da dockup.yaml nur normale Werte enthält und vorhandene Secret-Werte geschützt bleiben, können Reviewer die beabsichtigte Konfiguration prüfen, ohne Zugangsdaten für die Produktion zu erhalten. Prüfe normale Werte trotzdem auf interne Hostnamen, Kundenkennungen oder andere Daten, die nicht öffentlich werden sollten.

Quelle und Ziel gemeinsam angeben

Nenne den vorgesehenen project/service im Pull-Request und im Deployment-Job. Ein gültiges dockup.yaml, das auf das falsche Ziel angewendet wird, ist trotzdem ein operativer Fehler. Zielermittlung und Manifest-Review sind zwei separate, notwendige Prüfungen.

YAML vor dem Plan validieren

Parse das Manifest in CI, bevor du Dockup aufrufst, damit Einrückungs- oder Typfehler direkt an der Quelle der Änderung fehlschlagen. Die Syntaxvalidierung ersetzt dockup plan nicht, verhindert aber vermeidbare Requests mit einer nicht lesbaren Datei.

Eine Quelle bevorzugen

Ein reviewed dockup.yaml sollte die Absicht für die Produktion erklären.

Mit einem verifizierbaren Deployment starten

Füge einem Service ein minimales Manifest hinzu, führe einen schreibgeschützten Plan aus und prüfe jedes gemeldete Feld vor dem ersten Apply.

Kostenlos auf app.dockup.ai starten. Der Free-Plan kostet 0 $ pro Monat, enthält ein Startguthaben von 10 $ und unterstützt einen Workspace, drei Datenbanken und drei Deployments.

FAQ

Was ist dockup.yaml?

Es ist das Config-as-Code-Manifest von Dockup, mit dem sich Service-Branch, Port, Build- und Start-Einstellungen, Health Checks, normale Umgebungswerte und Domains deklarieren lassen.

Ändert dockup plan die Produktion?

Nein. dockup plan ist schreibgeschützt und zeigt die Unterschiede zwischen dem Manifest und dem Live-Service.

Löscht dockup up Konfigurationen, die nicht in der Datei enthalten sind?

Nicht standardmäßig. Apply ist additiv. Unterstützte normale Umgebungswerte und Domains werden nur entfernt, wenn --prune ausdrücklich verwendet wird.

Können Secrets in dockup.yaml gespeichert werden?

Das sollte nicht geschehen. Committe nur normale Werte; setze Secrets über den Secret-Environment-Befehl oder eine Secret-Injection zur Laufzeit. Vorhandene Secrets sind vor Pruning geschützt.

Kann dockup up nach dem Anwenden der Konfiguration ein Deployment auslösen?

Ja. Die dokumentierte Option --deploy wendet das Manifest an und startet ein Deployment. Dessen finales Ergebnis sollte anschließend geprüft werden.