Contenedores

Un Container es la opción de gestión directa para un entorno de ejecución Docker. Opfield guarda su configuración y sus relaciones de acceso, mientras que el daemon de Docker seleccionado arranca y supervisa el proceso real. Usa un Container cuando no se necesiten slots de versión blue/green ni la propiedad de un proyecto de varios servicios. Los contenedores que ya se ejecutan en un nodo Docker aparecen en la lista y se pueden operar sin que Opfield los recree; consulta Contenedores que Opfield no creó.

Cuándo un Container es el propietario adecuado

Elige un Container para un único servicio cuyo reinicio, actualización y recuperación se puedan gestionar como un solo entorno de ejecución. Funciona bien para herramientas internas, agentes, servicios sin estado y cargas de trabajo con una relación sencilla con un volumen persistente. El responsable de la aplicación sigue siendo quien decide si sustituir el proceso es seguro y si sus datos requieren una copia de seguridad o una ventana de mantenimiento.

Elige en su lugar un Deployment cuando una versión deba prepararse y comprobarse su estado antes de mover el tráfico, con un candidato de reversión conservado. Elige Compose cuando varios servicios, redes, variables y volúmenes deban cambiar bajo una misma revisión. Un Container es deliberadamente directo; Opfield no se inventa una estrategia de versiones de la aplicación a su alrededor.

El éxito significa algo más que un estado running. La comprobación de estado esperada debe superarse, la aplicación debe escuchar en el puerto seleccionado, su Route o su conexión privada deben funcionar y los datos persistentes deben seguir conectados tras una recreación. Define esas comprobaciones antes de la primera actualización en producción.

Contenedores que Opfield no creó

El daemon de Docker informa de todos los contenedores de su nodo, no solo de los creados a través de Opfield. Un contenedor iniciado con docker run o con otra herramienta, sin etiquetas de proyecto de Docker Compose, aparece en Docker > Containers como un Container independiente normal con una identidad de recurso de Opfield estable. No hay un paso de adopción separado: los usuarios con los ámbitos correspondientes pueden ver sus logs, sus estadísticas y sus procesos, iniciarlo, detenerlo, reiniciarlo o matarlo, abrir la consola o el explorador de archivos, y editarlo o recrearlo.

Opfield no concede automáticamente acceso a nadie a un contenedor descubierto. Los usuarios con ámbitos de Docker globales o para todo el nodo lo ven de inmediato; los demás usuarios necesitan una concesión de grupo o directa para ese contenedor, su nodo o una carpeta de Docker que lo contenga. Consulta Opera cargas de trabajo sin adoptarlas para ver ejemplos de concesiones.

Otros dos tipos de contenedores se tratan de forma distinta:

• Contenedores de Compose. Un contenedor con la etiqueta com.docker.compose.project pertenece a su Compose Project y no aparece como un Container independiente. Los logs, la monitorización, la consola y el acceso a los archivos siguen disponibles para sus servicios. Iniciar, detener, reiniciar, editar, recrear, duplicar y eliminar se rechazan para los contenedores de Compose individuales, tanto si el proyecto es externo como si lo gestiona Opfield.
• Contenedores internos de Opfield. Los contenedores de servicio que Opfield ejecuta para sí mismo están ocultos a las API de ciclo de vida de los usuarios.

Las concesiones limitadas por recurso siguen la identidad del recurso de Opfield. Opfield conserva esa identidad, y las concesiones sobre ella, a lo largo de una recreación o una actualización realizadas a través de Opfield. Si un contenedor se elimina y se vuelve a iniciar fuera de Opfield, aunque sea con el mismo nombre, Opfield registra un recurso nuevo y revoca las concesiones sobre el anterior. Cambia los contenedores que tienen concesiones limitadas por recurso a través de Opfield, o concede el acceso a nivel de nodo o de carpeta.

Antes de empezar

