Compose-Projekte

Opfield erkennt externe Docker-Compose-Anwendungen und kann Compose-Projekte auf einem Node als dauerhafte Ressourcen verwalten. Ein Projekt fasst Dienste, Konfiguration, unveränderliche Revisionen, Lebenszyklusoperationen, Logs, Routen und Datenbank-Bindings unter einer stabilen Identität zusammen.

Die externe Erkennung ist in jedem Tarif verfügbar. Das Erstellen oder Übernehmen eines verwalteten Projekts auf einem Node erfordert Personal oder höher. Compose-Builds aus Git erfordern Business oder Enterprise und einen dedizierten Build Worker, der online ist.

Zwischen Sichtbarkeit und Zuständigkeit entscheiden

Die Erkennung gibt Teams eine gemeinsame Sicht auf eine bestehende Compose-Anwendung, ohne zu ändern, wer sie betreibt. Die Übernahme ändert das Zuständigkeitsmodell: Opfield wird zu dem Ort, an dem Konfigurationsrevisionen und Lebenszyklusaktionen ausgeführt werden. Machen Sie diese Übertragung mit dem Anwendungsverantwortlichen ausdrücklich, denn wer nach der Übernahme weiterhin einen unabhängigen docker compose-Ablauf betreibt, erzeugt konkurrierende Sollzustände.

Wählen Sie verwaltetes Compose, wenn mehrere Dienste als eine Anwendung auf einem Docker Node geprüft, angewendet, gestoppt, wiederhergestellt und auditiert werden müssen. Der Projektverantwortliche sollte Dienstabhängigkeiten, Zuständigkeit für Daten, Quellen der Secrets, akzeptable Ausfallzeiten und die Rollback-Bedingungen für Konfigurationsänderungen festlegen. Für geeignete Projekte ohne Mounts können Business und Enterprise Workload Availability (HA) aktivieren, um das gesamte Projekt zu replizieren oder seine bedienende Platzierung nach einem Node-Ausfall zu ersetzen. Die Dienste jeder Platzierung bleiben auf einem Node; Opfield teilt ein Compose-Projekt nicht über einen Cluster auf.

Ein erfolgreiches Projekt hat einen verstandenen Konfigurationsverantwortlichen, eine reproduzierbare aktive Revision, fehlerfreie benötigte Dienste, bekannte persistente Volumes, funktionierende Routen und private Bindings und keine ungeklärten Abweichungen.

Externe und verwaltete Projekte

Ein externes Projekt wird anhand kanonischer Docker-Compose-Labels an seinen Containern, Volumes und Netzwerken erkannt. Opfield zeigt Inventar, Status, Zustand der Dienste, Monitoring und zusammengefasste Logs, und berechtigte Benutzer können die Konsole oder den Dateibrowser eines Dienstcontainers öffnen. Externe Projekte sind schreibgeschützt: Opfield liest die Compose-Datei des Hosts nicht und bietet keine Aktion zum Starten, Stoppen, Neustarten, für Revisionen, Secrets oder Löschen an, bis ein Operator das Projekt ausdrücklich übernimmt. Betreiben Sie ein externes Projekt weiter mit seinem ursprünglichen docker compose-Ablauf oder übernehmen Sie es. Zur Gestaltung des Zugriffs siehe Workloads betreiben, ohne sie zu übernehmen.

Ein verwaltetes Projekt speichert sein verfasstes Compose-YAML, Variablen, geschützte Secret-Schlüssel und unveränderliche Revisionen in Opfield. Der Docker-Daemon wendet die ausgewählte Revision über die festgelegte Compose-Laufzeit von Opfield an. Der Lebenszyklus auf einem Node ist ab Personal verfügbar. Workload Availability über mehrere Nodes ist in Business und Enterprise verfügbar; metrikbasiertes Autoscaling und das Skalieren von Replikaten auf demselben Node bleiben In development.

