Anwendungs-Bindings für Datenbanken

Ein Anwendungs-Binding gibt einem Container, einem Deployment oder einem geeigneten Workload-Dienst privaten Zugriff auf eine verwaltete Datenbank. Opfield erstellt für das Binding einen eigenen Engine-Benutzer bzw. eine eigene Rolle mit Rechten auf Anwendungsebene in der verwalteten Datenbank, niemals mit den Zugangsdaten des Besitzers oder Superusers. Die Engine-Identität gehört zum Binding, nicht zu einem vorübergehenden Workload-Prozess.

Bindings gibt es nur für verwaltete Datenbanken. Speichern Sie bei einer Datenbank, die anderswo läuft und als externe Verbindung registriert ist, ihre Verbindungswerte stattdessen als Workload-Secrets oder Compose-Variablen; siehe Verwaltete und externe Datenbanken im Überblick.

Engine	Identität des Bindings
PostgreSQL	Eine Login-Rolle, die Mitglied der Anwendungsrolle ist, mit der Anwendungsrolle als Standard; keine Superuser-Rechte und keine Rechte zum Erstellen von Datenbanken oder Rollen
ClickHouse	Ein Benutzer, dessen Rolle alle Rechte an der Anwendungsdatenbank und Lesezugriff auf die Systemtabellen hat, die Opfield benötigt; kein Zugriff auf andere Datenbanken
Key-Value-Store	Ein ACL-Benutzer, beschränkt auf Lese-, Schreib-, Verbindungs-, Transaktions-, Publish/Subscribe- und Skriptauswertungsbefehle; gefährliche und administrative Befehle werden verweigert

Rechte werden nicht pro Binding gewählt: Jedes Binding derselben Datenbank erhält über seine eigene Identität denselben Zugriff auf Anwendungsebene.

Ein Binding gibt einer Anwendung Datenbankzugriff ohne Zugangsdaten des Besitzers und ohne die Datenbank zu veröffentlichen. Die Anwendung kann ihre Arbeit in der Anwendungsdatenbank erledigen und außerhalb davon nichts Administratives tun, und sie behält dieselbe Identität, wenn der Workload neu erstellt wird.

Erstellen Sie für jeden Workload ein eigenes Binding, statt eines wiederzuverwenden, halten Sie die Datenbank privat und löschen Sie das Binding, wenn der Workload keinen Zugriff mehr benötigt.

Details für Betreiber: Transport und Zuständigkeitsmodell

Ab 2.11.1 läuft jedes Binding über den gemeinsamen Secure-Link-Connector des Ziel-Docker-Nodes, denselben, der Speicherverbindungen und Container-Links bedient. Jedes Binding erhält ein kleines eigenes privates Netzwerk, dem der Workload beitritt; der Connector beantwortet dort den Hostnamen des Bindings und leitet jede Verbindung über das Relay zum Storage Node der Datenbank. Es gibt keinen Connector-Container pro Binding und keinen Listener auf dem Host. Opfield gleicht die Verbindung als Teil des Sollzustands des Bindings ab. Verbindungsnetzwerke beziehen ihre Adressen aus einem eigenen Bereich, beschrieben unter Gemeinsamer Connector und Verbindungsnetzwerke.

Die Verbindung und die Engine-Identität des Bindings sind getrennte, aber koordinierte Einträge. Jedes Binding hat einen eigenen Datenbank-Prinzipal, sodass die Rotation von Zugangsdaten, das Löschen oder eine Berechtigungsänderung bei einem Workload nicht stillschweigend den Zugriff eines anderen Workloads ändert. Das Neuerstellen eines gebundenen Workloads bewahrt die Binding-Beziehung und ihre eigene Engine-Identität; Opfield gleicht die Verbindung ab und speist die aktuellen Verbindungseinstellungen erneut ein.

Untersuchen Sie bei Problemen zuerst den Zustand der Verbindung des Bindings und die Bereitschaft der Datenbank; Ingress-Routen sind nicht Teil des Pfads eines Bindings.

Ein Binding erstellen