Necesitas acceso al nodo Docker de destino y permiso para crear o cambiar el Container. Confirma que la imagen está disponible en un registro permitido, que el nodo tiene capacidad y que el entorno de ejecución solicitado es compatible. Revisa los puertos, las Routes, las vinculaciones de bases de datos, los volúmenes gestionados y los secretos antes de elegir un nombre: esas relaciones pueden afectar a futuros cambios de nombre, migraciones o eliminaciones. Un Container se puede vincular a una base de datos gestionada; a una base de datos externa se llega mediante valores de conexión guardados como secretos del Container. Consulta Bases de datos gestionadas y externas de un vistazo.

Los nuevos bind mounts del host se rechazan. Usa volúmenes locales gestionados por Opfield para los datos persistentes nuevos. Los bind mounts heredados pueden mantenerse durante una actualización normal, pero, una vez eliminados, no se pueden volver a añadir a través de Opfield.

Una carga de trabajo con bind mounts del host heredados los conserva en los cambios que no cambian su imagen, como las ediciones del entorno, los enlaces a bases de datos o almacenamiento y los cambios de slot de un despliegue; estos no requieren docker:containers:mounts. Una imagen nueva recibe el mismo acceso al host, así que cambiarla requiere ese ámbito: a la persona que inicia el cambio y, para los despliegues automáticos desde Git y los webhooks, a la cuenta que guardó por última vez el origen o el webhook, comprobado en el momento del despliegue. Los webhooks guardados antes de la 2.11 no tienen ninguna cuenta registrada y se rechazan en esas cargas de trabajo hasta que alguien que tenga el ámbito los vuelva a guardar.

El entorno de ejecución Default está disponible en los nodos Docker compatibles. El entorno de ejecución seguro gVisor requiere una capacidad informada en buen estado y no se puede combinar con GPU, dispositivos, bind mounts del host, migración ni exportación de archivos.

Crea y actualiza un Container

1. Selecciona el nodo Docker y la imagen, preferiblemente un digest inmutable para una carga de trabajo de producción.
2. Define el comando, el entrypoint, el entorno, los secretos cifrados, las etiquetas, los puertos, la política de reinicio, los límites de recursos, las comprobaciones de estado y los volúmenes gestionados.
3. Revisa la configuración resuelta y crea el Container.
4. Sigue el Task de creación hasta que el daemon informe del estado de ejecución.
5. Comprueba el estado, los logs y cualquier Route o conexión privada a una base de datos antes de enviar tráfico de la aplicación.

Algunos espacios de nombres de etiquetas están reservados, porque Opfield y Docker Compose los usan para colocar, agrupar u ocultar contenedores: cualquier etiqueta que empiece 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. Crear un Container con una de ellas se rechaza en la consola, en la REST API y en MCP con Labels <names> are reserved for Opfield and Docker Compose. Recrear o actualizar un Container vuelve a enviar sus etiquetas completas: las etiquetas reservadas que ya tenga pueden volver sin cambios, pero añadir o cambiar una falla con 400 RESERVED_DOCKER_LABEL. Duplicate deja fuera de la copia las etiquetas reservadas y conserva solo los registros propios del daemon de Docker sobre la configuración copiada, como la procedencia de un grupo de GPU. Los daemons de Docker más antiguos copian todas las etiquetas, así que en un nodo cuyo daemon no se ha actualizado, duplicar un contenedor que lleva etiquetas reservadas se rechaza con 409 UNSUPPORTED_DAEMON hasta que se actualiza el daemon. Importar un archivo de contenedor descarta las etiquetas de Compose y las etiquetas de archivo, Deployment y migración de Opfield en lugar de rechazar el archivo.