Untergeordnete Container, benannte Volumes und nicht externe Netzwerke eines Projekts werden über das Compose-Projekt gesteuert. Sie sind vor konkurrierenden eigenständigen Lebenszyklusaktionen ausgeblendet oder geschützt: Ein einzelner Compose-Container kann nicht eigenständig gestartet, gestoppt, neu gestartet, bearbeitet, neu erstellt oder gelöscht werden, unabhängig davon, ob das Projekt extern oder verwaltet ist. Lebenszyklusaktionen gelten für das gesamte Projekt. Images und ausdrücklich externe oder gemeinsam genutzte Ressourcen bleiben globale Docker-Ressourcen.

Ein verwaltetes Projekt erstellen

1. Öffnen Sie Docker > Compose und wählen Sie New Project.
2. Wählen Sie einen Docker Node mit der Compose-Fähigkeit, der online ist.
3. Geben Sie eine vollständige Compose-Konfiguration in einer Datei ein.
4. Geben Sie nicht geheime Variablen an und kennzeichnen Sie geschützte Secret-Schlüssel separat.
5. Führen Sie die Validierung aus und lösen Sie nicht unterstützte Optionen, fehlende Variablen, Portkonflikte oder Richtlinienverstöße auf.
6. Erstellen Sie das Projekt und verfolgen Sie die erste Anwendungsoperation bis zum Abschluss.
7. Prüfen Sie jeden erwarteten Dienst, Health-Zustand, jedes Netzwerk, jedes Volume und jeden zusammengefassten Log-Stream.

Manuelle Projekte arbeiten nur mit Images: Die Images müssen vom Ziel-Node bereits bezogen werden können. Business und Enterprise können eine Git-Quelle von der Allowlist anhängen. Begrenzte Compose-build-Abschnitte werden dann von isolierten Build Workern aufgelöst, die Schwachstellenrichtlinie wird angewendet, und die resultierende unveränderliche Revision legt vor dem Deployment freigegebene Image-Digests fest.

Ein externes Projekt übernehmen

Die Übernahme ist eine ausdrückliche Übertragung der Zuständigkeit. Sie erfordert Personal oder höher sowie docker:compose:create und docker:compose:manage für das Projekt. Öffnen Sie das erkannte Projekt, wählen Sie Adopt into Opfield und fügen Sie die vollständige Konfiguration ein, für die Opfield zuständig sein soll. Opfield liest die Compose-Datei nicht vom Host, daher beginnt der Editor leer. Opfield validiert das YAML, speichert es als erste unveränderliche Revision und wendet es dann mit Adopt & Apply an.

Bestätigen Sie, dass das übermittelte YAML zu den Diensten, Volumes, Netzwerken, Variablen und Secrets der laufenden Anwendung passt. Opfield vertraut niemals einem per Label übergebenen Host-Pfad als Quelleingabe. Nach der Übernahme müssen künftige Änderungen über neue Revisionen erfolgen statt über direkte Änderungen an untergeordneten Containern.

Was die Übernahme beibehält und was sie ändert

