Primeros pasos
Esta página describe la forma recomendada de implantar Axelix en una organización: con qué entornos empezar, en qué orden instalar los componentes y cómo llegar a producción de forma segura. Cada paso incluye los comandos concretos y la configuración mínima, con enlaces a las páginas de configuración detallada para consultar la referencia completa.
Los fragmentos de esta página fijan la versión 1.3.1 como ejemplo. Consulte la página de versiones
para obtener la última etiqueta publicada y sustitúyala en sus comandos.
Axelix y sus entornos
Un ciclo de desarrollo de software típico abarca varios entornos. Independientemente de sus nombres —desarrollo, sandbox, QA, UAT o preproducción—, todos pertenecen a una de dos categorías: producción y no producción.
La primera pregunta que suelen hacer los equipos es: ¿debe ejecutarse Axelix Master en producción? Sí. Master está diseñado para ejecutarse tanto en producción como en entornos de pruebas, desde el punto de vista del rendimiento, la seguridad y la tolerancia a fallos. Ejecutar Master en producción es una práctica establecida, no un uso no previsto.
Sin embargo, recomendamos encarecidamente mantener separado el despliegue de producción de Axelix del que gestiona los entornos de pruebas. Es decir, no ejecute un único Master para todos los entornos. Los motivos:
- El control de acceso difiere. La configuración RBAC de un entorno de pruebas casi nunca coincide con la de producción. La lista de personas autorizadas a cambiar niveles de registro, activar o desactivar cachés o realizar un volcado del heap en producción es mucho más reducida que en preproducción. Consulte roles y permisos.
- Las reglas de red difieren. Las reglas que controlan quién puede acceder a la interfaz y al servidor MCP de Master suelen ser mucho más estrictas en producción que en los entornos de pruebas.
- Las políticas diferirán. También se prevé que las políticas de Axelix Enterprise, actualmente en desarrollo, sean específicas de cada entorno.
Cada despliegue de Master puede indicar a qué entorno corresponde mediante la propiedad axelix.master.environment (por
ejemplo, production o staging). Actualmente esta etiqueta solo se utiliza en el registro estructurado,
pero configurarla desde el primer día permite que los despliegues se identifiquen por sí mismos.
Con esta separación, la adopción comienza en pruebas. Así, cuando Axelix llega a producción, tanto la configuración como los hábitos del equipo ya se han validado.
Paso 1 — Preparar la base de datos
Master necesita una base de datos relacional. Incluye SQLite integrado y la URL
predeterminada jdbc:sqlite:axelix.db, por lo que la primera ejecución no necesita ninguna configuración de base de datos.
Este valor permite empezar rápidamente.
Si ya ha terminado de experimentar y quiere obtener valor real de la instalación, elija un motor de la lista admitida: PostgreSQL, MySQL o SQLite. Para cualquier uso que vaya más allá de una prueba de un solo nodo, elija PostgreSQL o MySQL: SQLite almacena los datos en un archivo local, que no sobrevive a reinicios del contenedor sin un volumen montado y no puede respaldar varias réplicas de Master. Tenemos previsto ampliar la lista de motores admitidos en futuras versiones.
Prepare la base de datos y un usuario con permisos para migrar el esquema, porque Master aplica su propio esquema: Liquibase se ejecuta en cada arranque y nunca se aplican migraciones manualmente. Consulte migraciones de base de datos. La conexión se configura con tres propiedades descritas en la sección base de datos.
Cuando la base de datos esté lista, continúe.
Paso 2 — Instalar Master en un entorno de pruebas
Instale primero Master en un entorno de pruebas (o en varios, si mantiene un despliegue independiente de Axelix por entorno). Cualquier formato sirve; elija el que mejor encaje con su infraestructura: JAR, Docker, Docker Compose o Kubernetes con el chart de Helm oficial. El inicio mínimo para cada uno:
La imagen se publica en GitHub Container Registry. Los comandos siguientes utilizan la última versión,
1.3.1; cambie la etiqueta para ejecutar otra:
docker run --rm -p 2935:2935 ghcr.io/axelixlabs/axelix:1.3.1Si no se configuran propiedades JWT, Master utiliza la clave de firma integrada. Utilícela solo para una prueba local; consulte ejecución sin clave de firma.
Consulte ejecución con Docker para configurar la conexión de base de datos y el resto de opciones, y ejecución con Docker Compose para la variante con Compose.
Master estará disponible en http://localhost:2935 (o detrás de su Ingress en Kubernetes). Inicie sesión con la
cuenta de superadministrador.
2935 es el puerto predeterminado desde Axelix 1.2.0. Antes de esa versión, Master escuchaba en 8080.
Consulte general para conocer el motivo y cómo recuperar el puerto anterior.
Después, configúrelo. Master acepta configuración de muchas fuentes: variables de entorno, un archivo externo, un servidor Spring Cloud Config o HashiCorp Vault. Por ello, integrarlo en su proceso actual de configuración no debería resultar complicado. Consulte cómo proporcionar propiedades.
Los dos valores JWT de los ejemplos anteriores son axelix.master.auth.jwt.algorithm y
axelix.master.auth.jwt.signing-key; consulte autenticación — JWT.
Proteja la clave de firma desde el primer día: es el secreto compartido que todos los servicios gestionados presentarán después a Master.
Genere un valor aleatorio largo y guárdelo en su gestor de secretos, en lugar de incluirlo en un archivo versionado.
En Axelix 1.2.0 y posteriores
Ambos valores JWT son opcionales. Sin ellos, Master y los servicios utilizan una clave integrada, de modo que puede probar Axelix localmente sin generar una. Esa clave es pública, por lo que cualquiera puede utilizarla para iniciar sesión en Master y llamar a los endpoints de Axelix de los servicios. Utilícela solo en una prueba local y configure una clave propia en cualquier otro caso. Consulte ejecución sin clave de firma.
Además de la conexión de base de datos y la clave de firma, conviene tomar conscientemente dos decisiones en este paso:
- Modo de descubrimiento. Con descubrimiento automático, Master explora su entorno Kubernetes y comprueba los servicios que encuentra. Con autorregistro, cada servicio envía mensajes de actividad a Master. Ambos modos pueden combinarse: por ejemplo, descubrimiento automático para servicios del clúster y autorregistro para los que Master no puede explorar. Consulte cómo funciona el descubrimiento para conocer cada modo.
- Inicio de sesión y RBAC. Para equipos pequeños, probablemente basten los usuarios locales, cuyas cuentas almacena Master en su propia base de datos. En grandes organizaciones, OAuth2 / OIDC con su proveedor de identidad suele ser mejor opción. En ambos casos, la cuenta inicial de superadministrador permite acceder a la interfaz desde el primer día.
Paso 3 — Añadir el starter y el plugin de compilación a los servicios
A continuación, añada gradualmente los componentes cliente a los servicios que Master deba gestionar. Son dos y ambos son obligatorios: el starter de Spring Boot de Axelix correspondiente a la versión principal de Spring Boot del servicio y el plugin de compilación de Axelix para Maven o Gradle. Ambos se publican en Maven Central, por lo que añadirlos es un cambio normal de dependencias, sin repositorios privados. Axelix se versiona de forma coordinada: utilice la misma versión para Master, los starters y el plugin. Consulte compatibilidad y versiones para conocer la correspondencia entre starter y Boot y las reglas exactas de diferencias de versión.
Para un servicio Spring Boot 4, los cambios de compilación son los siguientes (sustituya 4 por 2 o 3 según la versión principal de Boot del servicio):
plugins {
id("com.axelixlabs.axelix") version "1.3.1"
}
dependencies {
implementation("com.axelixlabs:axelix-spring-boot-4-starter:1.3.1")
}Como el plugin aún no está en Gradle Plugin Portal, añada mavenCentral() a pluginManagement en
settings.gradle.kts. Consulte configuración del plugin de compilación.
Añadir las dependencias no basta. Cada servicio necesita además dos elementos de configuración, descritos
en detalle en la página de configuración del starter. En Axelix 1.2.0 y
posteriores, los endpoints de Actuator no necesitan configuración aquí: el starter los añade automáticamente a
management.endpoints.web.exposure.include; consulte endpoints de Actuator.
En versiones anteriores, exponerlos es un tercer elemento obligatorio de configuración; consulte el aviso situado después de los ejemplos.
- Establecer la clave JWT compartida del paso 2 en
axelix.sbs.auth.jwt.*. La falta de coincidencia entre Master y el servicio es la causa más habitual de respuestas401. Consulte compartir la clave JWT con Master y solución de problemas. En Axelix 1.2.0 y posteriores puede omitirla para una prueba local: el servicio utilizará la clave integrada; consulte ejecución sin clave de firma. - Configurar el descubrimiento, solo si eligió autorregistro. Dirija las propiedades
axelix.sbs.discovery.*a Master, como se muestra en permitir que Master encuentre la instancia. Con descubrimiento automático desde Master, no hay nada adicional que configurar en el servicio.
En conjunto, la configuración mínima del servicio:
axelix:
sbs:
auth:
jwt:
algorithm: HMAC512
signing-key: ${AXELIX_JWT_SIGNING_KEY}En Axelix anterior a 1.2.0
Los starters anteriores a 1.2.0 no añaden sus endpoints a management.endpoints.web.exposure.include, por lo que
en esas versiones la lista también forma parte de la configuración mínima. Master utiliza axelix-metadata para
detectar la instancia: sin él, el servicio nunca aparece, independientemente del modo de descubrimiento:
management:
endpoints:
web:
exposure:
include:
- axelix-metadata
- axelix-beans
- axelix-caches
- axelix-conditions
- axelix-configprops
- axelix-details
- axelix-env
- axelix-gc
- axelix-heap-dump
- axelix-loggers
- axelix-metrics
- axelix-scheduled-tasks
- axelix-thread-dumpEstas versiones del starter también incorporan el endpoint heredado axelix-feign. Se omite de la lista deliberadamente:
Master nunca lo consulta y se elimina en Axelix 1.3.0; consulte eliminación del endpoint axelix-feign.
Despliegue los cambios servicio por servicio. A medida que cada servicio se vuelva a desplegar en pruebas, aparecerá en el Master de pruebas y el equipo podrá empezar a utilizar la interfaz y MCP de inmediato.
Conviene prever un detalle relacionado con producción. Los servicios suelen promover el mismo artefacto desde pruebas a
producción, por lo que el starter llega a producción antes que Master. Si ese servicio tiene autorregistro activado,
seguirá intentando registrarse en un Master que aún no existe. Para esos servicios, establezca
axelix.sbs.enabled=false en la configuración de producción para mantener el starter inactivo; consulte desactivar el starter.
Paso 4 — Instalar Master en producción
Finalmente, cuando el despliegue de pruebas esté validado, lleve Axelix a producción. Repita los pasos 1 y 2 como despliegue independiente: base de datos propia, RBAC adecuado para producción y las reglas más estrictas de acceso de red a la interfaz y al servidor MCP que exige producción.
Una vez iniciado el Master de producción, elimine las sobrescrituras temporales axelix.sbs.enabled=false del paso 3 para que
las instancias de producción se registren y sean visibles.
Relacionado
- Qué es Master: contexto sobre lo que hace Master con los servicios gestionados.
- Configuración de Master: todas sus propiedades, formatos de distribución y fuentes de configuración.
- Configuración del starter de Spring Boot: integración detallada de un servicio.
- Configuración del plugin de compilación: el segundo componente cliente obligatorio.
- Autenticación: opciones de inicio de sesión, roles y permisos.
- Compatibilidad y versiones: qué starter corresponde a cada versión de Spring Boot y Java y cómo se mantiene la compatibilidad entre componentes.
- Solución de problemas: problemas habituales de instalación (respuestas
401, módulo de starter incorrecto o servicio que nunca se registra) y sus soluciones.
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.
Instalar con IA
Instalar Axelix en un servicio Spring Boot: el starter de Spring Boot de Axelix, el plugin de compilación de Axelix y, para una prueba local, el propio Axelix Master. Utilizar cuando el usuario pida instalar, añadir, configurar, probar o conectar Axelix.