Servidores y agentes

Un core de Pier puede gestionar más que su propio host. Añades un servidor remoto como agente — un demonio ligero y sin estado (pier-agent) que el core dirige a través de un canal HTTPS fijado. El core sigue siendo el único plano de control; el agente solo ejecuta comandos de Docker y reporta métricas.

Añadir, eliminar y desplegar en servidores son acciones de nivel de administrador en el panel.

Registrar un agente

Cuando creas un servidor de tipo agente, el core genera un token de arranque de corta duración y te entrega un comando de instalación. El script (servido desde GET /api/v1/servers/install-script) se ejecuta en el nuevo host y:

1. Instala Docker y el plugin de Compose si faltan, y crea la red Docker pier-net.
2. Descarga el binario pier-agent desde el core, autenticado con el token de arranque.
3. Instala pier-net-helper (inactivo — no hace nada hasta que el core envía una operación de malla).
4. Genera un certificado TLS autofirmado para el agente y calcula la huella SHA-256 de su hoja.
5. Realiza el handshake, intercambiando el token de arranque de un solo uso por un token de agente de larga duración.
6. Confirma que está activo con un primer latido.

El script de instalación fija el propio certificado autofirmado del core mediante curl --cacert, de modo que el agente responde sobre HTTPS verificado en lugar de -k.

Handshake de arranque a portador

El token de arranque es de un solo uso y de corta duración. El agente lo gasta en POST /api/v1/servers/{id}/handshake, y el core genera el token de agente de larga duración como respuesta. Ese token de larga duración se devuelve exactamente una vez y se almacena en el core únicamente como un hash SHA-256; el agente conserva el texto plano en su archivo de entorno de systemd.

Un segundo handshake contra un arranque ya canjeado se rechaza. Si el comando de instalación se filtró o se volvió a ejecutar, recrea el servidor en el panel para emitir un arranque nuevo — Pier no reemitirá silenciosamente una credencial.

A partir de entonces el agente autentica cada solicitud con Authorization: Bearer <agent token>. Puedes rotarlo desde el panel (POST /api/v1/servers/{id}/rotate): el core envía primero el nuevo token al agente, y solo lo persiste después de que el agente lo confirma, de modo que una rotación fallida nunca deja al core desincronizado.

Fijación de huella de certificado

El canal core a agente es HTTPS, pero a los agentes se les llega por IP en bruto (o IP de malla) sin cadena PKI. En lugar de validar una autoridad de certificación, el core fija la huella de la hoja TLS del agente — el SHA-256 que el script de instalación calculó y envió durante el handshake. Cada llamada posterior de core a agente se valida contra esa fijación, de modo que el canal queda protegido contra intercambios de certificados. Una huella reafirmada puede llegar en un latido posterior para volver a fijar después de que el agente regenere su certificado.

Métricas y despliegues

Una vez registrado, un agente expone:

• Métricas — CPU, memoria, disco, versión de Docker y número de contenedores, mostrados en la tarjeta del servidor (GET /api/v1/servers/{id}/metrics, proxificado al /metrics del agente).
• Despliegues — despliega o detiene un stack de Compose en el agente (POST /api/v1/servers/{id}/deploy y /stop). El core envía el YAML de Compose renderizado; el agente lo escribe en su directorio de datos y ejecuta docker compose.

El core también sondea a los pares registrados con un temporizador, mientras que los agentes envían su propio latido, de modo que el panel refleja el estado de cada servidor.

Promover un agente a core

Un agente puede ser promovido a un pier-core completo. El core exporta un paquete de promoción desde su base de datos y lo envía al agente (POST /api/v1/servers/{id}/promote). El agente escribe el paquete, descarga el binario pier-core, importa el paquete a una base de datos nueva, instala una unidad de systemd, detiene pier-agent e inicia pier. La promoción se ejecuta de forma desacoplada, de modo que el agente puede detenerse a sí mismo a medida que el nuevo core toma el control.

Próximos pasos

• Malla WireGuard — conecta tus servidores a través de una superposición cifrada.
• Federación — enlaza cores independientes y controla stacks de pares.
• Proyectos y servicios — qué despliegas en un servidor.