• Projektname. Das übernommene Projekt behält den Namen, den Docker bereits meldet, und Opfield führt jede Operation mit diesem Compose-Projektnamen aus. Opfield benennt weder das Projekt noch seine Dienste oder Volumes um und versieht sie mit keinem Präfix. Ein name: auf oberster Ebene im YAML ist optional, muss aber, falls vorhanden, dem Projektnamen entsprechen.
• Benannte Volumes. Da der Projektname unverändert bleibt, löst Docker Compose dieselben Volume-Namen wie zuvor auf – standardmäßig <project>_<volume> oder den ausdrücklichen name: eines Volumes – und verwendet die bestehenden Volumes samt ihren Daten weiter. Mit external: true deklarierte Volumes werden referenziert, nicht erstellt. Vergleichen Sie vor dem ersten Anwenden die im erkannten Projekt aufgeführten Volumes mit den Volumes, auf die das übermittelte YAML aufgelöst wird; ein umbenannter Volume-Schlüssel erstellt ein neues, leeres Volume.
• Container. Opfield fügt jedem Dienst seine eigenen Verwaltungs-Labels hinzu, rechnen Sie also damit, dass das erste Anwenden die Dienstcontainer neu erstellt. Planen Sie ein kurzes Wartungsfenster ein.
• Umgebung und Secrets. env_file und eine .env-Datei des Projekts werden nicht verwendet. Deklarieren Sie Variablen im environment: jedes Dienstes und referenzieren Sie Werte mit ${NAME}. Opfield liefert beim Anwenden einer Revision nicht geheime Variablen und verschlüsselte Projekt-Secrets für die Interpolation. In der Konsole werden die Registerkarten Variables und Secrets nach der Übernahme verfügbar; verwenden Sie ${NAME}-Platzhalter für Werte, die Sie dort hinzufügen werden.
• Host-Bind-Mounts. Bind-Mounts werden abgelehnt, einschließlich relativer Pfade wie ./config:/etc/app, ~-Pfaden und aus Variablen gebildeter Quellen. Verlagern Sie Konfigurationsdateien vor der Übernahme in das Image oder ein benanntes Volume.
• Einmalige Jobs. Opfield hat keine Entsprechung zu docker compose run und keinen Pre-Deploy- oder Release-Hook. Führen Sie für einen Migrationsschritt den Befehl entweder über die Konsole in einem Dienstcontainer aus, was docker:containers:console erfordert, oder bilden Sie ihn als Dienst mit restart: "no" ab, auf den andere Dienste über depends_on warten. Verwenden Sie condition: service_completed_successfully, wenn andere Dienste warten müssen, bis der Job abgeschlossen ist. Ein einmaliger Dienst, der mit Code 0 endet, gilt als abgeschlossen und markiert das Projekt daher nicht als degraded.

Unterstützte Compose-Konfiguration

Manuelle und übernommene Revisionen akzeptieren ein Compose-Dokument in einer Datei bis 1 MiB, ohne YAML-Anker oder -Aliase. Schlüssel auf oberster Ebene sind auf name, version, services, volumes und networks beschränkt, daher werden include, secrets und configs auf oberster Ebene sowie x--Erweiterungen abgelehnt.

Jeder Dienst muss image verwenden und darf nur diese Schlüssel verwenden: image, command, entrypoint, working_dir, user, hostname, environment, labels, ports, volumes, networks, depends_on, healthcheck, restart, extra_hosts, cpus, cpu_shares, mem_limit, mem_reservation, memswap_limit, pids_limit und logging. Alles andere wird abgelehnt, einschließlich build, env_file, container_name, privileged, cap_add, devices, network_mode, pid, ipc, security_opt, tmpfs, ulimits, deploy, profiles, extends, secrets und configs auf Dienstebene sowie links.

Weitere Regeln:

• restart muss no, always, on-failure oder unless-stopped sein;
• Ports dürfen keine Bereiche verwenden und müssen TCP oder UDP sein;
• ein Netzwerkeintrag eines Dienstes kann nur aliases setzen, und jedes Netzwerk, das ein Dienst verwendet, muss auf oberster Ebene deklariert sein, außer dem impliziten Netzwerk default;
• jedes benannte Volume, das ein Dienst einbindet, muss auf oberster Ebene deklariert sein;
• ein Volume-Mount in Langform kann nur type, source, target und read_only setzen, muss type enthalten (andernfalls VOLUME_TYPE_REQUIRED) und muss type: volume mit einem benannten Volume als Quelle verwenden;
• depends_on akzeptiert eine Liste von Diensten oder eine Zuordnung in Langform; in der Zuordnungsform kann jeder Eintrag nur condition setzen, das erforderlich ist und service_started, service_healthy oder service_completed_successfully sein muss; jede Abhängigkeit muss ein Dienst in derselben Datei sein;
• Volumes und Netzwerke auf oberster Ebene können nur external, name, driver und labels setzen, daher wird driver_opts abgelehnt;
• logging kann nur driver und options setzen; der Treiber muss json-file, local oder none sein, und die Optionen sind auf max-size, max-file und compress beschränkt (none akzeptiert keine Optionen);
• Labels, die mit com.docker.compose. oder net.opfield. beginnen oder mit den Präfixen aus der Zeit vor Opfield wiolett.gateway., net.wiolett.gateway. und com.wiolett.gateway., sowie das Label gateway.sandbox sind reserviert, und ein aus einer Variablen gebildeter Label-Schlüssel wird abgelehnt;
• ein Netzwerk darf weder das Host-Netzwerk (host oder none) noch eines der internen Netzwerke von Opfield sein (opfield-secure-links, opfield-db-*, opfield-storage-*, opfield-link-* oder deren gateway--Namen von vor 2.12.1), und ein aus einer Variablen gebildeter Netzwerkname wird abgelehnt;
• Variablen und Secrets dürfen nicht die Namen verwenden, die der Compose-Client selbst liest: PATH, DOCKER_HOST, DOCKER_CONTEXT, DOCKER_CONFIG, DOCKER_CERT_PATH, DOCKER_TLS_VERIFY, DOCKER_TLS, DOCKER_API_VERSION, DOCKER_DEFAULT_PLATFORM, DOCKER_BUILDKIT sowie jeden Namen, der mit BUILDKIT_ oder COMPOSE_ beginnt; andere DOCKER_*-Namen bleiben gewöhnliche Variablen;
• jede ${NAME}-Referenz benötigt eine bereitgestellte Variable oder ein bereitgestelltes Secret.

