Vinculaciones de bases de datos para aplicaciones

Una vinculación de aplicación da a un Container, un Deployment o un servicio de carga de trabajo compatible acceso privado a una base de datos gestionada. Opfield crea para la vinculación un usuario o un rol del motor distinto con privilegios a nivel de aplicación sobre la base de datos gestionada, nunca la credencial de propietario ni de superusuario. La identidad del motor pertenece a la vinculación, no a un proceso transitorio de la carga de trabajo.

Las vinculaciones solo existen para las bases de datos gestionadas. Para una base de datos que se ejecuta en otro lugar y está registrada como conexión externa, guarda en su lugar sus valores de conexión como secretos de la carga de trabajo o como variables de Compose; consulta Bases de datos gestionadas y externas de un vistazo.

Motor	Identidad de la vinculación
PostgreSQL	Un rol de inicio de sesión que es miembro del rol de aplicación, con el rol de aplicación como predeterminado; sin derechos de superusuario ni de creación de bases de datos o roles
ClickHouse	Un usuario cuyo rol tiene todos los privilegios sobre la base de datos de la aplicación y acceso de lectura a las tablas del sistema que necesita Opfield; sin acceso a otras bases de datos
Almacén clave-valor	Un usuario ACL limitado a los comandos de lectura, escritura, conexión, transacciones, publicación/suscripción y evaluación de scripts; se deniegan los comandos peligrosos y administrativos

Los privilegios no se eligen por vinculación: todas las vinculaciones de una misma base de datos reciben el mismo acceso a nivel de aplicación a través de su propia identidad.

Una vinculación da a una aplicación acceso a la base de datos sin una credencial de propietario y sin publicar la base de datos. La aplicación puede hacer su trabajo en la base de datos de la aplicación y nada administrativo fuera de ella, y conserva la misma identidad cuando se recrea la carga de trabajo.

Crea una vinculación separada para cada carga de trabajo en lugar de reutilizar una, mantén privada la base de datos y elimina la vinculación cuando la carga de trabajo ya no necesite acceso.

Detalles para operadores: modelo de transporte y de propiedad

Desde la 2.11.1, todas las vinculaciones funcionan a través del conector de Secure Links compartido del nodo Docker de destino, el mismo que sirve los enlaces de almacenamiento y los container links. Cada vinculación recibe una pequeña red privada propia, a la que se une la carga de trabajo; el conector responde allí al nombre de host de la vinculación y transporta cada conexión a través del Relay hasta el nodo Storage de la base de datos. No hay un contenedor conector por vinculación ni un listener en el host. Opfield concilia el enlace como parte del estado deseado de la vinculación. Las redes de enlace toman sus direcciones de un rango dedicado, descrito en Conector compartido y redes de enlace.

El enlace y la identidad del motor de la vinculación son registros separados pero coordinados. Cada vinculación tiene su propio principal en la base de datos, de modo que la rotación de credenciales, la eliminación o el cambio de permisos de una carga de trabajo no cambian silenciosamente el acceso de otra. Recrear una carga de trabajo vinculada conserva la relación de la vinculación y su identidad del motor propia; Opfield concilia el enlace y vuelve a inyectar los ajustes de conexión actuales.

Diagnostica primero el estado del enlace de la vinculación y la preparación de la base de datos; las Routes de Ingress no intervienen en el camino de una vinculación.

Crea una vinculación

Antes de crear una vinculación, confirma que la base de datos gestionada está Ready, que el nodo Docker de destino está en línea, que la carga de trabajo es compatible y que tienes acceso a ambos recursos: databases:bind sobre la base de datos (incluido en databases:edit) y, sobre la carga de trabajo, docker:containers:environment y docker:containers:secrets para un Container o un Deployment, o docker:compose:manage para un servicio de Compose. Un cambio de vinculación en un Deployment puede desplegarlo, así que también requiere docker:containers:manage sobre ese Deployment, más docker:containers:edit cuando cambia el entorno del Deployment. Revisa los permisos de base de datos o de rol previstos y asegúrate de que la carga de trabajo puede consumir los ajustes de conexión entregados sin ponerlos en el control de código fuente.

1. Selecciona la base de datos gestionada y la carga de trabajo de destino.
2. Elige qué valores de conexión entregar y el nombre de la variable de entorno de cada uno.
3. Crea la vinculación y espera a que Opfield aprovisione su identidad del motor y concilie el enlace.
4. Aplica o recrea la carga de trabajo solo cuando su cambio de configuración lo requiera.
5. Verifica una consulta real de la aplicación e inspecciona después la telemetría de la vinculación y los logs de la carga de trabajo y de la base de datos.

