Saltar al contenido
cloud-webv0.1.0
Documentación

Arquitectura

                 GitLab (gitlab.com o self-hosted)
                     ▲  OAuth / API          │ webhook (push)
                     │                       ▼
   Dashboard ─▶  Plano de control (cloudweb-server)
                 API · scheduler · CA · SQLite
                     ▲  mTLS (los agentes llaman al servidor)
        ┌────────────┼───────────────┐
   Nodo (cloudweb-agent)   Nodo …    Nodo …
   WireGuard · Docker · Caddy · registro de imágenes
        └──── malla WireGuard 10.77.0.0/16 ────┘

Plano de control

Un único proceso Go con la API REST (más SSE para logs), el dashboard embebido, el scheduler (mejor ajuste por carga de CPU/memoria), un reconciliador y la CA interna del clúster. El estado vive en SQLite (un archivo, con backup automático antes de migrar). Los secretos (variables de entorno, secreto OAuth, tokens de GitLab) se cifran con AES-256-GCM usando una clave maestra local.

Agentes

Cada nodo ejecuta cloudweb-agent, que vive en su propio repositorio (cloud-web-node) y se versiona y publica por separado; hablan un protocolo versionado y un agente incompatible recibe un 426 con el rango soportado. Se une con un token de un solo uso y recibe un certificado de cliente de la CA (la clave privada nunca sale del nodo). Desde ahí el agente llama al plano de control por mTLS —por eso funciona detrás de NAT—: latidos con su capacidad, órdenes pendientes, reportes de despliegue, rutas y peers de la malla. Las órdenes son persistentes: si el agente se desconecta, las recibe al volver.

Despliegues

  1. Un push (o el botón de redeploy) crea un despliegue queued; el scheduler elige nodo y emite la orden.
  2. El agente clona el commit exacto con credenciales efímeras, construye (Dockerfile o buildpacks), publica la imagen en el registro interno y arranca el contenedor.
  3. Se verifica la salud (respuesta HTTP); recién entonces el ingress cambia el tráfico y la instancia vieja se detiene tras un período de drenaje (blue/green).
  4. Si algo falla, el despliegue queda failed y la versión anterior sigue sirviendo.

Estados: queued → building → deploying → running (o failed); el reemplazado pasa a superseded. Si un nodo cae, sus instancias se reprograman en otro nodo con la misma imagen.

Ingress

Los nodos de ingress ejecutan Caddy (contenedor Docker, o un binario con --caddy-bin). El agente genera su configuración desde la tabla de rutas del plano de control y la recarga sin cortes cuando una instancia arranca, se mueve o se detiene. Caddy obtiene los certificados TLS y redirige HTTP a HTTPS.

Registro de imágenes

registry:2 corre en el nodo del plano de control, publicado sólo en la dirección de malla y con TLS emitido por la CA del clúster. Todos los nodos configuran su Docker para confiar en esa CA, de modo que cualquier nodo puede traer una imagen (rollback y reprogramación sin recompilar).

Qué no hace (todavía)

Alta disponibilidad del plano de control, multi-tenant/RBAC, bases de datos gestionadas, autoscaling, volúmenes persistentes distribuidos y proveedores Git distintos de GitLab (existe la interfaz GitProvider para sumarlos).