Bestätigen Sie vor dem Erstellen eines Bindings, dass die verwaltete Datenbank Ready ist, der Ziel-Docker-Node online ist, der Workload geeignet ist und Sie Zugriff auf beide Ressourcen haben: databases:bind auf der Datenbank (in databases:edit enthalten) und auf dem Workload docker:containers:environment und docker:containers:secrets bei einem Container oder Deployment bzw. docker:compose:manage bei einem Compose-Dienst. Eine Binding-Änderung an einem Deployment kann es ausrollen, daher erfordert sie außerdem docker:containers:manage auf diesem Deployment sowie docker:containers:edit, wenn sie die Umgebung des Deployments ändert. Prüfen Sie die vorgesehenen Datenbank- oder Rollenberechtigungen und stellen Sie sicher, dass der Workload die gelieferten Verbindungseinstellungen verwenden kann, ohne sie in die Quellcodeverwaltung zu legen.

1. Wählen Sie die verwaltete Datenbank und den Ziel-Workload.
2. Wählen Sie, welche Verbindungswerte geliefert werden, und für jeden den Namen der Umgebungsvariablen.
3. Erstellen Sie das Binding und warten Sie, bis Opfield seine Engine-Identität bereitgestellt und die Verbindung abgeglichen hat.
4. Wenden Sie den Workload nur an oder erstellen Sie ihn nur neu, wenn seine Konfigurationsänderung es erfordert.
5. Prüfen Sie eine echte Anwendungsabfrage und sehen Sie sich dann die Telemetrie des Bindings sowie die Logs von Workload und Datenbank an.

Verwenden Sie private Bindings für den Workload-Zugriff auch dann, wenn die direkte TCP-Veröffentlichung für einen externen Client aktiviert ist. Die Veröffentlichung ist optional und ersetzt nicht die Isolation durch Bindings.

