Roles de los nodos e instalación

Estos requisitos de los roles se aplican tanto a los nodos registrados en tus propios servidores como a las VM creadas a través de Opfield.

El rol elegido en el registro decide qué recursos puede controlar el host, qué perfil de software se instala y a qué afecta un fallo del host. Elige por responsabilidad, no por los paquetes que ya tiene la máquina.

Antes del registro, decide el rol, el responsable del host, el dominio de fallo, la sensibilidad de los datos y quién recupera el host. El registro está completo cuando hay una única identidad de nodo duradera instalada en el host previsto, que informa solo de las capacidades esperadas y supera una comprobación de aceptación de bajo riesgo específica del rol antes de que se le asignen recursos de producción.

Detalles para operadores: requisitos previos de los perfiles

Usa el comando de instalación generado en el flujo de creación del nodo. Contiene material de registro acotado y la identidad de Opfield fijada.

nginx: requiere nginx, puertos públicos de ingress cuando corresponda, validación de la configuración y acceso a los logs.
Docker: requiere un Docker Engine compatible y permisos para las operaciones de ejecución configuradas. El instalador también instala el lease watchdog, opfield-lease-watchdog, un servicio aparte que la conmutación por error del plano de datos necesita en los nodos que tienen leases de Availability. En un nodo instalado antes de que existiera el watchdog, un daemon de Docker que se ejecuta como root con systemd u OpenRC lo instala por sí mismo; para un daemon instalado con --user <non-root user>, vuelve a ejecutar el instalador de nodos Docker con sudo y el mismo --user, porque de lo contrario una ejecución no interactiva cambia el servicio del daemon a root. Cada volumen de imagen de disco gestionado ocupa un dispositivo loop, y el daemon instala un paso de arranque, opfield-volume-images, que monta esos volúmenes antes de que arranque Docker.
storage: ejecuta el daemon de Docker como root y requiere almacenamiento dedicado, dispositivos loop y compatibilidad con montajes; el instalador formatea, monta, amplía y libera una imagen de prueba antes del registro y se detiene si el host no puede hacerlo. Cada base de datos gestionada, cada miembro de almacenamiento de objetos y cada copia de seguridad en ejecución ocupan un dispositivo loop, así que un invitado LXC necesita que su host le pase /dev/loop-control y un pool de dispositivos loop dimensionado para todos ellos. El nodo necesita HTTPS saliente hacia ghcr.io para el runner de copias de seguridad. El instalador también instala el lease watchdog, opfield-lease-watchdog, que usan las bases de datos y el almacenamiento en varios servidores. El modo anterior databases se acepta como alias. Consulta Requisitos previos de los nodos Storage y Docker.
builder: requiere systemd y capacidad dedicada de BuildKit/containerd, y no debe tener un socket de Docker Engine. En un host sin systemd, el instalador se detiene antes de instalar o descargar nada.
monitoring: proporciona la recopilación de monitorización compatible.
Relay supervisor/worker: amplía la capacidad y la resiliencia de Relay con una ubicación explícita.

Tras la instalación, valida el informe de capacidades en lugar de suponer que los paquetes del host implican compatibilidad. Las funciones de GPU, Secure Runtime, builder, almacenamiento y migración dependen de capacidades informadas en buen estado.

Elige el rol

Ingress: termina TLS y sirve los dominios y las Routes públicos. Necesita validación de la configuración de nginx, almacenamiento de certificados, logs y puertos públicos cuando corresponda.
Docker: gestiona las cargas de trabajo de aplicaciones ordinarias y los recursos de Docker. Necesita un Docker Engine compatible y los privilegios que requieran las funciones de ejecución seleccionadas.
Build Worker: ejecuta los builds desde Git en servicios BuildKit/containerd aislados. Debe estar dedicado a los builds y no debe exponer un socket ordinario de Docker Engine al perfil de build.
Storage: ejecuta PostgreSQL, almacenes clave-valor y ClickHouse gestionados, almacenamiento de objetos SeaweedFS gestionado y los trabajos de copia de seguridad de bases de datos, con una preparación del almacenamiento dedicada y un perfil de daemon de Docker restringido. Los contenedores de aplicaciones genéricos y los builds se rechazan. Los nodos registrados con el antiguo rol Databases conservan su identidad, su registro, su configuración y sus datos; actualizar su daemon activa las capacidades de Storage sin volver a registrarlos ni trasladar los datos.
Monitoring: recopila el estado y las métricas compatibles del host sin recibir permisos sobre el ciclo de vida de las cargas de trabajo.
Relay: instala el supervisor de Relay, anuncia una dirección accesible y se une al Relay Pool de los Secure Links.

