Compose Projects

Opfield descubre aplicaciones Docker Compose externas y puede gestionar Compose Projects de un solo nodo como recursos duraderos. Un proyecto agrupa servicios, configuración, revisiones inmutables, operaciones de ciclo de vida, logs, Routes y vinculaciones de bases de datos bajo una identidad estable.

El descubrimiento de proyectos externos está disponible en todos los planes. Crear o adoptar un proyecto gestionado de un solo nodo requiere Personal o superior. Los builds de Compose basados en Git requieren Business o Enterprise y un Build Worker dedicado en línea.

Decide entre visibilidad y propiedad

El descubrimiento da a los equipos una vista compartida de una aplicación Compose existente sin cambiar quién la opera. La adopción cambia el modelo de propiedad: Opfield pasa a ser el lugar donde se hacen las revisiones de configuración y las acciones de ciclo de vida. Haz esa transferencia de forma explícita con el responsable de la aplicación, porque seguir ejecutando un flujo de trabajo docker compose independiente después de la adopción crea estados deseados que compiten entre sí.

Elige Compose gestionado cuando varios servicios deban revisarse, aplicarse, detenerse, recuperarse y auditarse como una sola aplicación en un nodo Docker. El responsable del proyecto debe definir las dependencias entre servicios, la propiedad de los datos, el origen de los secretos, el tiempo de inactividad aceptable y las condiciones de reversión de los cambios de configuración. Para los proyectos compatibles sin montajes, Business y Enterprise pueden activar Workload Availability (HA) para replicar el proyecto completo o sustituir su ubicación que sirve tras la pérdida de un nodo. Los servicios de cada ubicación se quedan en un nodo; Opfield no reparte un proyecto Compose por un clúster.

Un proyecto correcto tiene un único responsable conocido de la configuración, una revisión activa reproducible, los servicios necesarios en buen estado, volúmenes persistentes conocidos, Routes y vinculaciones privadas que funcionan y ninguna deriva sin explicar.

Proyectos externos y gestionados

Un proyecto externo se descubre a partir de las etiquetas canónicas de Docker Compose de sus contenedores, volúmenes y redes. Opfield muestra el inventario, el estado, el estado de los servicios, la monitorización y los logs agregados, y los usuarios con permiso pueden abrir la consola o el explorador de archivos del contenedor de un servicio. Los proyectos externos son de solo lectura: Opfield no lee el archivo Compose del host y no ofrece ninguna acción de iniciar, detener, reiniciar, revisión, secretos ni eliminar hasta que un operador adopta explícitamente el proyecto. Sigue operando un proyecto externo con su flujo de trabajo docker compose original, o adóptalo. Para el diseño del acceso, consulta Opera cargas de trabajo sin adoptarlas.

Un proyecto gestionado guarda en Opfield su YAML de Compose escrito, sus variables, sus claves de secretos protegidas y sus revisiones inmutables. El daemon de Docker aplica la revisión seleccionada mediante el runtime de Compose fijado de Opfield. El ciclo de vida en un solo nodo está disponible en Personal y superiores. Workload Availability en varios nodos está disponible en Business y Enterprise; el escalado automático por métricas y el escalado de réplicas en un mismo nodo siguen In development.

Los contenedores hijos, los volúmenes con nombre y las redes no externas propiedad del proyecto se controlan a través del Compose Project. Están ocultos o protegidos frente a acciones de ciclo de vida independientes en conflicto: un contenedor de Compose individual no se puede iniciar, detener, reiniciar, editar, recrear ni eliminar por sí solo, tanto si el proyecto es externo como si está gestionado. Las acciones de ciclo de vida se aplican al proyecto completo. Las imágenes y los recursos explícitamente externos o compartidos siguen siendo recursos globales de Docker.

Crea un proyecto gestionado

