Liaisons applicatives aux bases de données

Une liaison applicative donne à un Container, un Deployment ou un service de charge de travail éligible un accès privé à une base de données managée. Opfield crée pour la liaison un utilisateur ou un rôle distinct dans le moteur, avec des privilèges de niveau applicatif sur la base managée, jamais l’identifiant du propriétaire ou du superutilisateur. L’identité dans le moteur appartient à la liaison, et non à un processus transitoire de la charge de travail.

Les liaisons n’existent que pour les bases de données managées. Pour une base qui s’exécute ailleurs et est enregistrée comme connexion externe, stockez plutôt ses valeurs de connexion sous forme de secrets de la charge de travail ou de variables Compose ; voir Bases de données managées et externes en un coup d’œil.

Moteur	Identité de la liaison
PostgreSQL	Un rôle de connexion membre du rôle applicatif, avec le rôle applicatif comme rôle par défaut ; aucun droit de superutilisateur, de création de base ou de création de rôle
ClickHouse	Un utilisateur dont le rôle dispose de tous les privilèges sur la base applicative et d’un accès en lecture aux tables système dont Opfield a besoin ; aucun accès aux autres bases
Stockage clé-valeur	Un utilisateur ACL limité aux commandes de lecture, d’écriture, de connexion, de transaction, de publication/abonnement et d’évaluation de scripts ; les commandes dangereuses et d’administration sont refusées

Les privilèges ne se choisissent pas par liaison : chaque liaison sur une même base reçoit le même accès de niveau applicatif via sa propre identité.

Une liaison donne à une application l’accès à une base de données sans identifiant de propriétaire et sans publier la base. L’application peut effectuer son travail dans la base applicative et rien d’administratif en dehors, et elle conserve la même identité lorsque la charge de travail est recréée.

Créez une liaison distincte pour chaque charge de travail au lieu d’en réutiliser une, gardez la base privée, et supprimez la liaison lorsque la charge de travail n’a plus besoin d’accès.

Détails pour l’opérateur : modèle de transport et de propriété

À partir de 2.11.1, chaque liaison passe par le connecteur secure-link partagé du nœud Docker cible, celui-là même qui sert les liens de stockage et les liens entre conteneurs. Chaque liaison dispose de son propre petit réseau privé, que rejoint la charge de travail ; le connecteur y répond au nom d’hôte de la liaison et transporte chaque connexion via Relay jusqu’au nœud Storage de la base. Il n’existe ni conteneur connecteur par liaison ni écouteur sur l’hôte. Opfield réconcilie le lien dans le cadre de l’état souhaité de la liaison. Les réseaux de liens prennent leurs adresses dans une plage dédiée, décrite dans Connecteur partagé et réseaux de liens.

Le lien et l’identité de la liaison dans le moteur sont des enregistrements distincts mais coordonnés. Chaque liaison a son propre principal de base de données ; la rotation des identifiants, la suppression ou la modification des permissions concernant une charge de travail ne modifie donc pas silencieusement l’accès d’une autre. La recréation d’une charge de travail liée préserve la relation de liaison et son identité distincte dans le moteur ; Opfield réconcilie le lien et injecte à nouveau les paramètres de connexion actuels.

Diagnostiquez d’abord l’état du lien de la liaison et la disponibilité de la base ; les routes d’ingress ne font pas partie du chemin d’une liaison.

Créer une liaison

Avant de créer une liaison, vérifiez que la base managée est Ready, que le nœud Docker cible est en ligne, que la charge de travail est éligible et que vous avez accès aux deux ressources : databases:bind sur la base (inclus dans databases:edit) et, sur la charge de travail, docker:containers:environment et docker:containers:secrets pour un Container ou un Deployment, ou docker:compose:manage pour un service Compose. Une modification de liaison sur un Deployment peut le redéployer ; elle nécessite donc aussi docker:containers:manage sur ce Deployment, plus docker:containers:edit lorsqu’elle modifie l’environnement du Deployment. Examinez les permissions prévues sur la base ou le rôle et assurez-vous que la charge de travail peut consommer les paramètres de connexion fournis sans les placer dans la gestion de sources.

1. Sélectionnez la base managée et la charge de travail cible.
2. Choisissez les valeurs de connexion à fournir et le nom de variable d’environnement de chacune.
3. Créez la liaison et attendez qu’Opfield provisionne son identité dans le moteur et réconcilie le lien.
4. N’appliquez ou ne recréez la charge de travail que si son changement de configuration l’exige.
5. Vérifiez une vraie requête applicative, puis examinez la télémétrie de la liaison et les journaux de la charge de travail et de la base.