Flujo de registro estándar

Abre Nodes, selecciona Add Node y elige External VM.
Selecciona el Node Type previsto y lee su descripción.
Introduce un nombre estable de cara a los operadores.
Para Relay, introduce la dirección a la que pueden llegar los nodos participantes por TCP 9443.
Crea el nodo pendiente.
Copia el comando de instalación de un solo uso generado. Pertenece a la instalación de Opfield que lo muestra: descarga el instalador de la versión de esa instalación, lo ejecuta solo cuando su suma de comprobación coincide con la versión y fija el daemon más reciente de la misma línea de versiones.
Ejecuta el comando en el host Linux previsto.
Mantén abierto el diálogo de resultados mientras el daemon se instala y se registra; se cierra automáticamente cuando ese nodo concreto pasa a estar en línea.
Abre el detalle del nodo y verifica el rol, el nombre de host, la versión, las capacidades, las métricas y las direcciones de servicio.

La acción Add relay node de los ajustes de Relay abre el mismo flujo de registro con Relay preseleccionado y bloqueado. Los miembros de Relay aparecen como capacidad del pool lista solo cuando el registro y el informe de estado tienen éxito.

Preparación del host

Usa un host o una VM dedicados siempre que el rol sea responsable de un límite de confianza fuerte. Confirma el DNS, la hora del sistema, la accesibilidad saliente hacia Relay, los requisitos previos de paquetes y de ejecución, el almacenamiento persistente y systemd u OpenRC antes de ejecutar el instalador. No copies un comando de instalación entre registros de nodos pendientes.

Los nodos Storage requieren la comprobación previa de almacenamiento del instalador. Los Build Workers requieren capacidad de ejecución y de almacenamiento dedicada. Los nodos Relay requieren una dirección anunciada accesible y deben colocarse en dominios de fallo distintos cuando el pool tenga que proporcionar resiliencia.

Qué comprueba el instalador

Conexión. Una ejecución del instalador, y cada nueva ejecución en un nodo registrado, solo tiene éxito cuando el daemon que ha arrancado se ejecuta con systemd u OpenRC y Opfield ha aceptado su sesión. En caso contrario, termina con un error, indica el log del daemon e imprime sus últimas líneas; espera hasta 90 segundos a la sesión. Un token que ya se usó o que ha caducado se notifica como rechazado por Opfield. Los hosts sin systemd ni OpenRC reciben un lanzador independiente que no sobrevive a un reinicio.
Nueva ejecución del comando de configuración. Volver a ejecutar el propio comando de configuración de un nodo, con su token ya usado, conserva el registro y se ejecuta como una nueva ejecución sin token. Un token distinto en un host registrado no se usa: los instaladores de Docker y de monitorización se detienen con un error y no cambian nada (en un nodo registrado antes de la 2.11.1 avisan y continúan la actualización), y el instalador de nginx se registra con el nuevo token, pero conserva el registro anterior cuando Opfield lo rechaza. Para registrar el host como otro nodo, detén el daemon, aparta su directorio certs y su state.json y ejecuta el nuevo comando.
Respuestas. Sin -y, el instalador pregunta en el terminal y se detiene cuando no puede leer una respuesta, por ejemplo sin terminal o con su salida canalizada a través de tee; una respuesta que falta nunca se toma como consentimiento. Rechazar Proceed with installation? o detenerse tras el resumen termina con un error.
Secure Runtime. Una instalación nueva de un nodo Docker configura Secure Runtime cuando el host lo admite. En un host sin compatibilidad, o cuando la configuración falla, el instalador avisa con el motivo y continúa, y el nodo informa del mismo motivo en sus capacidades. Con --secure-runtime, la instalación falla en su lugar; la opción también instala Secure Runtime en una instalación existente. En un /etc/docker/daemon.json existente, la configuración solo añade runtimes.runsc, después de guardar una vez el original como daemon.json.opfield-backup; todas las demás claves se quedan como estaban.
Versión del daemon. Sin --version, un instalador instala la última versión estable del daemon, pero una nueva ejecución nunca instala un daemon más antiguo que el instalado, por ejemplo en un nodo que ejecuta una versión preliminar más reciente. En ese caso, imprime la versión instalada y la versión a la que se resuelve latest, y conserva la versión instalada. Para instalar la versión más antigua, indícala con --version (OPFIELD_NODE_DAEMON_VERSION en los instaladores de daemons). Esto se aplica a los instaladores de Docker, Build Worker, Storage, nginx, monitorización y Relay.
Copias de seguridad. Cuando los instaladores de monitorización, nginx y Docker sustituyen un archivo, como el binario del daemon o una configuración de nginx, solo conservan la copia de seguridad más reciente (<file>.backup.<timestamp>).