1. Abre Docker > Compose y selecciona New Project.
2. Elige un nodo Docker en línea con la capacidad de Compose.
3. Introduce una configuración de Compose completa en un único archivo.
4. Proporciona las variables no secretas e identifica por separado las claves de secretos protegidas.
5. Ejecuta la validación y resuelve las opciones no compatibles, las variables que faltan, los conflictos de puertos o las infracciones de políticas.
6. Crea el proyecto y sigue la primera operación de aplicación hasta el final.
7. Verifica cada servicio esperado, el estado, las redes, los volúmenes y el flujo de logs agregado.

Los proyectos manuales son solo de imágenes: el nodo de destino ya debe poder descargar las imágenes. Business y Enterprise pueden asociar un origen Git de la lista de permitidos. Las secciones build acotadas de Compose las resuelven entonces Build Workers aislados, se aplica la política de vulnerabilidades y la revisión inmutable resultante fija los digests de imagen aprobados antes del despliegue.

Adopta un proyecto externo

La adopción es una transferencia explícita de la propiedad. Requiere Personal o superior y tanto docker:compose:create como docker:compose:manage para el proyecto. Abre el proyecto descubierto, elige Adopt into Opfield y pega la configuración completa de la que deba ser responsable Opfield. Opfield no lee el archivo Compose del host, así que el editor empieza vacío. Opfield valida el YAML, lo guarda como la primera revisión inmutable y después lo aplica con Adopt & Apply.

Confirma que el YAML enviado coincide con los servicios, los volúmenes, las redes, las variables y los secretos de la aplicación en ejecución. Opfield nunca se fía de una ruta del host indicada en una etiqueta como entrada de origen. Tras la adopción, los cambios futuros deben pasar por revisiones nuevas y no por modificaciones directas de los contenedores hijos.

Qué conserva y qué cambia la adopción

• Nombre del proyecto. El proyecto adoptado conserva el nombre del que ya informa Docker, y Opfield ejecuta cada operación con ese nombre de proyecto Compose. Opfield no renombra ni añade prefijos al proyecto, a sus servicios ni a sus volúmenes. Un name: de nivel superior en el YAML es opcional, pero si existe debe ser igual al nombre del proyecto.
• Volúmenes con nombre. Como el nombre del proyecto no cambia, Docker Compose resuelve los mismos nombres de volumen que antes (<project>_<volume> por defecto, o el name: explícito de un volumen) y reutiliza los volúmenes existentes y sus datos. Los volúmenes declarados external: true se referencian, no se crean. Antes de la primera aplicación, compara los volúmenes que aparecen en el proyecto descubierto con los volúmenes a los que se resuelve el YAML enviado; una clave de volumen renombrada crea un volumen nuevo y vacío.
• Contenedores. Opfield añade sus propias etiquetas de gestión a cada servicio, así que cuenta con que la primera aplicación recree los contenedores de los servicios. Planifica una breve ventana de mantenimiento.
• Entorno y secretos. No se usan env_file ni un archivo .env del proyecto. Declara las variables en el environment: de cada servicio y haz referencia a los valores con ${NAME}. Opfield proporciona las variables no secretas y los secretos cifrados del proyecto para la interpolación cuando aplica una revisión. En la consola, las pestañas Variables y Secrets están disponibles tras la adopción; usa marcadores ${NAME} para los valores que vayas a añadir allí.
• Bind mounts del host. Los bind mounts se rechazan, incluidas las rutas relativas como ./config:/etc/app, las rutas con ~ y los orígenes construidos con variables. Mueve los archivos de configuración a la imagen o a un volumen con nombre antes de la adopción.
• Trabajos puntuales. Opfield no tiene un equivalente de docker compose run, ni hooks previos al despliegue o de versión. Para un paso de migración, ejecuta el comando en el contenedor de un servicio a través de la consola, lo que requiere docker:containers:console, o modélalo como un servicio con restart: "no" al que esperan otros servicios mediante depends_on. Usa condition: service_completed_successfully cuando otros servicios deban esperar a que termine el trabajo. Un servicio de un solo uso que termina con el código 0 cuenta como completado, así que no marca el proyecto como degraded.

Configuración de Compose compatible

