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 :

  1. 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.
  2. 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.
  3. 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.1

Si 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) :

build.gradle.kts
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éponses 401 ; 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-dump

Ces 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

Sur cette page

Modifier sur GitHubSignaler un problème