Ein Projekt, das gespeichert wurde, bevor es diese Netzwerk-, Label- und Variablenregeln gab, läuft weiter und kann weiterhin gestoppt und heruntergefahren werden, aber das Erstellen einer Revision, das Anwenden, Starten und Neustarten werden abgelehnt, bis seine Konfiguration ihnen folgt. Das umfasst das erste Anwenden nach dem Update des Docker-Daemons.

Auf einem Node, dessen Standard-Log-Treiber json-file ist, gibt der Docker-Daemon jedem Dienst ohne logging eine json-file-Rotation von 50 MB × 3, dasselbe Limit, das einzelne Container erhalten. Um die Logs eines Dienstes länger aufzubewahren, setzen Sie eigene Werte für max-size und max-file; driver: json-file ohne Optionen behält den unbegrenzten Standard von Docker bei. Docker kann die Log-Einstellungen eines bestehenden Containers nicht ändern. Nach dem Update auf 2.11 erstellt das erste Anwenden daher jeden Dienst einmal neu, selbst bei einer unveränderten Revision: Jeder Dienst erhält die neuen Log-Einstellungen und ein Label mit dem Digest seiner eigenen Konfiguration. Ab dann erstellt ein Anwenden nur die Dienste neu, deren Konfiguration sich geändert hat. Ein Node, dessen Docker-Daemon noch nicht aktualisiert wurde, wendet Revisionen ohne ihre logging-Abschnitte an und behält die Standards von Docker.

Opfield und der Docker-Daemon wenden dieselben Regeln an, sodass eine Revision, die die Validierung besteht, später beim Anwenden nicht abgelehnt wird. Business- und Enterprise-Projekte mit einer Git-Quelle können zusätzlich einen begrenzten build-Abschnitt verwenden; siehe Ein verwaltetes Projekt erstellen. Dieselben Regeln gelten für Revisionen, die über die API, MCP oder AI Workspace erstellt werden. Eine Compose-Datei so umzuschreiben, dass sie diesen Regeln entspricht, ist Teil der Übernahmeplanung, erledigen Sie das also zuerst im Staging.

Revisionen und Lebenszyklus

Das Bearbeiten der Konfiguration erstellt eine neue unveränderliche Revision. Verwenden Sie Pull & Apply, um benötigte Images zu beziehen und die aktive Revision anzuwenden, Start oder Stop für den Projektlebenszyklus und Change revision, um eine frühere gültige Revision erneut anzuwenden. Inaktive Revisionen können entfernt werden, wenn keine Operation sie verwendet; die aktive Revision kann nicht gelöscht werden.