Utilisez des liaisons privées pour l’accès des charges de travail même lorsque la publication TCP directe est activée pour un client externe. La publication est facultative et ne remplace pas l’isolation des liaisons.

Les liaisons peuvent cibler un Container autonome, un Deployment ou un service Compose éligible sur un nœud Docker en ligne, et la base doit être Ready. Opfield fournit les valeurs que vous sélectionnez — URI de connexion, hôte, port, base, nom d’utilisateur et mot de passe — sous les noms de variables d’environnement que vous choisissez ; au moins une valeur est requise. La Console suggère des noms comme DATABASE_URL ou REDIS_URL, ou des noms propres au moteur pour les valeurs individuelles. L’URI utilise le protocole simple du moteur sur le réseau privé de la liaison (postgresql://, redis:// ou http:// pour ClickHouse) ; les liaisons n’ajoutent pas de paramètres TLS. L’URI simple fonctionne aussi pour PostgreSQL avec TLS activé : lorsqu’un client se connecte sans TLS, le démon du nœud Storage de la base (2.11 ou ultérieur) ouvre la connexion TLS vers PostgreSQL et vérifie le certificat de l’instance. Un client qui demande lui-même TLS, par exemple avec sslmode=require, conserve sa propre session TLS de bout en bout. Traitez chaque valeur fournie comme un secret, même si le lien lui-même est privé. Ne copiez pas l’URI dans la source Compose, les couches d’image, des captures d’écran, des journaux ou la configuration d’exécution de Pages.

Une base peut servir plusieurs charges de travail via des liaisons distinctes. C’est préférable à la réutilisation d’un compte partagé : chaque liaison peut être auditée, faire l’objet d’une rotation et être retirée indépendamment. Opfield refuse les affectations de variables d’environnement conflictuelles plutôt que de remplacer silencieusement une valeur applicative existante ; la seule exception est une option explicite de remplacement des valeurs existantes sur un Container autonome.

Charges de travail qui ne s’exécutent pas

La charge de travail cible n’a pas besoin de s’exécuter. Vous pouvez créer ou supprimer une liaison pour un Container, un Deployment ou un service Compose arrêté, qui redémarre en boucle ou en échec, ainsi que pour un élément qui n’a pas encore été déployé. La requête revient sans attendre que la charge de travail démarre ou devienne saine, et un déploiement en échec n’annule pas la liaison.

• Une liaison enregistrée dans la configuration de la charge de travail mais pas encore utilisée par celle-ci apparaît comme pending (observedState: "target_applied" dans l’API et MCP). Elle devient active au prochain démarrage de la charge de travail ou à la fin de son déploiement en cours.
• Un Container qui redémarre en boucle est recréé avec la liaison et continue de redémarrer selon sa politique de redémarrage.
• Un Deployment dont le premier build Git a échoué reçoit la liaison lorsque vous relancez le build ; vous n’avez pas besoin de définir une image.
• Pendant le déploiement d’un build Git, les liaisons peuvent toujours être enregistrées ; elles atteignent la nouvelle révision à la fin du déploiement.
• Via l’API, MCP ou l’assistant, vous pouvez aussi lier un Container à source Git avant son premier build, par son nom, ainsi qu’un service Compose avant la première révision du projet ou pendant qu’un déploiement de build retient le projet. Le premier build ou la révision suivante démarre la charge de travail avec la liaison ; si cette révision ne définit pas le service, la liaison échoue avec la raison. La Console propose les liaisons pour ces charges de travail une fois que le Container ou la première révision existe.
• Un retour arrière de Deployment, une bascule de slot et l’application d’une révision Compose plus ancienne conservent les liaisons actuelles. Une révision qui ne définit pas un service lié ne peut pas être appliquée tant que vous n’avez pas supprimé cette liaison.
• Dans un service Compose, chaque valeur sélectionnée est écrite comme une référence à une variable Compose, par exemple DATABASE_URL: ${OPFIELD_DB_<link>_<value>}, et la valeur est conservée comme secret géré du projet sous cette variable. Conservez ces références lorsque vous modifiez le fichier Compose. Les liaisons créées avant 2.12.1 conservent leurs variables GATEWAY_DB_<link>_<value> ; les noms de variables que lit votre service ne changent pas.
• Le nœud Docker cible doit être en ligne : une liaison pour une charge de travail sur un nœud hors ligne est refusée avec 409 NODE_OFFLINE.

Vérifier l’isolation

Après la création ou la recréation de la charge de travail, vérifiez tous les points suivants :

• la liaison signale Ready, et non pending, et sa charge de travail cible s’exécute ;
• la charge de travail a reçu les noms de variables attendus sans exposer leurs valeurs ;
• une requête applicative réussit et une opération d’administration hors de la base applicative, comme la création d’un rôle ou d’une base, échoue ;
• la télémétrie d’exécution de la liaison montre le flux attendu et aucun refus d’admission persistant ;
• la recréation de la charge de travail préserve la même relation de liaison et ne crée pas de rôle supplémentaire dans le moteur ;
• une charge de travail sans rapport ne peut ni joindre le réseau privé de la liaison ni réutiliser son identité.

L’inspection du Container, les vues de l’environnement, l’export d’archive et la duplication ne révèlent pas les mots de passe des liens ni les clés des liens de stockage, et une copie n’hérite pas des liens de la source. L’affichage des identifiants est une action de diagnostic exceptionnelle. Il nécessite un accès explicite et doit être suivi des contrôles normaux de gestion des secrets ; évitez d’afficher des identifiants simplement pour prouver qu’une liaison fonctionne, alors qu’une requête applicative et la télémétrie fournissent des éléments plus sûrs.

Capacité des liens et pools de connexions

Un lien vers une base de données managée transporte autant de connexions simultanées que sa base en accepte : max_connections de PostgreSQL (100 par défaut, défini avec Maximum connections dans Database Settings, de 20 à 10 000), le paramètre maxclients d’un stockage clé-valeur, ou 4096 pour ClickHouse. La capacité appartient au lien, et non à un conteneur : chaque conteneur que sert le lien la partage, et pendant un déploiement blue/green l’ancien et le nouveau slot la partagent jusqu’à l’arrêt de l’ancien slot. Workload Availability donne à chaque placement son propre lien. Tous les liens d’une même base partagent aussi la limite de la base.

Un lien de stockage managé n’a pas de limite de connexions fixe : l’admission Relay le borne selon la charge et partage équitablement la capacité entre les routes. Les connexions inactives des pools restent ouvertes pour les deux types de liens.

Gardez ensemble les pools de connexions de tous les conteneurs derrière un lien de base de données sous la limite de la base, et comptez chaque pool du processus — ORM, file de tâches, migrations et pilotes distincts — afin qu’un nouveau slot puisse ouvrir ses pools pendant que le slot actif conserve encore les siens.

Le nœud qui exécute la charge de travail applique la capacité d’un lien de base de données dans son ensemble : son connecteur secure-link maintient le lien à la limite de la base quel que soit le relais du pool qui transporte chaque connexion, et chaque relais plafonne la route du lien à la même valeur. Une connexion au-delà de la capacité est acceptée puis fermée immédiatement ; les clients signalent donc des erreurs comme Connection terminated unexpectedly ou ECONNRESET, et l’exécution du lien la comptabilise dans throttledTotal. Le nœud consigne managed link connection rejected avec reason=link_limit une fois par minute et par lien, avec le décompte depuis la ligne précédente ; la ligne apparaît dans les journaux du nœud dans Opfield, et pas seulement dans le journal de l’hôte.

Exécution des liens

La vue d’ensemble d’un Container, d’un Deployment ou d’un projet Compose lié affiche l’exécution de chaque lien : connexions ouvertes par rapport à la limite du lien, débit, latence d’établissement des connexions, bonne terminaison et refus d’admission avec la raison du dernier refus. Les liens de stockage des Containers et des Deployments apparaissent à côté des liens de bases de données, signalés S3. L’exécution d’un lien Availability est la somme de ses placements.

Interface	Lien de base de données	Lien de stockage
REST	GET /api/databases/managed/{id}/bindings/{bindingId}/runtime	GET /api/managed-storage/{id}/bindings/{bindingId}/runtime
MCP et assistant	manage_managed_database get_binding_runtime	manage_managed_storage get_binding_runtime

activeStreams est le nombre de connexions ouvertes tel que le compte le nœud qui exécute la charge de travail, openedTotal et les compteurs d’octets représentent ce que le lien a transporté via ce nœud quels que soient les relais utilisés, throttledTotal compte les connexions refusées à la limite de capacité par le nœud ou un relais, et connections ajoute la limite, les refus du nœud ainsi que la raison et l’heure de la dernière connexion refusée. Les terminaisons, les échecs, la latence d’établissement et la durée proviennent des relais. connections vaut null tant que ce nœud exécute un démon Docker antérieur à 2.11, et les autres valeurs proviennent alors aussi des relais. Des refus d’admission persistants signifient que les pools des conteneurs derrière le lien sont trop grands.

Réconciliation et gestion des échecs

L’état souhaité de la liaison reste durable au travers des recréations de la charge de travail, des redémarrages du démon Docker, des reconnexions de nœuds et des redémarrages de Relay. Un lien conserve ses connexions lorsque l’API de Docker est brièvement lente et lorsqu’Availability reprend ou rend une charge de travail, et la réconciliation ne s’exécute que pour la charge de travail concernée par un événement. La réconciliation rétablit le lien et confirme l’identité dans le moteur sans créer une nouvelle identité pour chaque exécution transitoire. C’est ainsi qu’Opfield évite les rôles orphelins après les redémarrages et recréations normaux.

Pour une liaison en échec, diagnostiquez dans cet ordre : disponibilité de la base managée ; nœud Storage cible ; nœud Docker cible ; état souhaité de la liaison ; le lien sur le connecteur secure-link du nœud ; identité et permissions dans le moteur ; puis configuration de l’application. Examinez l’opération de la liaison et sa télémétrie avant de réessayer. Ne supprimez pas manuellement le rôle du moteur, le réseau du lien ou le connecteur comme tactique de réparation générale, car cela peut désynchroniser l’enregistrement durable de la base et du démon.

Supprimer et rétablir

Supprimez la liaison via Opfield lorsque la charge de travail n’a plus besoin d’accès. Opfield retire le lien et met hors service l’identité de la liaison dans le moteur au sein d’un seul cycle de vie enregistré, ce qui empêche le chemin de suppression normal de laisser des identités inutilisées. Supprimez la liaison avant de supprimer la base ou la charge de travail chaque fois que possible, puis vérifiez que le nettoyage du lien, de la télémétrie et du principal dans le moteur est terminé. Supprimer un Container autonome via Opfield supprime aussi ses liens, tout comme le fait de donner son nom à un autre conteneur en en créant, dupliquant, renommant ou important un ; un nouveau conteneur portant le même nom ne reçoit donc jamais le réseau ni les identifiants de l’ancien lien.

Si une suppression est interrompue, laissez en place l’enregistrement durable de la liaison et utilisez son état d’opération pour la reprise. La suppression manuelle d’un rôle est une procédure de reprise exceptionnelle, car elle peut faire échouer une réconciliation future ; ne l’utilisez qu’avec un plan de reprise explicite et coordonné.

Détails pour l’opérateur : mise à niveau et compatibilité

Les liaisons passent sur le connecteur partagé lorsque le démon Docker du nœud cible est mis à jour vers 2.11.1. Opfield recrée une fois chaque charge de travail liée pour la rattacher à son nouveau réseau de lien, une charge de travail à la fois sur chaque nœud, la suivante une fois que la précédente s’exécute sainement : un Deployment se déploie en blue/green sans interruption, tandis qu’un Container autonome ou un service Compose redémarre une fois. Rien n’est à faire à la main, et les noms de variables et les identifiants restent les mêmes. Revenir au démon Docker 2.11.0 rebascule automatiquement les liaisons, là encore avec une recréation par charge de travail et au plus quatre simultanément par nœud, limite du démon pour les commandes concurrentes ; sur un nœud comportant de nombreuses charges de travail liées, les dernières se reconnectent un peu plus tard. Ne supprimez pas à la main les anciens réseaux ou conteneurs de liens pendant l’une ou l’autre bascule.

Lorsque le connecteur secure-link est mis à jour, l’ancien connecteur transmet ses connexions ouvertes au nouveau, qui les poursuit sans reconnexion. Un connecteur antérieur à 2.11.4 ne peut pas les transmettre : il les conserve jusqu’à une heure puis les ferme une fois ; les clients doivent donc se reconnecter avec des relances bornées ; voir Connecteur partagé et réseaux de liens. Un redémarrage de la seule application Opfield n’interrompt pas le trafic établi d’une liaison tant que Relay et les démons cibles restent sains. Une mise à jour de Relay est un événement de maintenance du plan de données et peut interrompre les flux. Après un redémarrage du démon Docker cible ou du nœud, vérifiez à la fois l’état de la liaison et une vraie requête.