Premiers pas
Cette page décrit la méthode recommandée pour déployer Axelix dans une organisation : les environnements par lesquels commencer, l’ordre d’installation des composants et la manière d’atteindre la production en toute sécurité. Chaque étape fournit les commandes concrètes et la configuration minimale, avec des liens vers la page de configuration détaillée pour consulter la référence complète.
Les extraits de cette page utilisent la version 1.3.1 à titre d’exemple. Consultez la page des
versions pour connaître le dernier tag publié et utilisez-le dans vos propres
commandes.
Axelix et vos environnements
Un cycle de développement logiciel type couvre plusieurs environnements. Quels que soient leurs noms exacts — dev, sandbox, QA, UAT, staging — chaque environnement appartient à l’une de deux catégories : production et hors production.
La première question que les équipes se posent donc généralement est la suivante : Axelix Master est-il censé s’exécuter en production ? Oui. Master est conçu pour s’exécuter à la fois en production et dans les environnements de test, du point de vue des performances, de la sécurité et de la tolérance aux pannes. L’exécution de Master en production est une pratique établie, et non une utilisation détournée.
Toutefois, nous vous recommandons vivement de séparer le déploiement de production d’Axelix de celui qui gère vos environnements de test. En d’autres termes : n’utilisez pas un Master unique pour gérer tous les environnements. Voici pourquoi :
- Le contrôle d’accès diffère. La configuration RBAC d’un environnement de test ne correspond presque certainement pas à celle de la production. La liste des personnes autorisées à modifier les niveaux de journalisation, à activer ou désactiver des caches ou à générer un heap dump en production est beaucoup plus courte que dans l’environnement de staging. Consultez Rôles et autorités.
- Les règles réseau diffèrent. Les règles déterminant qui peut accéder à l’interface utilisateur de Master et à son serveur MCP sont généralement beaucoup plus strictes en production que dans les environnements de test.
- Les politiques différeront. Les politiques d’Axelix Enterprise, actuellement en cours de développement, devraient également être propres à chaque environnement.
Chaque déploiement de Master peut indiquer l’environnement qu’il dessert via la propriété axelix.master.environment (par
exemple production ou staging). Aujourd’hui, cette étiquette alimente uniquement la journalisation
structurée, mais la définir dès le
premier jour permet à vos déploiements de se décrire eux-mêmes.
Avec cette séparation à l’esprit, l’adoption commence par les environnements de test. Ainsi, lorsque Axelix arrive en production, la configuration et les habitudes de votre équipe ont déjà fait leurs preuves.
Étape 1 — Préparer la base de données
Master nécessite une base de données relationnelle. Par défaut, il embarque SQLite et utilise
l’URL jdbc:sqlite:axelix.db, de sorte qu’une première exécution ne nécessite aucune configuration de base de données. Cette valeur par défaut
permet de démarrer rapidement.
Si vous ne souhaitez plus simplement expérimenter et voulez tirer réellement parti de l’installation, choisissez un moteur dans la liste des moteurs pris en charge : PostgreSQL, MySQL ou SQLite. Pour toute utilisation allant au-delà d’un essai sur un seul nœud, choisissez PostgreSQL ou MySQL : SQLite stocke les données dans un fichier local, qui ne survit donc pas aux redémarrages de conteneurs sans volume monté et ne peut pas prendre en charge plusieurs réplicas de Master. Nous prévoyons d’élargir la liste des moteurs pris en charge dans les futures versions.
Provisionnez la base de données et un utilisateur disposant des privilèges nécessaires aux migrations de schéma, car Master applique lui-même son schéma : Liquibase s’exécute à chaque démarrage et vous n’avez jamais à lancer les migrations manuellement ; consultez Migrations de base de données. La connexion se configure au moyen de trois propriétés décrites dans la section Base de données.
Une fois la base de données prête, passez à l’étape suivante.
Étape 2 — Installer Master dans un environnement de test
Installez d’abord Master dans un environnement de test (ou dans plusieurs, si vous conservez des déploiements Axelix distincts pour chaque environnement de test). Tous les formats de distribution conviennent ; choisissez celui qui correspond à votre infrastructure : un simple JAR, Docker, Docker Compose ou Kubernetes avec le chart Helm officiel. Voici le lancement minimal pour chacun :
L’image est publiée sur GitHub Container Registry. Les commandes ci-dessous utilisent la dernière version,
1.3.1 ; remplacez le tag pour exécuter une autre version :
docker run --rm -p 2935:2935 ghcr.io/axelixlabs/axelix:1.3.1Si aucune propriété JWT n’est définie, Master utilise la clé de signature intégrée. Réservez cette option à un essai local ; consultez Exécuter sans clé de signature.
Consultez Exécuter avec Docker pour fournir la connexion à la base de données et le reste de la configuration, et Exécuter avec Docker Compose pour la variante Compose.
Master est ensuite accessible à l’adresse http://localhost:2935 (ou derrière votre Ingress sur Kubernetes). Connectez-vous avec le compte
super-administrateur.
2935 est le port par défaut depuis Axelix 1.2.0. Avant cette version, Master écoutait sur le port 8080 ; consultez
Général pour connaître les raisons de ce changement et la marche à suivre pour rétablir l’ancien port.
Configurez ensuite Master. Il accepte une configuration provenant de nombreuses sources : variables d’environnement, fichier de configuration externe, Spring Cloud Config Server ou HashiCorp Vault. Son intégration à votre pipeline de configuration existant ne devrait donc pas poser de difficulté particulière. Consultez Fournir les propriétés.
Les deux valeurs JWT des extraits de lancement ci-dessus sont axelix.master.auth.jwt.algorithm et
axelix.master.auth.jwt.signing-key ; consultez Authentification — JWT. Protégez
soigneusement la clé de signature dès le premier jour : il s’agit du secret partagé que chaque service géré présentera ensuite à Master.
Générez donc une longue valeur aléatoire et conservez-la dans votre gestionnaire de secrets plutôt que dans un fichier suivi par Git.
À partir d’Axelix 1.2.0
Les deux valeurs JWT sont facultatives. Sans elles, Master et vos services utilisent une clé de signature intégrée, ce qui vous permet d’essayer Axelix localement sans en générer une. Cette clé est publiquement connue : n’importe qui peut donc l’utiliser pour se connecter à Master et appeler les endpoints Axelix de vos services. Réservez-la à un essai local et définissez votre propre clé partout ailleurs. Consultez Exécuter sans clé de signature.
Au-delà de la connexion à la base de données et de la clé de signature, deux décisions méritent d’être prises en connaissance de cause à cette étape :
- Mode de découverte. Avec l’ autodécouverte, Master analyse son environnement Kubernetes et interroge les services qu’il trouve. Avec l’ auto-enregistrement, chaque service envoie plutôt des signaux de présence à Master. Les deux modes peuvent être combinés, par exemple l’autodécouverte pour les services du cluster et l’auto-enregistrement pour les services que Master ne peut pas analyser. Consultez Fonctionnement de la découverte pour comprendre le comportement de chaque mode.
- Connexion et RBAC. Pour les petites équipes, les utilisateurs locaux, dont les comptes sont stockés par Master dans sa propre base de données, suffiront probablement. Pour les grandes organisations, OAuth2 / OIDC auprès de votre fournisseur d’identité constitue généralement la meilleure option. Dans tous les cas, le compte super-administrateur initial vous permet d’accéder à l’interface utilisateur dès le premier jour.
Étape 3 — Ajouter le starter et le plugin de build à vos services
Ajoutez ensuite progressivement les composants côté client aux services que Master doit gérer. Il y en a deux, et ils sont tous deux obligatoires : le starter Axelix Spring Boot correspondant à la version majeure de Spring Boot du service et le plugin de build Axelix pour Maven ou Gradle. Tous deux sont publiés sur Maven Central ; leur ajout constitue donc une simple modification de dépendances, sans référentiels privés. Axelix utilise une gestion synchrone des versions : utilisez la même version d’Axelix pour Master, les starters et le plugin de build. Consultez Compatibilité et gestion des versions pour connaître la correspondance entre les starters et Spring Boot ainsi que les règles précises en cas d’écart de versions.
Pour un service Spring Boot 4, les modifications du build se présentent comme suit (remplacez 4 par 2 ou 3 pour correspondre à la
version majeure de Spring Boot du service) :
plugins {
id("com.axelixlabs.axelix") version "1.3.1"
}
dependencies {
implementation("com.axelixlabs:axelix-spring-boot-4-starter:1.3.1")
}Comme le plugin n’est pas encore disponible sur le Gradle Plugin Portal, ajoutez mavenCentral() à pluginManagement dans votre
settings.gradle.kts ; consultez Configuration du plugin de build.
L’ajout des dépendances ne suffit pas. Chaque service nécessite également deux éléments de configuration, tous
décrits en détail sur la page de configuration du starter. Dans Axelix 1.2.0 et
les versions ultérieures, les endpoints actuator eux-mêmes ne nécessitent aucune configuration ici : le starter les ajoute automatiquement à
management.endpoints.web.exposure.include ; consultez Endpoints
actuator. Dans les versions plus anciennes, leur exposition constitue un troisième
élément de configuration obligatoire ; consultez la note située sous les extraits.
- Définissez la clé de signature JWT partagée de l’étape 2 sous
axelix.sbs.auth.jwt.*. Une incompatibilité de clé entre Master et le service est la cause la plus fréquente de réponses401; consultez Partager la clé de signature JWT avec Master et Résolution des problèmes. Dans Axelix 1.2.0 et les versions ultérieures, vous pouvez ignorer cette étape pour un essai local ; le service utilise alors la clé intégrée. Consultez Exécuter sans clé de signature. - Configurez la découverte, uniquement si vous avez choisi l’auto-enregistrement. Faites pointer les propriétés
axelix.sbs.discovery.*vers votre Master, comme indiqué dans Permettre à Master de trouver l’instance. Avec l’autodécouverte côté Master, aucune configuration supplémentaire n’est nécessaire dans le service.
Une fois ces éléments réunis, voici la configuration minimale du service :
axelix:
sbs:
auth:
jwt:
algorithm: HMAC512
signing-key: ${AXELIX_JWT_SIGNING_KEY}Versions d’Axelix antérieures à 1.2.0
Les starters antérieurs à la version 1.2.0 n’ajoutent pas eux-mêmes leurs endpoints à management.endpoints.web.exposure.include.
Dans ces versions, la liste des endpoints fait donc également partie de la configuration minimale. L’endpoint axelix-metadata est celui que
Master interroge pour détecter l’instance ; sans lui, le service n’apparaît jamais, quel que soit le mode de découverte :
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-dumpCes versions du starter fournissent également l’ancien endpoint axelix-feign. Il est volontairement exclu de la liste :
Master ne le lit jamais et cet endpoint est supprimé dans Axelix 1.3.0 ; consultez L’endpoint axelix-feign est
supprimé.
Déployez ces changements service par service. À mesure que chaque service est redéployé dans un environnement de test, il apparaît dans le Master de test et l’équipe peut immédiatement commencer à utiliser l’interface utilisateur et MCP avec lui.
Un détail lié à la production mérite d’être anticipé. Les services déploient généralement le même artefact successivement dans les environnements de test et
de production ; le starter arrive donc en production avant Master. Si un tel service s’exécute avec l’auto-enregistrement
activé, son starter continuera de tenter de s’enregistrer auprès d’un Master qui n’existe pas encore. Pour ces services, définissez
axelix.sbs.enabled=false dans la configuration de production afin de laisser le starter inactif ; consultez Désactiver le
starter.
Étape 4 — Installer Master en production
Enfin, lorsque le déploiement de test a fait ses preuves, déployez Axelix en production. Répétez les étapes 1 et 2 sous la forme d’un déploiement distinct : sa propre base de données, une configuration RBAC adaptée à la production et les règles d’accès réseau plus strictes à l’interface utilisateur et au serveur MCP qu’exige la production.
Une fois le Master de production opérationnel, supprimez tous les remplacements temporaires axelix.sbs.enabled=false de l’étape 3 afin que les
instances de production s’enregistrent et deviennent visibles.
Voir aussi
- Qu’est-ce que Master ? — informations générales sur ce que Master fait des services qu’il gère.
- Configuration de Master — toutes les propriétés de Master, les options de distribution et les sources de configuration.
- Configuration de Spring Boot Starter — connexion détaillée d’un service.
- Configuration du plugin de build — le second composant côté client obligatoire.
- Authentification — options de connexion, rôles et autorités.
- Compatibilité et gestion des versions — correspondance entre chaque starter et les versions de Spring Boot et de Java, et maintien de la compatibilité entre les versions des composants.
- Résolution des problèmes — les problèmes d’installation les plus courants (réponses
401, mauvais module de starter, service qui ne s’enregistre jamais) et leurs solutions.
Fonctionnement de la découverte
Découvrez comment Axelix Master identifie les instances Spring Boot existantes et maintient leur état à jour, soit en les recherchant lui-même dans Kubernetes, soit en permettant à chaque instance de s’enregistrer.
Installer avec l’IA
Installer Axelix dans un service Spring Boot : le starter Spring Boot Axelix, le plugin de build Axelix et, pour un essai local, Axelix Master lui-même. À utiliser lorsque l’utilisateur demande d’installer, d’ajouter, de configurer, d’essayer ou de connecter Axelix.