Las revisiones manuales y adoptadas aceptan un documento Compose de un solo archivo de hasta 1 MiB, sin anclas ni alias de YAML. Las claves de nivel superior se limitan a name, version, services, volumes y networks, así que se rechazan include, secrets y configs de nivel superior y las extensiones x-.

Cada servicio debe usar image y solo puede usar estas claves: 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 y logging. Todo lo demás se rechaza, incluidos build, env_file, container_name, privileged, cap_add, devices, network_mode, pid, ipc, security_opt, tmpfs, ulimits, deploy, profiles, extends, secrets y configs a nivel de servicio, y links.

Otras reglas:

• restart debe ser no, always, on-failure o unless-stopped;
• los puertos no pueden usar rangos y deben ser TCP o UDP;
• una entrada de red de un servicio solo puede fijar aliases, y cada red que usa un servicio debe declararse en el nivel superior, salvo la red implícita default;
• cada volumen con nombre que monta un servicio debe declararse en el nivel superior;
• un montaje de volumen con la sintaxis larga solo puede fijar type, source, target y read_only, debe incluir type (si no, VOLUME_TYPE_REQUIRED) y debe usar type: volume con un volumen con nombre como origen;
• depends_on acepta una lista de servicios o un mapeo con la sintaxis larga; en la forma de mapeo, cada entrada solo puede fijar condition, que es obligatoria y debe ser service_started, service_healthy o service_completed_successfully; cada dependencia debe ser un servicio del mismo archivo;
• los volúmenes y las redes de nivel superior solo pueden fijar external, name, driver y labels, así que se rechaza driver_opts;
• logging solo puede fijar driver y options; el controlador debe ser json-file, local o none, y las opciones se limitan a max-size, max-file y compress (none no admite opciones);
• las etiquetas que empiezan por com.docker.compose. o net.opfield., o por los prefijos anteriores a Opfield wiolett.gateway., net.wiolett.gateway. y com.wiolett.gateway., y la etiqueta gateway.sandbox, están reservadas, y se rechaza una clave de etiqueta construida con una variable;
• una red no puede ser la red del host (host o none) ni una de las redes internas de Opfield (opfield-secure-links, opfield-db-*, opfield-storage-*, opfield-link-*, o sus nombres gateway- anteriores a la 2.12.1), y se rechaza un nombre de red construido con una variable;
• las variables y los secretos no pueden usar los nombres que lee el propio cliente de Compose: PATH, DOCKER_HOST, DOCKER_CONTEXT, DOCKER_CONFIG, DOCKER_CERT_PATH, DOCKER_TLS_VERIFY, DOCKER_TLS, DOCKER_API_VERSION, DOCKER_DEFAULT_PLATFORM, DOCKER_BUILDKIT y todos los nombres que empiezan por BUILDKIT_ o COMPOSE_; los demás nombres DOCKER_* siguen siendo variables normales;
• cada referencia ${NAME} necesita una variable o un secreto proporcionados.

Un proyecto guardado antes de que existieran estas reglas de redes, etiquetas y variables sigue funcionando y se puede seguir deteniendo y bajando, pero crear una revisión, aplicar, iniciar y reiniciar se rechazan hasta que su configuración las cumpla. Eso incluye la primera aplicación tras la actualización del daemon de Docker.

En un nodo cuyo controlador de logs predeterminado es json-file, el daemon de Docker da a cada servicio sin logging una rotación json-file de 50 MB × 3, el mismo límite que reciben los contenedores individuales. Para conservar más tiempo los logs de un servicio, fija tus propios max-size y max-file; driver: json-file sin opciones mantiene el valor predeterminado ilimitado de Docker. Docker no puede cambiar los ajustes de logs de un contenedor existente. Por eso, tras la actualización a la 2.11, la primera aplicación recrea una vez cada servicio, incluso con una revisión sin cambios: cada servicio recibe los nuevos ajustes de logs y una etiqueta con el digest de su propia configuración. A partir de entonces, una aplicación solo recrea los servicios cuya configuración ha cambiado. Un nodo cuyo daemon de Docker todavía no se ha actualizado aplica las revisiones sin sus secciones logging y conserva los valores predeterminados de Docker.

