Arquitectura
Axelix tiene una aplicación central — **Axelix Master** — que se comunica con cada servicio Spring Boot que se quiera gestionar mediante una dependencia **Axelix Starter** en el servicio. La interfaz web y el servidor MCP están incluidos en Master, por lo que un único proceso sirve los mismos datos al navegador y al agente de IA.
┌───────────────────────┐
│ Spring Boot 2 Service │
┌──────────────▶│ + Axelix Starter │
│ └───────────────────────┘
┌──────────┐ ┌───┴────────┐ ┌───────────────────────┐
│ UI │─REST───▶│ │─────▶│ Spring Boot 3 Service │
└──────────┘ │ Axelix │ │ + Axelix Starter │
│ Master │ └───────────────────────┘
│ (UI + MCP) │ ┌───────────────────────┐
┌──────────┐ │ │─────▶│ Spring Boot 2 Service │
│ AI Agent │─MCP────▶│ │ │ + Axelix Starter │
└──────────┘ └───┬────────┘ └───────────────────────┘
│ ┌───────────────────────┐
└──────────────▶│ Spring Boot 3 Service │
│ + Axelix Starter │
└───────────────────────┘Componentes
- Axelix Master: sirve la interfaz, expone la API REST que esta consume, ejecuta el servidor MCP integrado, se comunica con cada servicio gestionado por HTTP y mantiene el registro de instancias.
- Axelix Spring Boot Starter: existen módulos separados para Spring Boot 2, Spring Boot 3 y Spring Boot 4. Elija el que corresponda a su aplicación. El starter expone los endpoints que Master necesita (beans, entorno, cachés, tareas programadas y otros) y, opcionalmente, puede autorregistrarse en Master al arrancar.
Comunicación
- Navegador ⇄ Master: REST/JSON a través del mismo origen desde el que Master sirve el frontend estático.
- Agente de IA ⇄ Master: Model Context Protocol sobre HTTP. Consulte los esquemas de credenciales en autenticación del servidor MCP.
- Master → servicio gestionado: HTTP a los endpoints del Axelix Starter en el servicio. Cada lectura (beans, entorno, tareas programadas y otras) y cada acción de modificación (establecer el nivel de un logger, vaciar una caché o iniciar una tarea) es una llamada HTTP síncrona.
- Servicio gestionado → Master: solo se utiliza con el autorregistro activado. El starter envía un registro al arrancar y mensajes periódicos de actividad; la carga útil incluye la URL que Master debe utilizar para acceder al servicio.
Descubrimiento de servicios
Un servicio aparece en el registro de instancias de Master por una de estas dos vías:
- Descubrimiento automático desde Master: Master consulta periódicamente la API de la plataforma para encontrar servicios que incluyan el Axelix Starter. Actualmente el descubrimiento automático solo es posible en Kubernetes, y está activado de forma predeterminada en el chart de Helm oficial de Axelix.
- Autorregistro desde el starter: el Axelix Starter envía una solicitud de registro a Master al arrancar y mensajes de actividad a intervalos regulares.
Consulte cómo funciona el descubrimiento para conocer cada vía.
Despliegue y escalado
- Master es el proceso central. Actúa como el cerebro que acepta todas las solicitudes de la interfaz y las dirige al servicio correspondiente.
- La base de datos garantiza la persistencia. Axelix Master necesita mantener cierto estado y, para ello, utiliza una base de datos. De forma predeterminada se utiliza SQLite. Aunque SQLite es suficiente para despliegues pequeños, hay que tener en cuenta que su archivo de base de datos no sobrevive a un reinicio del contenedor sin un volumen montado. Para despliegues mayores, configure PostgreSQL o MySQL; consulte base de datos.
- La conectividad de red es responsabilidad del operador. Master debe poder llamar a cada servicio gestionado por HTTP desde su propia red: todas las lecturas y modificaciones pasan por esa conexión. Los mensajes de actividad del autorregistro son las únicas llamadas en sentido contrario.
Despliegues con varios Master
Ejecute una sola réplica activa de Master a la vez. Los trabajos en segundo plano y las cachés en memoria de Master presuponen una única instancia; una base de datos compartida no hace segura la ejecución de varias réplicas activas. Si sus ámbitos de descubrimiento automático difieren, cada réplica puede eliminar del registro las instancias de servicios descubiertas automáticamente por la otra durante su exploración.
Siga las restricciones de despliegue y actualización con una sola instancia de Actualización de Axelix. Actualmente no se admite un Master de alta disponibilidad con varias réplicas.
Modelo de seguridad
La autenticación de agentes de IA mediante MCP y de personas mediante la interfaz puede realizarse con autenticación Basic o con OAuth2/OIDC. A continuación se ofrece un breve resumen; consulte autenticación para conocer el modelo completo de credenciales.
Autenticación Basic
En este caso, se presupone que los usuarios se crearán en la base de datos a la que está conectado Axelix Master. El perfil del usuario se almacena en la base de datos de Axelix Master, algo adecuado para despliegues pequeños.
Actualmente, los usuarios solo pueden crearse manualmente a través de la interfaz, con la intervención de un ingeniero. El proveedor de Terraform está en desarrollo.
Al iniciar sesión, se solicitan las credenciales a la persona o al agente de IA y se comprueban con la base de datos. Cuando el inicio de sesión se realiza mediante el formulario de la interfaz, el backend envía una cookie de autenticación específica que contiene el token de acceso JWT.
Los agentes de IA que utilizan autenticación Basic envían las credenciales en la cabecera HTTP estándar Authorization:
Authorization: Basic <base64(username)>, tal como define
RFC 7617.
Al utilizar autenticación Basic con el servidor MCP, el agente de IA debe enviar esta cabecera Authorization en cada solicitud.
OAuth2 y OIDC
En las empresas modernas, SSO (inicio de sesión único) es un patrón habitual de IAM. A menudo se implementa mediante OAuth2 y OIDC.
Axelix Master puede configurarse para autenticar al usuario con un proveedor de identidad OIDC externo. En ese caso, Axelix
Master confía en el token del proveedor OIDC y también puede solicitar información adicional sobre el usuario actual
al proveedor (por ejemplo, consultando el endpoint /userinfo, si está disponible).
IAM: matices importantes
- Clave de firma JWT compartida. Master y cada Axelix Starter deben utilizar la misma clave de firma y el mismo algoritmo HMAC.
Master comprueba los permisos del usuario autenticado para las solicitudes de la interfaz y MCP. Al llamar a un starter desde la versión 1.3,
envía un JWT de corta duración que lo identifica como
AXELIX.MASTER, sin roles ni permisos del usuario. El starter verifica la firma, la caducidad y la identidad de Master. Para starters anteriores, Master vuelve a emitir el token del usuario con nombres de permisos heredados, porque esos starters siguen comprobando los permisos por sí mismos. El starter también firma las solicitudes de registro y los mensajes de actividad con la clave compartida. Si las claves no coinciden, se produce un401. - TLS es responsabilidad del operador. Master escucha por HTTP sin cifrar de forma predeterminada. Sitúelo detrás de un
proxy que termine TLS y establezca
axelix.master.auth.cookie.secure=truepara cualquier despliegue que no sea local.
Motivación
Este documento explica los principales problemas que Axelix resuelve para los desarrolladores de Spring Boot y las organizaciones. Mediante ejemplos reales, se presentan las dificultades que inspiraron la creación de Axelix.
Cómo funciona el descubrimiento
Cómo Axelix Master descubre qué instancias Spring Boot existen y mantiene su estado actualizado, ya sea encontrándolas en Kubernetes o permitiendo que cada instancia se registre.