Das Anwenden einer Revision erstellt nur die Dienste neu, deren eigene Definition sich geändert hat – Image, Umgebung, Befehl, Ports, Volumes, Netzwerke, Limits, Labels, Logging oder ein anderes Dienstfeld – oder deren interpolierte Variablen oder Secrets sich geändert haben; die anderen Dienste laufen weiter. Eine Revision, die einen Dienst entfernt, wartet, bis dieser Dienst gestoppt ist, bis zu seiner Stopp-Kulanzzeit von 10 Sekunden, bevor die geänderten Dienste starten. Pull & Apply erstellt außerdem einen Dienst neu, dessen Image-Tag jetzt auf ein neueres Image zeigt. Platzierungen eines Projekts unter Workload Availability tragen weiterhin den Digest der gesamten Revision, daher erstellt eine neue Revision alle ihre Dienste neu. Ein Anwenden ohne Pull bezieht nur die Images, die auf dem Node fehlen. Eine Revision, deren veröffentlichter TCP-Port auf dem Node bereits von einem Deployment, einem Availability-Replikat, einer verwalteten Datenbank oder verwaltetem Speicher belegt ist, wird beim Erstellen mit 409 COMPOSE_HOST_PORT_IN_USE abgelehnt; bei einem aus Git gebauten Projekt schlägt der Build mit dieser Meldung fehl, und es wird keine Revision erstellt. Ein Projekt zeigt degraded, wenn einer seiner Dienste außerhalb von Opfield stoppt, und die Statusseite meldet es. Bei einem Projekt mit Workload Availability wird ein Start, Stopp oder Neustart, der angefordert wird, während die vorherige Availability-Operation noch läuft, eingereiht und danach ausgeführt.

Lebenszyklusarbeit wird durch dauerhafte Operationen und Tasks dargestellt. Ein Neuladen der Seite bricht eine Operation nicht ab. Während ein Git-Build auf das Projekt ausgerollt wird, liefern Revisions-, Lebenszyklus-, Secret- und Löschaktionen BUILD_ROLLOUT_IN_PROGRESS, bis der Rollout endet; das Abbrechen einer Operation bleibt möglich. Während eines Opfield-Updates werden neue Compose-Operationen mit OPFIELD_UPDATING abgelehnt. Ist ein Abbruch verfügbar, aktualisieren Sie den Zustand des Projekts und den vom Daemon gemeldeten Zustand, bevor Sie eine Ersatzaktion starten.

Routen und Datenbank-Bindings

Routen und Secure Links können einen verwalteten Compose-Dienst über die stabile Projekt- und Dienstidentität ansteuern statt über einen flüchtigen Containernamen. Bindings verwalteter Datenbanken aktualisieren die Revision des Projekts und bewahren dabei die verfasste Konfiguration und die geschützten Secrets. Das Entfernen eines Dienstes oder Bindings muss über eine neue Revision erfolgen, damit Opfield abhängige Beziehungen sicher abgleichen kann. Das Anwenden einer älteren Revision behält die aktuellen Bindings bei; eine Revision, die einen gebundenen Dienst nicht definiert, wird abgelehnt, bis dieses Binding gelöscht ist. Über die API, MCP oder den Assistenten kann ein Dienst vor der ersten Revision des Projekts gebunden werden; siehe Workloads, die nicht laufen.

Eine neue Revision trägt jede Datenbankverbindung vollständig – ihr Netzwerk, ihre Variablen und den Host-Alias des privaten Endpunkts der Verbindung –, sodass ihr Anwenden den Dienst in einer Operation mit bereits auflösbarer Verbindung startet. Das Hinzufügen, Entfernen oder Reparieren einer Verbindung bei einem laufenden Projekt wendet das Projekt einmal an, ohne seine Images zu beziehen und ohne seine anderen Dienste neu zu erstellen. Auch ein aus einer Git-Quelle gebautes Projekt kann Verbindungen aufnehmen und abgeben: Opfield wendet eine Kopie der gebauten Revision an, die die Compose-Datei des Repositorys und ihre Git-Herkunft beibehält, und ein späterer Push behält die Verbindung und ihre Secrets bei. Die Projektübersicht zeigt die Laufzeit jeder Verbindung: ihre offenen Verbindungen im Verhältnis zur Kapazität der Verbindung und die abgelehnten Verbindungen; siehe Verbindungskapazität.