Opfield y el daemon de Docker aplican las mismas reglas, de modo que una revisión que supera la validación no se rechaza después al aplicarla. Los proyectos de Business y Enterprise con un origen Git pueden usar además una sección build acotada; consulta Crea un proyecto gestionado. Las mismas reglas se aplican a las revisiones creadas a través de la API, de MCP o de AI Workspace. Reescribir un archivo Compose para que cumpla estas reglas forma parte de la planificación de la adopción, así que hazlo antes en staging.

Revisiones y ciclo de vida

Editar la configuración crea una revisión inmutable nueva. Usa Pull & Apply para descargar las imágenes necesarias y aplicar la revisión activa, Start o Stop para el ciclo de vida del proyecto, y Change revision para volver a aplicar una revisión válida anterior. Las revisiones inactivas se pueden eliminar cuando ninguna operación las usa; la revisión activa no se puede eliminar.

Aplicar una revisión solo recrea los servicios cuya propia definición ha cambiado (imagen, entorno, comando, puertos, volúmenes, redes, límites, etiquetas, logging u otro campo del servicio) o cuyas variables o secretos interpolados han cambiado; los demás servicios siguen funcionando. Una revisión que elimina un servicio espera a que ese servicio se detenga, hasta su periodo de gracia de detención de 10 segundos, antes de que arranquen los servicios modificados. Pull & Apply también recrea un servicio cuyo tag de imagen apunta ahora a una imagen más reciente. Las ubicaciones de un proyecto con Workload Availability siguen llevando el digest de la revisión completa, así que una revisión nueva recrea todos sus servicios. Una aplicación sin descarga solo obtiene las imágenes que faltan en el nodo. Una revisión cuyo puerto TCP publicado ya ocupa en el nodo un Deployment, una réplica de Availability, una base de datos gestionada o un almacenamiento gestionado se rechaza al crearla, con 409 COMPOSE_HOST_PORT_IN_USE; para un proyecto construido desde Git, el build falla con ese mensaje y no se crea ninguna revisión. Un proyecto aparece como degraded cuando uno de sus servicios se detiene fuera de Opfield, y la página de estado lo indica. En un proyecto con Workload Availability, un inicio, una detención o un reinicio solicitados mientras todavía se ejecuta la operación de Availability anterior se ponen en cola y se ejecutan después.

El trabajo de ciclo de vida se representa con operaciones y Tasks duraderos. Recargar la página no cancela una operación. Mientras se despliega un build de Git en el proyecto, las acciones de revisión, ciclo de vida, secretos y eliminación devuelven BUILD_ROLLOUT_IN_PROGRESS hasta que termina el despliegue; cancelar una operación sigue siendo posible. Durante una actualización de Opfield, las nuevas operaciones de Compose se rechazan con OPFIELD_UPDATING. Si la cancelación está disponible, actualiza el proyecto y el estado informado por el daemon antes de iniciar una acción sustituta.

Routes y vinculaciones de bases de datos

Las Routes y los Secure Links pueden apuntar a un servicio de Compose gestionado por la identidad estable del proyecto y del servicio en lugar de por un nombre de contenedor efímero. Las vinculaciones de bases de datos gestionadas actualizan la revisión del proyecto conservando la configuración escrita y los secretos protegidos. Eliminar un servicio o una vinculación debe pasar por una revisión nueva para que Opfield pueda conciliar de forma segura las relaciones dependientes. Aplicar una revisión anterior conserva las vinculaciones actuales; una revisión que no define un servicio vinculado se rechaza hasta que se elimina esa vinculación. A través de la API, de MCP o del asistente, se puede vincular un servicio antes de la primera revisión del proyecto; consulta Cargas de trabajo que no están en ejecución.