Usa vinculaciones privadas para el acceso de las cargas de trabajo incluso cuando la publicación TCP directa esté activada para un cliente externo. La publicación es opcional y no sustituye al aislamiento de las vinculaciones.

Las vinculaciones pueden apuntar a un Container independiente, un Deployment o un servicio de Compose compatibles en un nodo Docker en línea, y la base de datos debe estar Ready. Opfield entrega los valores que seleccionas (URI de conexión, host, puerto, base de datos, usuario y contraseña) con los nombres de variables de entorno que elijas; se necesita al menos un valor. La consola sugiere nombres como DATABASE_URL o REDIS_URL, o nombres específicos del motor para los valores individuales. La URI usa el protocolo sin cifrar del motor en la red privada de la vinculación (postgresql://, redis:// o http:// para ClickHouse); las vinculaciones no añaden ajustes de TLS. La URI sencilla también funciona con PostgreSQL con TLS activado: cuando un cliente se conecta sin TLS, el daemon del nodo Storage de la base de datos (2.11 o posterior) abre la conexión TLS con PostgreSQL y verifica el certificado de la instancia. Un cliente que pide TLS por sí mismo, por ejemplo con sslmode=require, mantiene su propia sesión TLS de extremo a extremo. Trata cada valor entregado como un secreto aunque el propio enlace sea privado. No copies la URI en el código de Compose, en capas de imagen, en capturas de pantalla, en logs ni en la configuración de ejecución de Pages.

Una base de datos puede servir a varias cargas de trabajo mediante vinculaciones separadas. Es preferible a reutilizar una cuenta compartida: cada vinculación se puede auditar, rotar y retirar de forma independiente. Opfield rechaza las asignaciones de variables de entorno en conflicto en lugar de sustituir silenciosamente un valor existente de la aplicación; la única excepción es una opción explícita para sustituir los valores existentes en un Container independiente.

Cargas de trabajo que no están en ejecución

No hace falta que la carga de trabajo de destino esté en ejecución. Puedes crear o eliminar una vinculación para un Container, un Deployment o un servicio de Compose detenidos, en un bucle de fallos o fallidos, y para uno que todavía no se ha desplegado. La petición vuelve sin esperar a que la carga de trabajo arranque o esté en buen estado, y un despliegue fallido no deshace la vinculación.

• Una vinculación que está guardada en la configuración de la carga de trabajo pero que esta todavía no usa aparece como pending (observedState: "target_applied" en la API y en MCP). Pasa a estar activa cuando la carga de trabajo vuelve a arrancar o termina su despliegue actual.
• Un Container en un bucle de fallos se recrea con la vinculación y sigue reiniciándose según su política de reinicio.
• Un Deployment cuyo primer build de Git falló recibe la vinculación cuando reintentas el build; no hace falta fijar una imagen.
• Durante el despliegue de un build de Git, las vinculaciones se pueden seguir guardando; llegan a la nueva revisión cuando termina el despliegue.
• A través de la API, de MCP o del asistente, también puedes vincular un Container con origen Git antes de su primer build, por su nombre, y un servicio de Compose antes de la primera revisión del proyecto o mientras el despliegue de un build ocupa el proyecto. El primer build o la siguiente revisión arrancan la carga de trabajo con la vinculación; si esa revisión no define el servicio, la vinculación falla con el motivo. La consola ofrece vinculaciones para estas cargas de trabajo cuando existe el Container o la primera revisión.
• Una reversión de un Deployment, un cambio de slot y la aplicación de una revisión de Compose anterior conservan las vinculaciones actuales. Una revisión que no define un servicio vinculado no se puede aplicar hasta que elimines esa vinculación.
• En un servicio de Compose, cada valor seleccionado se escribe como una referencia a una variable de Compose, por ejemplo DATABASE_URL: ${OPFIELD_DB_<link>_<value>}, y el valor se guarda como un secreto gestionado del proyecto con esa variable. Conserva estas referencias cuando edites el archivo Compose. Las vinculaciones creadas antes de la 2.12.1 conservan sus variables GATEWAY_DB_<link>_<value>; los nombres de variable que lee tu servicio no cambian.
• El nodo Docker de destino debe estar en línea: una vinculación para una carga de trabajo en un nodo desconectado se rechaza con 409 NODE_OFFLINE.

Verifica el aislamiento

Tras la creación o la recreación de la carga de trabajo, verifica todo lo siguiente:

• la vinculación informa de Ready, no de pending, y su carga de trabajo de destino está en ejecución;
• la carga de trabajo recibió los nombres de variables esperados sin exponer sus valores;
• una consulta de la aplicación tiene éxito y una operación administrativa fuera de la base de datos de la aplicación, como crear un rol o una base de datos, falla;
• la telemetría de ejecución de la vinculación muestra el flujo esperado y ningún rechazo de admisión sostenido;
• recrear la carga de trabajo conserva la misma relación de vinculación y no crea un rol del motor adicional;
• una carga de trabajo no relacionada no puede llegar a la red privada de la vinculación ni reutilizar su identidad.

La inspección de contenedores, las vistas del entorno, la exportación de archivos y la duplicación no revelan las contraseñas de los enlaces ni las claves de los enlaces de almacenamiento, y un duplicado no hereda los enlaces del origen. Revelar credenciales es una acción de diagnóstico excepcional. Requiere un acceso explícito y debe ir seguida de los controles normales de tratamiento de secretos; evita revelar credenciales solo para demostrar que una vinculación funciona cuando una consulta de la aplicación y la telemetría aportan pruebas más seguras.

Capacidad de los enlaces y pools de conexiones

Un enlace a una base de datos gestionada transporta tantas conexiones simultáneas como acepte su base de datos: max_connections de PostgreSQL (100 por defecto, que se fija con Maximum connections en Database Settings, entre 20 y 10 000), el ajuste maxclients de un almacén clave-valor o 4096 para ClickHouse. La capacidad pertenece al enlace, no a un contenedor: la comparten todos los contenedores a los que sirve el enlace, y durante un despliegue blue/green la comparten el slot antiguo y el nuevo hasta que el antiguo se detiene. Workload Availability da a cada ubicación su propio enlace. Todos los enlaces de una misma base de datos comparten además el límite de la base de datos.

Un enlace de almacenamiento gestionado no tiene un límite fijo de conexiones: la admisión de Relay lo acota según la carga y reparte la capacidad de forma equitativa entre las rutas. Las conexiones inactivas de los pools de ambos tipos de enlace permanecen abiertas.

Mantén los pools de conexiones de todos los contenedores que hay detrás de un enlace de base de datos, en conjunto, por debajo del límite de la base de datos, y cuenta cada pool del proceso (ORM, cola de trabajos, migraciones y controladores separados) para que un slot nuevo pueda abrir sus pools mientras el slot que sirve todavía mantiene los suyos.

El nodo que ejecuta la carga de trabajo aplica la capacidad de un enlace de base de datos en conjunto: su conector de Secure Links mantiene el enlace en el límite de la base de datos sea cual sea el Relay del pool que transporte cada conexión, y cada Relay limita la ruta del enlace al mismo valor. Una conexión que supera la capacidad se acepta y se cierra de inmediato, de modo que los clientes informan de errores como Connection terminated unexpectedly o ECONNRESET, y el estado de ejecución del enlace la cuenta en throttledTotal. El nodo registra managed link connection rejected con reason=link_limit una vez por minuto y por enlace, con el recuento desde la línea anterior; la línea aparece en los logs del nodo en Opfield, no solo en el journal del host.

Estado de ejecución del enlace

La vista general de un Container, un Deployment o un Compose Project enlazados muestra el estado de ejecución de cada enlace: las conexiones abiertas frente al límite del enlace, el caudal, la latencia de establecimiento de conexiones, el estado de finalización y los rechazos de admisión con el motivo del último rechazo. Los enlaces de almacenamiento de los Containers y Deployments aparecen junto a los enlaces de bases de datos, marcados como S3. El estado de ejecución de un enlace de Availability es la suma de sus ubicaciones.

Interfaz	Enlace de base de datos	Enlace de almacenamiento
REST	GET /api/databases/managed/{id}/bindings/{bindingId}/runtime	GET /api/managed-storage/{id}/bindings/{bindingId}/runtime
MCP y asistente	manage_managed_database get_binding_runtime	manage_managed_storage get_binding_runtime

activeStreams es el número de conexiones abiertas según las cuenta el nodo que ejecuta la carga de trabajo, openedTotal y los contadores de bytes son lo que el enlace transportó a través de ese nodo sean cuales sean los Relays que lo transportaron, throttledTotal cuenta las conexiones rechazadas por capacidad por el nodo o por un Relay, y connections añade el límite, los rechazos del nodo y el motivo y la hora de la última conexión rechazada. Las finalizaciones, los fallos, la latencia de establecimiento y la duración proceden de los Relays. connections es null mientras ese nodo ejecuta un daemon de Docker anterior a la 2.11, y las demás cifras proceden entonces también de los Relays. Unos rechazos de admisión sostenidos significan que los pools de los contenedores que hay detrás del enlace son demasiado grandes.

Conciliación y gestión de fallos

El estado deseado de la vinculación sigue siendo duradero a lo largo de la recreación de la carga de trabajo, el reinicio del daemon de Docker, la reconexión del nodo y el reinicio de Relay. Un enlace conserva sus conexiones mientras la API de Docker va brevemente lenta y cuando Availability toma o devuelve una carga de trabajo, y la conciliación solo se ejecuta para la carga de trabajo a la que afecta un evento. La conciliación restablece el enlace y confirma la identidad del motor sin crear una identidad nueva para cada entorno de ejecución transitorio. Así es como Opfield evita los roles huérfanos tras los caminos normales de reinicio y recreación.

Ante una vinculación fallida, diagnostica en este orden: la preparación de la base de datos gestionada; el nodo Storage de destino; el nodo Docker de destino; el estado deseado de la vinculación; el enlace en el conector de Secure Links del nodo; la identidad del motor y los permisos; y después la configuración de la aplicación. Inspecciona la operación y la telemetría de la vinculación antes de reintentar. No elimines a mano el rol del motor, la red de enlace ni el conector como táctica general de reparación, porque eso puede desincronizar el registro duradero de la base de datos y del daemon.

Elimina y recupera

Elimina la vinculación a través de Opfield cuando la carga de trabajo ya no necesite acceso. Opfield elimina el enlace y retira la identidad del motor de la vinculación como parte de un único ciclo de vida registrado, lo que evita que el camino normal de eliminación deje identidades sin usar. Elimina la vinculación antes de eliminar la base de datos o la carga de trabajo siempre que sea posible, y verifica después que ha terminado la limpieza del enlace, de la telemetría y del principal del motor. Eliminar un Container independiente a través de Opfield también elimina sus enlaces, y lo mismo ocurre al dar su nombre a otro contenedor creándolo, duplicándolo, renombrándolo o importándolo, de modo que un contenedor nuevo con el mismo nombre nunca recibe la red ni las credenciales del enlace anterior.

Si una eliminación se interrumpe, deja en su sitio el registro duradero de la vinculación y usa su estado de operación para la recuperación. Eliminar un rol a mano es un procedimiento de recuperación excepcional, porque puede hacer que falle una conciliación futura; úsalo solo con un plan de recuperación explícito y coordinado.

Detalles para operadores: actualización y compatibilidad

Las vinculaciones pasan al conector compartido cuando el daemon de Docker del nodo de destino se actualiza a la 2.11.1. Opfield recrea una vez cada carga de trabajo vinculada para conectarla a su nueva red de enlace, de una en una en cada nodo, y la siguiente cuando la anterior funciona en buen estado: un Deployment se despliega en blue/green sin tiempo de inactividad, mientras que un Container independiente o un servicio de Compose se reinician una vez. No hay que hacer nada a mano, y los nombres de las variables y las credenciales no cambian. Revertir el daemon de Docker a la 2.11.0 devuelve las vinculaciones automáticamente, de nuevo con una recreación por carga de trabajo y como máximo cuatro a la vez por nodo, el límite del daemon para comandos simultáneos; en un nodo con muchas cargas de trabajo enlazadas, las últimas se vuelven a conectar un poco más tarde. No elimines a mano las redes de enlace ni los contenedores antiguos durante ninguno de los dos traslados.

Cuando se actualiza el conector de Secure Links, el conector anterior entrega sus conexiones abiertas al nuevo, que las mantiene sin reconexión. Un conector anterior a la 2.11.4 no puede entregarlas: las conserva hasta una hora y después las cierra una vez, así que los clientes deben volver a conectarse con reintentos acotados; consulta Conector compartido y redes de enlace. Un reinicio solo de la aplicación Opfield no termina el tráfico establecido de las vinculaciones mientras Relay y los daemons de destino siguen en buen estado. Una actualización de Relay es un evento de mantenimiento del plano de datos y puede interrumpir los flujos. Tras un reinicio del daemon de Docker de destino o del nodo, verifica tanto el estado de la vinculación como una consulta real.