Ejecuta un daemon sin root

Los daemons de monitorización, Docker (perfil docker), nginx y Relay pueden ejecutarse como un usuario existente sin privilegios de root: pasa --user <user> al instalador de monitorización, Docker o nginx, o fija OPFIELD_RELAY_RUN_USER (y, opcionalmente, OPFIELD_RELAY_RUN_GROUP) para el instalador de Relay. El propio instalador se sigue ejecutando con sudo y se detiene antes de cambiar el host cuando el usuario no existe. Los nodos Storage y los Build Workers solo se ejecutan como root.

Cambio de usuario. Vuelve a ejecutar el instalador del nodo con otro --user, o sin --user para volver a root. El nodo conserva su registro y su identidad de host; un Relay registrado no necesita --token para una nueva ejecución así. En los nodos Docker y nginx, el instalador lo prepara todo mientras el daemon sigue sirviendo y lo detiene justo antes de que arranque el nuevo proceso; el daemon de monitorización y el supervisor de Relay se detienen primero. El daemon se detiene antes de que ninguno de sus archivos cambie de propietario. El cambio reinicia el daemon una vez: las conexiones a través de sus enlaces de bases de datos, almacenamiento y contenedores se cortan una vez durante unos 1,5 segundos y los clientes se vuelven a conectar, como en cualquier reinicio del daemon. El tráfico de las Routes a través de los Secure Links solo espera, porque con systemd el daemon de un nodo Docker o nginx entrega sus sockets de enlace a systemd, que los mantiene durante el cambio. En un nodo Docker cuyos enlaces de almacenamiento todavía usan sidecars por enlace anteriores a la 2.11.1, el cambio también recrea esos sidecars. El usuario anterior conserva las pertenencias a grupos que le dio el instalador, como docker; elimínalas con gpasswd -d <user> docker.
Docker. El instalador añade el usuario al grupo docker, lo que equivale a root en el host. Sin root, no están disponibles los volúmenes de imagen de disco, el traslado de datos de volúmenes entre nodos, los tamaños de los logs de los contenedores ni la instalación de Secure Runtime desde Opfield; para instalar Secure Runtime, vuelve a ejecutar el instalador con el mismo --user y --secure-runtime (Node Details muestra el comando). El lease watchdog sigue ejecutándose como servicio root.
nginx. nginx ya debe ejecutarse como el mismo usuario con CAP_NET_BIND_SERVICE, y el usuario debe ser propietario de /etc/nginx, /var/log/nginx y los directorios temporales de nginx; usa --nginx-mode integrate. Ejecutar nginx como su usuario de la distribución (www-data o nginx) e instalar el daemon como ese usuario es la configuración más sencilla. Con OpenRC, fija command_user="<user>:<group>" y capabilities="^cap_net_bind_service" en /etc/conf.d/nginx y pid /run/nginx/nginx.pid; en nginx.conf. Cuando nginx no se ejecuta como el usuario, el instalador se detiene antes de cambiar nada y enumera lo que hay que preparar. Para volver a root, vuelve a ejecutar antes nginx como root.
Relay. Un puerto de Relay por debajo de 1024 necesita systemd u OpenRC; el instalador concede la capacidad de bind.
Consola del host. console.user en la configuración del daemon ejecuta las sesiones de consola como otro usuario solo en un daemon que se ejecuta como root. Un daemon que se ejecuta como su propio usuario rechaza las sesiones de consola mientras console.user indique otro usuario (409 NODE_CONSOLE_USER_UNAVAILABLE), y la página del nodo indica la solución: eliminar console.user o ejecutar el daemon como root.

Desactiva la consola y los archivos del host

Todos los tipos de daemon leen dos interruptores de acceso al host de su archivo de configuración: console.enabled y files.enabled, ambos true por defecto. Con console.enabled: false, el daemon rechaza la consola del host, incluidos los comandos puntuales del asistente y de MCP; con files.enabled: false, rechaza el acceso a los archivos del host. Los instaladores de Docker, nginx, monitorización y Relay los fijan con --disable-console y --disable-files, y los diálogos de configuración de nodos ofrecen las casillas Disable host console y Disable host files, que añaden esas opciones. Los nodos contratados a través de un proveedor de hosting los instala el propio Opfield; desactiva allí los interruptores editando el archivo de configuración.