Una revisión nueva lleva cada enlace de base de datos completo (su red, sus variables y el alias de host del endpoint privado del enlace), de modo que al aplicarla el servicio arranca con el enlace ya resoluble, en una sola operación. Añadir, eliminar o reparar un enlace en un proyecto en ejecución aplica el proyecto una vez sin descargar sus imágenes y sin recrear sus demás servicios. Un proyecto construido desde un origen Git también puede añadir y quitar enlaces: Opfield aplica una copia de la revisión construida que conserva el archivo Compose del repositorio y su linaje de Git, y un push posterior conserva el enlace y sus secretos. La vista general del proyecto muestra el estado de ejecución de cada enlace: sus conexiones abiertas frente a la capacidad del enlace y las conexiones que rechazó; consulta Capacidad de los enlaces.

Las vinculaciones solo están disponibles para las bases de datos gestionadas. Para llegar a una base de datos externa, pasa sus valores de conexión mediante variables y secretos; consulta Bases de datos gestionadas y externas. Los enlaces de almacenamiento gestionado no están disponibles para los servicios de Compose; da en su lugar a un servicio credenciales S3 de una clave de acceso mediante variables y secretos.

Un servicio de Compose puede llegar a un puerto de otra carga de trabajo, o ser alcanzado por una, mediante un container link: añádelo en el bloque Links de la pestaña Variables del proyecto con Add link → Container y elige el servicio consumidor.

Deriva y solución de problemas

Opfield informa de deriva cuando el estado de ejecución observado ya no coincide con la revisión activa. Comprueba la operación actual, la conectividad del nodo Docker, la capacidad de Compose, el acceso de descarga de imágenes, los logs de los servicios, las variables, los secretos y el diagnóstico del daemon antes de reintentar.

No repares un proyecto gestionado eliminando a mano sus contenedores hijos, sus redes ni los metadatos de sus revisiones. Para un proyecto externo, haz los cambios de configuración mediante su flujo de trabajo de Compose original hasta que termine la adopción.

Elimina un proyecto

Baja un proyecto gestionado y elimina las Routes o vinculaciones dependientes antes de eliminarlo. Eliminar un proyecto al que todavía apunta una Route, una Additional Route o un Additional Secure Link se rechaza con 409 PROXY_UPSTREAM_IN_USE antes de eliminar nada, y un proyecto con enlaces a bases de datos se rechaza con 409 COMPOSE_DATABASE_BINDINGS_EXIST. Eliminar un proyecto gestionado elimina sus contenedores, sus redes no externas, sus revisiones, sus secretos y todos los volúmenes que llevan las etiquetas de Docker Compose del proyecto, lo que incluye los volúmenes con nombre que creó Compose para el proyecto. Los recursos que no pertenecen al proyecto, como los volúmenes creados por separado y declarados external: true, no se eliminan. Haz una copia de seguridad de los datos persistentes antes de eliminar. Los proyectos externos no se pueden eliminar desde Opfield.

Detalles para operadores: recuperación de revisiones

Antes de aplicar una revisión, compara sus servicios, imágenes, variables, secretos, volúmenes, redes y puertos expuestos con la revisión activa. Registra el orden de migración y de arranque específico de la aplicación cuando los servicios no puedan reiniciarse juntos de forma segura. Pull & Apply puede sustituir los entornos de ejecución de los servicios; no garantiza conexiones sin interrupción.

Si una operación se interrumpe, espera a que el nodo Docker se vuelva a conectar y actualiza el estado observado del proyecto antes de iniciar otra aplicación. Usa las operaciones recientes para determinar si falló la descarga de imágenes, la preparación de la configuración, la creación de los servicios, el estado o la confirmación final. Cuando la revisión activa se sabe que funciona y la nueva no es adecuada, selecciona la revisión anterior con Change revision y verifica el camino completo de la aplicación.

La reversión cambia la configuración de Compose y los entornos de ejecución; no deshace las escrituras hechas en sistemas externos ni en volúmenes persistentes. Las migraciones de bases de datos incompatibles con versiones anteriores necesitan su propio plan de recuperación. No elimines contenedores hijos ni redes del proyecto para forzar la convergencia, porque eso elimina pruebas y puede interferir con la limpieza gestionada.