Federación
La federación enlaza cores de Pier independientes. Un core primario puede obtener una vista de solo lectura de los proyectos y stacks de sus pares y — cuando se le concede un token — desplegar, reiniciar y desmontar stacks en esos pares desde un único panel. Cada core mantiene su propia base de datos; la federación es una superposición de control, no una instalación fusionada.
Las concesiones de federación son exclusivas del rol Owner; las superficies de lectura y escritura descritas a continuación son acciones de nivel de administrador.
Federación de lectura (sincronización)
Sección titulada «Federación de lectura (sincronización)»Un planificador en segundo plano sondea a cada par registrado y refresca una caché local de sus proyectos y stacks. La sincronización se ejecuta aproximadamente cada 45 segundos (tras un breve retraso de arranque), obteniendo proyectos y stacks de la API de lectura normal de cada par y reemplazando las filas en caché de ese par dentro de una transacción. Un sondeo fallido deja en su lugar los últimos datos conocidos en lugar de vaciar la caché, de modo que el panel puede mostrar cuán desactualizada está la vista de un par.
La vista de solo lectura en caché se expone en el primario en:
GET /api/v1/federation/projects— proyectos locales más los proyectos de pares en caché, etiquetados por origen.GET /api/v1/federation/stacks— lo mismo para los stacks, incluyendo si cada par está emparejado para escrituras.GET /api/v1/federation/status— contabilidad de sincronización por par (última sincronización, último error, fallos consecutivos).POST /api/v1/federation/sync— dispara un refresco fuera de banda en lugar de esperar al temporizador.
Concesiones de tokens de par
Sección titulada «Concesiones de tokens de par»La autenticación entre cores usa tokens de federación. En el par, el operador genera un token (POST /api/v1/federation-tokens con una etiqueta); el texto plano se muestra exactamente una vez y se almacena solo como un hash SHA-256 más un prefijo visible corto. El operador lo copia en el primario, que lo envía en las llamadas de escritura en la cabecera X-Pier-Federation.
Gestiona los tokens en el par en:
GET / POST /api/v1/federation-tokens— listar y generar.DELETE /api/v1/federation-tokens/{id}— revocar (una revocación suave que conserva la fila para auditoría).
Un token de federación autoriza únicamente la superficie de control de federación del par — crear y gestionar los stacks que el primario despliega. No puede tocar los usuarios, sesiones ni la configuración de administrador del par, y no concede control sobre los stacks que el propio par ya posee.
Federación de escritura
Sección titulada «Federación de escritura»Con un token en su lugar, el primario controla los stacks de un par a través de rutas de paso que reenvían al par sobre el canal X-Pier-Federation:
| Acción | Ruta (primario) |
|---|---|
| Crear stack | POST /api/v1/federation/peer/{server_id}/stacks |
| Desplegar | POST /api/v1/federation/peer/{server_id}/stacks/{stack_id}/deploy |
| Bajar | POST /api/v1/federation/peer/{server_id}/stacks/{stack_id}/down |
| Reiniciar | POST /api/v1/federation/peer/{server_id}/stacks/{stack_id}/restart |
| Registros | GET /api/v1/federation/peer/{server_id}/stacks/{stack_id}/logs |
| Liberar | POST /api/v1/federation/peer/{server_id}/stacks/{stack_id}/release |
En el par, estas llegan a un router dedicado /api/v1/agent protegido por el token de federación. Cada stack creado de esta forma es propiedad del token emisor: el par hace cumplir la propiedad, de modo que un primario no puede gestionar los stacks federados de otro primario, y liberar un stack lo devuelve al propio panel del par sin tocar sus contenedores en ejecución.
Migrar stacks entre pares
Sección titulada «Migrar stacks entre pares»Puedes mover un stack del core local a un par emparejado con POST /api/v1/stacks/{id}/migrate, pasando el servidor de destino. La migración está limitada a stacks de Compose sin estado — un stack con volúmenes nombrados o anónimos se rechaza, ya que sus datos no viajarían con él. La canalización crea y despliega el stack en el destino, luego desmonta el origen y elimina su registro local.
La conmutación de DNS no está automatizada. Cada servidor ejecuta su propio Traefik, así que tras una migración vuelves a apuntar el dominio del stack al nuevo servidor por tu cuenta. La respuesta devuelve los dominios de origen como guía para exactamente este paso.
Próximos pasos
Sección titulada «Próximos pasos»- Servidores y agentes — registra los pares con los que federas.
- Malla WireGuard — la superposición cifrada entre cores.
- Proyectos y servicios — qué contiene un stack federado.