Los interruptores solo existen en el nodo, así que un administrador de Opfield no puede volver a activarlos de forma remota. Para cambiar uno, edita el archivo en el nodo y reinicia el daemon. Opfield rechaza las peticiones desactivadas con 409 NODE_CONSOLE_DISABLED o 409 NODE_FILES_DISABLED. Las consolas y los archivos de los contenedores no se ven afectados. Para eliminar el acceso al host, desactiva ambos: un daemon que se ejecuta como root y todavía puede escribir archivos puede cambiar el host y volver a activar la consola. La página del nodo muestra una advertencia mientras la consola está desactivada y el acceso a los archivos está activado. Para un Relay en la máquina de otra persona, usa el modo protegido.

Invitados Alpine, OpenRC y LXC

Los instaladores admiten OpenRC además de systemd, también para los daemons que se ejecutan como su propio usuario. Un nodo Docker necesita que Docker dé a sus contenedores los controladores de cgroup memory, pids y cpu, porque el conector de Secure Links y las cargas de trabajo gestionadas se ejecutan con límites. El instalador lo comprueba y se niega a registrar el nodo cuando falta un controlador; no cambia la configuración de cgroups del host.

En un invitado LXC de Alpine con OpenRC, el cgroup raíz a menudo no pasa ningún controlador hacia abajo, porque todos los procesos están en él. Deja que el servicio cgroups de OpenRC saque los procesos antes de activar los controladores: ejecuta rc-update add cgroups boot, pon lo siguiente en /etc/conf.d/cgroups y reinicia el invitado.

# Move every process out of the root cgroup so that the cgroups service can pass the controllers down.
start_pre() {
  [ -w /sys/fs/cgroup/cgroup.subtree_control ] || return 0
  mkdir -p /sys/fs/cgroup/init
  for pid in $(cat /sys/fs/cgroup/cgroup.procs); do
    echo "$pid" > /sys/fs/cgroup/init/cgroup.procs 2>/dev/null
  done
  return 0
}

Después verifica con cat /sys/fs/cgroup/cgroup.subtree_control /sys/fs/cgroup/docker/cgroup.controllers: ambos deben enumerar memory, pids y cpu. La configuración del contenedor LXC en el hipervisor no necesita ningún cambio para esto.

Verificación y limpieza

El registro solo está completo cuando el daemon informa de las capacidades esperadas y llega la primera instantánea de inventario y métricas. Si la instalación falla antes del registro, inspecciona los logs del servicio local y del instalador. Elimina el registro pendiente solo cuando abandones esa identidad; nunca debe reutilizarse el token de un nodo eliminado.

Modos de fallo de la instalación

El instalador de nodos nginx se puede volver a ejecutar en el mismo host tras una ejecución fallida, y una nueva ejecución conserva el modo de nginx de la instalación existente. Si el comando no puede descargar o arrancar el daemon, verifica el HTTPS saliente, el DNS, la hora del sistema, el estado del gestor de paquetes, la arquitectura y el espacio libre en disco. Si el daemon arranca pero el registro no se completa, verifica la accesibilidad de Relay, que el token de un solo uso no se haya consumido ya y que el comando se haya ejecutado para el nodo pendiente que se muestra en el diálogo. No generes varios registros pendientes para probar sus comandos de forma intercambiable.

Un nodo que se registra sin su capacidad esperada no está listo para ese rol. Comprueba el servicio del rol, los permisos de sockets o de almacenamiento, las funciones del kernel necesarias y los logs de arranque acotados del daemon. Corrige el requisito previo del host y deja que se actualice el informe de capacidades; cambiar el Node Type después de la instalación no sustituye a instalar el perfil correcto.

Si el host se registró con el rol equivocado, retira esa identidad de forma deliberada y crea un nodo nuevo con el rol correcto. Antes de eliminarla, asegúrate de que no se asignaron recursos ni operaciones a la identidad equivocada y desinstala el material de su daemon para que no pueda volver a conectarse de forma inesperada.

Seguridad tras la instalación

Trata el comando de instalación generado como una credencial de corta duración. Ejecútalo solo en el host previsto, no lo pegues en chats compartidos ni en automatizaciones de shell persistentes y elimínalo de las notas operativas tras el registro. El certificado del daemon instalado se convierte en la identidad duradera y no debe copiarse a otra máquina ni restaurarse en dos hosts activos.

Limita el acceso local a la configuración del daemon, al material de certificados, a las credenciales de registros, al almacenamiento de bases de datos y a los sockets específicos de cada rol. El registro establece la confianza entre Opfield y el host; no bastiona los servicios no relacionados del sistema operativo. Aplica la configuración base de hosts de la organización y mantén la superficie de ataque del rol no más amplia que sus requisitos previos documentados.