En un nodo Docker cuyo controlador de logs predeterminado es json-file, Opfield limita los logs de cada contenedor que crea o recrea sin una configuración de logging propia a tres archivos de 50 MB. Los Compose Projects reciben el mismo límite para cada servicio sin una sección logging propia; consulta Configuración de Compose compatible. Los demás controladores de logs no cambian, y un nodo cuyo /etc/docker/daemon.json define log-opts predeterminados los conserva. Cuando el script de configuración del nodo Docker instala Docker por sí mismo, escribe ese archivo con la misma rotación de 50 MB × 3, de modo que los contenedores creados fuera de Opfield también quedan limitados.

Para encontrar los contenedores cuyos logs todavía crecen sin límite, crea una alerta de Container sobre Log Size (MB). Cuenta el archivo de log del contenedor y sus copias rotadas en el nodo; un daemon de Docker que todavía no se ha actualizado informa de cero.

Usa Recreate cuando un cambio de configuración de ejecución requiera un proceso sustituto. Opfield conserva la identidad estable del recurso mientras vuelve a crear el entorno de ejecución previsto. Usa Duplicate cuando necesites un recurso separado con concesiones de acceso e historial de ciclo de vida independientes. Usa Rename solo después de revisar las Routes, las vinculaciones y las integraciones dependientes. Un nombre reservado por un origen Git cuyo contenedor todavía espera su primer build no se puede tomar creando, duplicando, renombrando ni importando otro contenedor: la petición falla con 409 NAME_IN_USE. Eliminar un contenedor elimina también su origen Git, y renombrarlo mueve el origen al nuevo nombre.

Duplicate copia los secretos propios del contenedor, pero no sus enlaces a bases de datos ni a almacenamiento: las variables que inyectan esos enlaces quedan fuera de la copia. La inspección, la pestaña Environment y la exportación de archivos nunca revelan las contraseñas de los enlaces ni las claves de los enlaces de almacenamiento. Actualizar la imagen de un contenedor requiere docker:containers:environment y docker:containers:secrets, porque el nuevo entorno de ejecución recibe el entorno y los secretos del contenedor, y conectar un contenedor a redes requiere acceso de edición a esas redes.

Verifica y opera

La vista de detalle es el registro operativo: confirma el estado deseado y el observado, el resultado de la comprobación de estado, la identidad de la imagen, los Tasks recientes y los logs. La pestaña Overview indica el perfil de ejecución del contenedor, por ejemplo Secure · gVisor, y la monitorización muestra sus límites de memoria y de PID junto al uso. Stop en un contenedor que no ejecuta nada (creado, terminado o muerto) termina de inmediato. Usa el acceso a la consola o a los archivos solo para los ámbitos que tengas concedidos, y evita usar una consola interactiva como camino normal de despliegue.

Tras un reinicio o una reconexión del daemon, Opfield concilia el estado deseado guardado. Si el Container está en ejecución pero no puede servir tráfico, comprueba en este orden su comprobación de estado, el puerto en el que escucha, el destino de la Route, el entorno y el log de la aplicación.

La pestaña Environment

La pestaña Environment contiene tres bloques, de arriba abajo:

• Links: las conexiones privadas del Container. Add link pregunta a qué se conecta la carga de trabajo: una base de datos gestionada (sus credenciales se convierten en variables, consulta las vinculaciones), un almacenamiento gestionado (credenciales privadas de almacenamiento de objetos para los buckets elegidos, definidas como variables) o un puerto de otro contenedor, deployment o servicio de Compose (un container link). Los enlaces que otras cargas de trabajo abren hacia esta aparecen como entrantes. Los cambios de enlaces a bases de datos y almacenamiento se aplican con Save & Recreate, o en el siguiente arranque de un Container detenido.
• Environment Variables: una tabla de claves y valores. Edit as text abre todas las variables como líneas KEY=value, una por línea; Apply las devuelve a la tabla, y se guardan al guardar. Úsalo para pegar un archivo .env o cambiar muchos valores a la vez.
• Secrets: valores cifrados que se inyectan como variables de entorno cuando arranca el Container; nunca se vuelven a mostrar después de guardarlos.

