Malla WireGuard

Un único servidor Pier es autónomo, pero en cuanto añades servidores remotos lo habitual es que quieras que se comuniquen a través de una red privada y cifrada en lugar de la Internet pública. Pier construye esa red como una superposición WireGuard a nivel de host: cada servidor obtiene una IP privada estable, y el tráfico entre ellos viaja por un túnel cifrado.

La gestión de la malla es exclusiva del rol Owner. Todos los endpoints descritos aquí están protegidos por el control global del rol Owner.

Cómo se construye la superposición

La malla se ensambla en pasos deliberados y revisables, de modo que un error detiene el asistente en lugar de romper un túnel activo:

Paso	Endpoint	Qué ocurre
Configurar	PUT /api/v1/network/mesh	Establece la subred, el puerto de escucha y el keepalive. Solo se permite mientras la malla está deshabilitada.
Comprobación previa	GET /api/v1/network/mesh/preflight	Comprueba en cada servidor que haya un pier-net-helper accesible antes de confirmar.
Habilitar	POST /api/v1/network/mesh/enable	Asigna una IP privada a cada servidor y activa la malla.
Configurar (aplicar)	POST /api/v1/network/mesh/configure	Instala WireGuard, genera un par de claves por nodo, escribe wg0.conf y levanta cada túnel.
Deshabilitar	POST /api/v1/network/mesh/disable	Baja todas las interfaces y elimina las filas de pares.

La subred debe ser un prefijo /30 o mayor — /31 y /32 no dejan hosts utilizables y se rechazan. Al core local siempre se le asigna la primera dirección de host, de modo que puedes fijarla en archivos de entorno y manuales de operación.

La fase de configuración está secuenciada para que un fallo parcial se detenga pronto y deje un estado recuperable. Un par que falla se marca con el mensaje del helper; lo resuelves deshabilitando y volviendo a habilitar, y luego ejecutando configure de nuevo.

El pier-net-helper

Pier nunca ejecuta comandos privilegiados de WireGuard desde el proceso del core o del agente. Cada servidor ejecuta un pequeño demonio de root, pier-net-helper, que escucha en un socket Unix — /run/pier/net.sock por defecto, configurable con la variable de entorno PIER_NET_HELPER_SOCKET. El core se comunica directamente con el helper local a través de ese socket; para los servidores remotos enruta las mismas operaciones a través del proxy de malla del agente sobre el canal HTTPS fijado.

Las claves privadas se generan en el nodo y permanecen allí. El core renderiza cada wg0.conf sin una línea PrivateKey — el helper inyecta la clave local del nodo cuando escribe el archivo.

La comprobación previa de la malla existe debido a esta separación: lanza un sondeo de estado a todos los servidores y se niega a iniciar el asistente de Habilitar si algún nodo carece de un helper accesible, de modo que puedes ejecutar el instalador de adaptación por adelantado en lugar de descubrir la carencia a mitad del aprovisionamiento.

Malla de pares core a core

Los pasos anteriores conectan un core con los servidores que gestiona directamente (el nodo local y sus agentes). Para conectar dos cores independientes, emparejas sus mallas:

• POST /api/v1/network/mesh/pair/{id} — empareja la malla de este core con un core par registrado.
• POST /api/v1/network/mesh/peer/{id}/unpair — deshace el emparejamiento en ambos lados.

El emparejamiento lo asigna el Owner: el core iniciador asigna IPs de malla para los nodos del core remoto desde su propia subred, envía el plan a través del canal de token de par y almacena los nodos remotos como pares externos, de modo que su propio wg0.conf gana bloques [Peer] para ellos. En esta versión ambos cores ya deben haberse registrado mutuamente como pares, y la malla del core de destino debe estar deshabilitada antes del emparejamiento.

DNS de servicios

Sobre la superposición, puedes registrar nombres de servicio lógicos que se resuelven a cualquier nodo que aloje un servicio en ese momento. Un nombre como db se convierte en db.mesh, inyectado como una entrada extra_hosts en cada stack al desplegar, de modo que los servicios consumidores se conectan a un nombre estable en lugar de a una IP.

Gestiona estas asignaciones (exclusivo del rol Owner) en:

• GET / POST /api/v1/network/service-dns
• PUT / DELETE /api/v1/network/service-dns/{name}

Los nombres siguen reglas de etiquetas RFC 1123 reforzadas — letras minúsculas, dígitos y guiones, comenzando y terminando en alfanumérico, hasta 31 caracteres — y no pueden colisionar con un nombre de servidor existente. Añadir o cambiar una asignación encola un redespliegue en segundo plano para que los stacks en ejecución adopten la nueva entrada extra_hosts.

Próximos pasos

• Servidores y agentes — añade los servidores remotos que se unen a la malla.
• Clústeres de bases de datos — clústeres entre servidores que dependen de la superposición.
• Redes — la red Docker pier-net por host.