Bindings können einen geeigneten eigenständigen Container, ein Deployment oder einen Compose-Dienst auf einem Docker Node, der online ist, ansteuern, und die Datenbank muss Ready sein. Opfield liefert die Werte, die Sie auswählen – Verbindungs-URI, Host, Port, Datenbank, Benutzername und Passwort –, unter den Namen der Umgebungsvariablen, die Sie wählen; mindestens ein Wert ist erforderlich. Die Konsole schlägt Namen wie DATABASE_URL oder REDIS_URL vor oder Engine-spezifische Namen für einzelne Werte. Die URI verwendet das einfache Protokoll der Engine im privaten Binding-Netzwerk (postgresql://, redis:// oder http:// bei ClickHouse); Bindings fügen keine TLS-Einstellungen hinzu. Die einfache URI funktioniert auch bei PostgreSQL mit aktiviertem TLS: Verbindet sich ein Client ohne TLS, öffnet der Daemon auf dem Storage Node der Datenbank (ab 2.11) die TLS-Verbindung zu PostgreSQL und prüft das Zertifikat der Instanz. Ein Client, der selbst TLS anfordert, zum Beispiel mit sslmode=require, behält seine eigene durchgängige TLS-Sitzung. Behandeln Sie jeden gelieferten Wert als Secret, auch wenn die Verbindung selbst privat ist. Kopieren Sie die URI nicht in Compose-Quellen, Image-Schichten, Screenshots, Logs oder die Laufzeitkonfiguration von Pages.

Eine Datenbank kann über getrennte Bindings mehrere Workloads bedienen. Das ist der Wiederverwendung eines gemeinsamen Kontos vorzuziehen: Jedes Binding kann unabhängig auditiert, rotiert und außer Betrieb genommen werden. Opfield lehnt widersprüchliche Zuweisungen von Umgebungsvariablen ab, statt einen bestehenden Anwendungswert stillschweigend zu ersetzen; die einzige Ausnahme ist eine ausdrückliche Zustimmung zum Ersetzen bestehender Werte bei einem eigenständigen Container.

Workloads, die nicht laufen

Der Ziel-Workload muss nicht laufen. Sie können ein Binding für einen gestoppten, in einer Absturzschleife hängenden oder fehlgeschlagenen Container, ein solches Deployment oder einen solchen Compose-Dienst erstellen oder löschen, und auch für einen, der noch nicht bereitgestellt wurde. Die Anfrage kehrt zurück, ohne darauf zu warten, dass der Workload startet oder fehlerfrei wird, und ein fehlgeschlagener Rollout macht das Binding nicht rückgängig.

• Ein Binding, das in der Konfiguration des Workloads gespeichert ist, aber noch nicht von ihm verwendet wird, wird als pending angezeigt (observedState: "target_applied" in der API und MCP). Es wird aktiv, wenn der Workload das nächste Mal startet oder seinen aktuellen Rollout abschließt.
• Ein Container in einer Absturzschleife wird mit dem Binding neu erstellt und startet gemäß seiner Neustartrichtlinie weiter neu.
• Ein Deployment, dessen erster Git-Build fehlgeschlagen ist, erhält das Binding, wenn Sie den Build wiederholen; Sie müssen kein Image festlegen.
• Während eines Git-Build-Rollouts können Bindings weiterhin gespeichert werden; sie erreichen die neue Revision, wenn der Rollout abgeschlossen ist.
• Über die API, MCP oder den Assistenten können Sie außerdem einen Container mit Git-Quelle vor seinem ersten Build über seinen Namen binden sowie einen Compose-Dienst vor der ersten Revision des Projekts oder während ein Build-Rollout das Projekt hält. Der erste Build bzw. die nächste Revision startet den Workload mit dem Binding; definiert diese Revision den Dienst nicht, schlägt das Binding mit dem Grund fehl. Die Konsole bietet Bindings für diese Workloads an, sobald der Container oder die erste Revision existiert.
• Ein Rollback eines Deployments, eine Slot-Umschaltung und das Anwenden einer älteren Compose-Revision behalten die aktuellen Bindings bei. Eine Revision, die einen gebundenen Dienst nicht definiert, kann erst angewendet werden, wenn Sie dieses Binding löschen.
• In einem Compose-Dienst wird jeder ausgewählte Wert als Verweis auf eine Compose-Variable geschrieben, zum Beispiel DATABASE_URL: ${OPFIELD_DB_<link>_<value>}, und der Wert wird als verwaltetes Secret des Projekts unter dieser Variablen aufbewahrt. Behalten Sie diese Verweise bei, wenn Sie die Compose-Datei bearbeiten. Vor 2.12.1 erstellte Bindings behalten ihre Variablen GATEWAY_DB_<link>_<value>; die Variablennamen, die Ihr Dienst liest, ändern sich nicht.
• Der Ziel-Docker-Node muss online sein: Ein Binding für einen Workload auf einem Node, der offline ist, wird mit 409 NODE_OFFLINE abgelehnt.

Isolation prüfen

Prüfen Sie nach dem Erstellen oder nach einer Neuerstellung des Workloads alle folgenden Punkte:

• das Binding meldet Ready, nicht pending, und sein Ziel-Workload läuft;
• der Workload hat die erwarteten Variablennamen erhalten, ohne ihre Werte offenzulegen;
• eine Anwendungsabfrage gelingt, und eine administrative Operation außerhalb der Anwendungsdatenbank, etwa das Erstellen einer Rolle oder Datenbank, schlägt fehl;
• die Laufzeittelemetrie des Bindings zeigt den erwarteten Datenstrom und keine anhaltenden Zulassungsablehnungen;
• das Neuerstellen des Workloads bewahrt dieselbe Binding-Beziehung und erzeugt keine zusätzliche Engine-Rolle;
• ein unbeteiligter Workload kann das private Netzwerk des Bindings nicht erreichen und die Binding-Identität nicht wiederverwenden.

Container-Inspect, Umgebungsansichten, Archivexport und Duplizieren legen weder Passwörter von Verbindungen noch Schlüssel von Speicherverbindungen offen, und ein Duplikat erbt die Verbindungen der Quelle nicht. Das Anzeigen von Zugangsdaten ist eine außergewöhnliche Diagnoseaktion. Es erfordert ausdrücklichen Zugriff und sollte von den normalen Kontrollen für den Umgang mit Secrets gefolgt werden; zeigen Sie Zugangsdaten nicht nur an, um nachzuweisen, dass ein Binding funktioniert, wenn eine Anwendungsabfrage und die Telemetrie sicherere Belege liefern.

Verbindungskapazität und Verbindungspools

Eine Verbindung zu einer verwalteten Datenbank transportiert so viele gleichzeitige Verbindungen, wie ihre Datenbank annimmt: PostgreSQL max_connections (standardmäßig 100, festgelegt mit Maximum connections unter Database Settings, 20–10.000), die Einstellung maxclients eines Key-Value-Stores oder 4096 bei ClickHouse. Die Kapazität gehört zur Verbindung, nicht zu einem Container: Jeder Container, den die Verbindung bedient, teilt sie, und während eines Blue/Green-Rollouts teilen sich der alte und der neue Slot sie, bis der alte Slot stoppt. Workload Availability gibt jeder Platzierung ihre eigene Verbindung. Alle Verbindungen einer Datenbank teilen sich außerdem das Limit der Datenbank.

Eine Verbindung zu verwaltetem Speicher hat kein festes Verbindungslimit: Die Relay-Zulassung begrenzt sie nach Last und verteilt die Kapazität fair zwischen den Routen. Ungenutzte gepoolte Verbindungen beider Arten von Verbindungen bleiben offen.

Halten Sie die Verbindungspools aller Container hinter einer Datenbankverbindung zusammen unter dem Limit der Datenbank und zählen Sie jeden Pool im Prozess mit – ORM, Job-Warteschlange, Migrationen und separate Treiber –, damit ein neuer Slot seine Pools öffnen kann, während der bedienende Slot seine eigenen noch hält.

Der Node, der den Workload ausführt, setzt die Kapazität einer Datenbankverbindung als Ganzes durch: Sein Secure-Link-Connector hält die Verbindung auf dem Limit der Datenbank, unabhängig davon, welches Relay des Pools die einzelne Verbindung transportiert, und jedes Relay begrenzt die Route der Verbindung auf denselben Wert. Eine Verbindung über der Kapazität wird angenommen und sofort geschlossen, sodass Clients Fehler wie Connection terminated unexpectedly oder ECONNRESET melden, und die Laufzeit der Verbindung zählt sie in throttledTotal. Der Node protokolliert managed link connection rejected mit reason=link_limit einmal pro Minute und Verbindung, mit der Anzahl seit der vorherigen Zeile; die Zeile erscheint in den Logs des Nodes in Opfield, nicht nur im Journal des Hosts.

Laufzeit der Verbindung

Die Übersicht eines verbundenen Containers, Deployments oder Compose-Projekts zeigt die Laufzeit jeder Verbindung: offene Verbindungen im Verhältnis zum Limit der Verbindung, Durchsatz, Latenz beim Verbindungsaufbau, Zustand beim Abschluss und Zulassungsablehnungen mit dem Grund der letzten Ablehnung. Speicherverbindungen von Containern und Deployments erscheinen neben Datenbankverbindungen, gekennzeichnet mit S3. Die Laufzeit einer Availability-Verbindung ist die Summe ihrer Platzierungen.

Schnittstelle	Datenbankverbindung	Speicherverbindung
REST	GET /api/databases/managed/{id}/bindings/{bindingId}/runtime	GET /api/managed-storage/{id}/bindings/{bindingId}/runtime
MCP und Assistent	manage_managed_database get_binding_runtime	manage_managed_storage get_binding_runtime

activeStreams ist die Anzahl offener Verbindungen, wie der Node zählt, der den Workload ausführt, openedTotal und die Byte-Zähler geben an, was die Verbindung über diesen Node transportiert hat, unabhängig davon, welche Relays sie transportiert haben, throttledTotal zählt Verbindungen, die vom Node oder einem Relay an der Kapazitätsgrenze abgelehnt wurden, und connections ergänzt das Limit, die Ablehnungen des Nodes sowie Grund und Zeitpunkt der zuletzt abgelehnten Verbindung. Abschlüsse, Fehler, Aufbaulatenz und Dauer stammen von den Relays. connections ist null, solange dieser Node einen Docker-Daemon älter als 2.11 ausführt, und die übrigen Werte stammen dann ebenfalls von den Relays. Anhaltende Zulassungsablehnungen bedeuten, dass die Pools der Container hinter der Verbindung zu groß sind.

Abgleich und Fehlerbehandlung

Der Sollzustand eines Bindings bleibt über Neuerstellungen des Workloads, Neustarts des Docker-Daemons, erneute Verbindungen des Nodes und Neustarts von Relay hinweg dauerhaft erhalten. Eine Verbindung behält ihre Verbindungen, während die API von Docker kurzzeitig langsam ist und wenn Availability einen Workload übernimmt oder zurückgibt, und der Abgleich läuft nur für den Workload, den ein Ereignis betrifft. Der Abgleich stellt die Verbindung wieder her und bestätigt die Engine-Identität, ohne für jede vorübergehende Laufzeit eine neue Identität zu erzeugen. So vermeidet Opfield verwaiste Rollen nach normalen Neustarts und Neuerstellungen.

Diagnostizieren Sie ein fehlgeschlagenes Binding in dieser Reihenfolge: Bereitschaft der verwalteten Datenbank; Ziel-Storage-Node; Ziel-Docker-Node; Sollzustand des Bindings; die Verbindung auf dem Secure-Link-Connector des Nodes; Engine-Identität und Berechtigungen; dann die Konfiguration der Anwendung. Prüfen Sie die Binding-Operation und die Telemetrie, bevor Sie es erneut versuchen. Löschen Sie die Engine-Rolle, das Verbindungsnetzwerk oder den Connector nicht manuell als allgemeine Reparaturtaktik, weil das den dauerhaften Eintrag von Datenbank und Daemon entkoppeln kann.

Löschen und wiederherstellen

Löschen Sie das Binding über Opfield, wenn der Workload keinen Zugriff mehr benötigt. Opfield entfernt die Verbindung und setzt die Engine-Identität des Bindings als Teil eines einzigen erfassten Lebenszyklus außer Kraft, sodass der normale Löschweg keine ungenutzten Identitäten zurücklässt. Löschen Sie das Binding nach Möglichkeit vor der Datenbank oder dem Workload und prüfen Sie dann, dass die Bereinigung von Verbindung, Telemetrie und Engine-Prinzipal abgeschlossen ist. Das Löschen eines eigenständigen Containers über Opfield löscht auch seine Verbindungen, ebenso wie die Vergabe seines Namens an einen anderen Container durch Erstellen, Duplizieren, Umbenennen oder Importieren, sodass ein neuer Container mit demselben Namen nie das Netzwerk oder die Zugangsdaten der alten Verbindung erhält.

Wird ein Löschvorgang unterbrochen, lassen Sie den dauerhaften Binding-Eintrag bestehen und verwenden Sie seinen Operationszustand für die Wiederherstellung. Das manuelle Löschen einer Rolle ist ein außergewöhnliches Wiederherstellungsverfahren, weil es einen künftigen Abgleich fehlschlagen lassen kann; verwenden Sie es nur mit einem ausdrücklichen, abgestimmten Wiederherstellungsplan.

Details für Betreiber: Upgrade und Kompatibilität

Bindings wechseln zum gemeinsamen Connector, wenn der Docker-Daemon des Ziel-Nodes auf 2.11.1 aktualisiert wird. Opfield erstellt jeden gebundenen Workload einmal neu, um ihn an sein neues Verbindungsnetzwerk anzubinden, einen Workload nach dem anderen auf jedem Node, den nächsten, sobald der vorherige fehlerfrei läuft: Ein Deployment wird ohne Ausfallzeit per Blue/Green ausgerollt, während ein eigenständiger Container oder ein Compose-Dienst einmal neu startet. Manuell ist nichts zu tun, und Variablennamen und Zugangsdaten bleiben gleich. Ein Rollback des Docker-Daemons auf 2.11.0 verschiebt die Bindings automatisch zurück, wieder mit einer Neuerstellung pro Workload und höchstens vier gleichzeitig pro Node, dem Limit des Daemons für gleichzeitige Befehle; auf einem Node mit vielen verbundenen Workloads verbinden sich die späteren etwas später neu. Löschen Sie während keines dieser Wechsel alte Verbindungsnetzwerke oder Container manuell.

Wird der Secure-Link-Connector aktualisiert, übergibt der vorherige Connector seine offenen Verbindungen an den neuen, der sie ohne erneuten Verbindungsaufbau weiterführt. Ein Connector von vor 2.11.4 kann sie nicht übergeben: Er behält sie bis zu einer Stunde und schließt sie dann einmal, daher sollten sich Clients mit begrenzten Wiederholungen neu verbinden; siehe Gemeinsamer Connector und Verbindungsnetzwerke. Ein Neustart nur der Opfield-Anwendung beendet bestehenden Binding-Verkehr nicht, solange das Relay und die Ziel-Daemons fehlerfrei bleiben. Ein Relay-Update ist ein Wartungsereignis der Datenebene und kann Datenströme unterbrechen. Prüfen Sie nach einem Neustart des Ziel-Docker-Daemons oder des Nodes sowohl den Zustand des Bindings als auch eine echte Abfrage.