Bindings sind nur für verwaltete Datenbanken verfügbar. Um eine externe Datenbank zu erreichen, übergeben Sie ihre Verbindungswerte über Variablen und Secrets; siehe Verwaltete und externe Datenbanken. Verbindungen zu verwaltetem Speicher sind für Compose-Dienste nicht verfügbar; geben Sie einem Dienst stattdessen S3-Zugangsdaten aus einem Zugriffsschlüssel über Variablen und Secrets.

Ein Compose-Dienst kann über einen Container-Link einen Port eines anderen Workloads erreichen oder von einem erreicht werden: Fügen Sie ihn im Block Links der Registerkarte Variables des Projekts mit Add link → Container hinzu und wählen Sie den nutzenden Dienst.

Abweichungen und Fehlerbehebung

Opfield meldet eine Abweichung, wenn der beobachtete Laufzeitzustand nicht mehr zur aktiven Revision passt. Prüfen Sie die aktuelle Operation, die Konnektivität des Docker Nodes, die Compose-Fähigkeit, den Zugriff zum Beziehen von Images, Dienstlogs, Variablen, Secrets und Daemon-Diagnosen, bevor Sie es erneut versuchen.

Reparieren Sie ein verwaltetes Projekt nicht, indem Sie seine untergeordneten Container, Netzwerke oder Revisionsmetadaten manuell löschen. Nehmen Sie bei einem externen Projekt Konfigurationsänderungen über seinen ursprünglichen Compose-Ablauf vor, bis die Übernahme abgeschlossen ist.

Ein Projekt löschen

Fahren Sie ein verwaltetes Projekt herunter und entfernen Sie abhängige Routen oder Bindings vor dem Löschen. Das Löschen eines Projekts, auf das eine Route, eine Additional Route oder ein Additional Secure Link noch zielt, wird mit 409 PROXY_UPSTREAM_IN_USE abgelehnt, bevor etwas entfernt wird, und ein Projekt mit Datenbankverbindungen wird mit 409 COMPOSE_DATABASE_BINDINGS_EXIST abgelehnt. Das Löschen eines verwalteten Projekts entfernt seine Container, nicht externen Netzwerke, Revisionen, Secrets und jedes Volume, das die Docker-Compose-Labels des Projekts trägt, einschließlich der benannten Volumes, die Compose für das Projekt erstellt hat. Ressourcen, die nicht zum Projekt gehören, etwa separat erstellte und als external: true deklarierte Volumes, werden nicht gelöscht. Sichern Sie persistente Daten vor dem Löschen. Externe Projekte können nicht aus Opfield gelöscht werden.

Details für Betreiber: Wiederherstellung von Revisionen

Vergleichen Sie vor dem Anwenden einer Revision ihre Dienste, Images, Variablen, Secrets, Volumes, Netzwerke und freigegebenen Ports mit der aktiven Revision. Halten Sie anwendungsspezifische Migrationen und die Startreihenfolge fest, wenn Dienste nicht sicher gemeinsam neu starten können. Pull & Apply kann Dienstlaufzeiten ersetzen; es garantiert keine unterbrechungsfreien Verbindungen.

Wird eine Operation unterbrochen, warten Sie, bis sich der Docker Node neu verbindet, und aktualisieren Sie den beobachteten Projektzustand, bevor Sie ein weiteres Anwenden starten. Verwenden Sie die jüngsten Operationen, um festzustellen, ob das Beziehen von Images, die Vorbereitung der Konfiguration, das Erstellen von Diensten, der Health-Zustand oder die abschließende Bestätigung fehlgeschlagen ist. Ist die aktive Revision bekannt fehlerfrei und die neue Revision ungeeignet, wählen Sie die frühere Revision über Change revision und prüfen Sie den vollständigen Anwendungspfad.

Ein Rollback ändert die Compose-Konfiguration und die Laufzeiten; es macht keine Schreibvorgänge in externe Systeme oder persistente Volumes rückgängig. Nicht abwärtskompatible Datenbankmigrationen benötigen einen eigenen Wiederherstellungsplan. Löschen Sie keine untergeordneten Container oder Projektnetzwerke, um eine Konvergenz zu erzwingen, denn das entfernt Belege und kann die verwaltete Bereinigung beeinträchtigen.