Guardar las variables recrea un Container en ejecución, tras una confirmación, así que cuenta con una breve interrupción. En un Container detenido se guardan y se aplican cuando arranca. Un Container que pertenece a una app recibe además las variables y los secretos de su entorno; esas claves están marcadas en esta pestaña.

Gestión de fallos y limpieza

Un fallo de descarga de la imagen, una credencial de registro no disponible, un conflicto de puertos, un montaje no válido, una capacidad de ejecución no compatible o un recurso del nodo agotado deben corregirse antes de reintentar. Mientras se despliega un build de Git en el Container, los cambios de ciclo de vida, de configuración y de secretos devuelven BUILD_ROLLOUT_IN_PROGRESS hasta que termina el despliegue; consulta Orígenes Git y Build Workers. El historial de Tasks identifica la etapa que se detuvo; los reintentos sin cambiar el requisito previo suelen repetir el mismo fallo. Los errores que puedes corregir vuelven como errores del cliente con su propio código, por ejemplo 409 HOST_PORT_IN_USE con el puerto, 409 IMAGE_NOT_ON_NODE, 409 DISK_IMAGE_VOLUMES_UNSUPPORTED cuando el nodo no tiene ningún dispositivo loop libre para un volumen de imagen de disco y 404 CONTAINER_NOT_FOUND. Recrear un contenedor con Secure Runtime y una GPU se rechaza con 409 SECURE_RUNTIME_GPU_UNSUPPORTED antes de detener el contenedor.

Antes de eliminar, inspecciona las Routes, las vinculaciones de bases de datos, las concesiones, los volúmenes, los ajustes de origen y los datos exportados. Eliminar el Container elimina sus concesiones de recurso y sus enlaces a bases de datos y almacenamiento, de modo que un Container posterior con el mismo nombre no hereda ni el acceso ni las credenciales de los enlaces. Un Container que espera el primer build de su origen Git no se puede eliminar por sí solo (409 SOURCE_CONTAINER_NOT_BUILT); elimina en su lugar su origen Git. La eliminación de volúmenes es una acción destructiva aparte; conserva o haz una copia de seguridad de los datos persistentes antes de eliminar cualquiera de los dos recursos.

Detalles para operadores: recreación y recuperación

Un cambio de configuración que afecta a la imagen, el comando, el entorno, los montajes, el entorno de ejecución, los puertos, los límites o el comportamiento de reinicio puede requerir una recreación. La recreación sustituye el entorno de ejecución de Docker conservando la identidad estable del Container en Opfield y las relaciones compatibles. Las sesiones existentes dentro del proceso se interrumpen, así que programa la operación o usa un Deployment cuando la interrupción no sea aceptable.

Antes de la recreación, registra el digest actual de la imagen, el resultado de la comprobación de estado, los volúmenes conectados, el estado de las Routes y de las vinculaciones y cualquier requisito de vaciado específico de la aplicación. Cuando termine el Task, compara el nuevo entorno de ejecución con el estado deseado guardado y prueba el camino real del cliente. Si el arranque falla, restaura la configuración o la imagen anteriores que se sabe que funcionaban y vuelve a recrear; no edites el objeto de Docker fallido fuera de Opfield.

Si el nodo Docker se desconecta durante una operación, espera a un inventario nuevo tras la reconexión antes de reintentar. Puede que el host haya completado la acción de ejecución sin confirmarla. Si falta un Container pero su estado deseado sigue existiendo, usa el camino compatible de conciliación o de recreación. Eliminar y volver a crear el registro en Opfield cambia la propiedad y las concesiones, y no debería ser la primera acción de recuperación.

El acceso a la consola y a los archivos son herramientas de incidentes y de inspección, no un sustituto de una configuración reproducible. Los cambios hechos solo dentro de un contenedor en ejecución pueden desaparecer en la siguiente recreación y deben trasladarse a la imagen, a la configuración gestionada o a un volumen persistente.