ConnexionPlanifier un briefing

Chapitre 2.7

Installer l'édition Enterprise et appliquer une licence

Ce qui change lors de l'installation de l'édition Enterprise, comment demander une licence depuis votre compte Adverant, les trois façons de l'importer avec chaque code de refus, et comment Harrow Port Authority a migré son pilote Community vers Enterprise sur place sans rien perdre.

Cette page a été traduite par l'IA à partir de l'original en anglais. En cas de doute, la page en anglais fait foi. Lire cette page en anglais

17 minutes de lecture

Une installation Enterprise comporte deux moitiés, et elles arrivent par des chemins différents. Les images Enterprise sont fournies avec le chart Enterprise, récupérées à l'aide d'un jeton de tirage. La licence se présente sous la forme d'un fichier signé provenant de votre compte Adverant, que vous importez dans l'installation en cours d'exécution. Aucune des deux moitiés ne fonctionne sans l'autre : des images sans licence fonctionnent au niveau plancher Community, et une licence sans images Enterprise n'a rien à activer.

À la Harrow Port Authority, nous avons procédé dans cet ordre, six semaines après le pilote Community du chapitre 2.6, Installer Community sur Kubernetes. La mise à niveau vers le chart Enterprise a pris une fenêtre de maintenance ; l'importation de la licence a pris deux minutes. Ce chapitre couvre les deux moitiés. Il commence par une nouvelle installation et se termine par le passage sur place d'une installation Community existante.

Deux voies parallèles alimentant un encadré à droite intitulé « Installation Enterprise ». Voie supérieure : « Compte Adverant : Téléchargements » mène à « Chart Enterprise et son verrou d'images », puis à « helm install ou helm upgrade, edition: enterprise », auquel est rattaché un encadré latéral « jeton de tirage sur chaque nœud ». Voie inférieure : « Compte Adverant : Déploiements » mène à « fichier de licence signé », puis à « importation dans l'installation en cours d'exécution ». Les deux voies se rejoignent au niveau de l'encadré de droite. En dessous, une légende indique « les images sans licence fonctionnent au niveau plancher Community ».
Les deux moitiés d'une installation Enterprise et la provenance de chacune.

Ce qui diffère de l'édition Community

Deux valeurs, et le chart qui les lit.

# harrow-values.yaml (Helm values, Enterprise: only these two keys change)
edition: enterprise
enterprise:
  enabled: true

Tout le reste du fichier de valeurs demeure exactement tel quel, le nom de l'installation et les dépositaires avant tout. Les deux clés doivent concorder, et le chart refuse edition: enterprise avec enterprise.enabled: false, ou l'inverse.

L'édition doit également concorder avec le verrou d'images du chart. Chaque paquet de chart porte le verrou d'une seule édition, et le verrou Enterprise répertorie les images Community ainsi que les moutures Enterprise. Si vous pointez un fichier de valeurs Enterprise vers le chart Community, le rendu s'arrête avec files/images.lock.json is the community lock; this install is edition enterprise. L'installation Enterprise nécessite donc le chart Enterprise.

Le chart et le bundle Enterprise se trouvent sur la page Téléchargements de votre compte Adverant, qui dépend de votre licence. Le fichier du chart porte le même nom que celui de l'édition Community, nexus-1.0.0-alpha.1.tgz ; conservez-les donc dans des dossiers séparés. Vérifiez-le exactement comme le décrit le chapitre 2.4, Obtenir et vérifier une version, à l'aide de la clé de publication dont vous avez contrôlé l'empreinte :

nexusctl verify enterprise/nexus-1.0.0-alpha.1.tgz
tar -xzf enterprise/nexus-1.0.0-alpha.1.tgz -C enterprise
jq -r '.version, .edition' enterprise/nexus/files/images.lock.json
1.0.0-alpha.1
enterprise

Exécutez ensuite la boucle de signature du chapitre 2.4, Obtenir et vérifier une version, sur enterprise/nexus/files/images.lock.json. Elle couvre les images Enterprise aussi bien que les images partagées.

Le jeton de tirage

Les images Community sont publiques. Les images Enterprise nécessitent un jeton de tirage issu de la page Jetons de tirage et commandes d'installation de votre compte, configuré pour l'environnement d'exécution de conteneurs de vos nœuds comme l'indique l'étape 3 du chapitre 2.4, Obtenir et vérifier une version. Sur k3s, il s'agit d'une entrée configs pour registry.adverant.ai dans /etc/rancher/k3s/registries.yaml sur chaque nœud.

Créez un jeton par cluster et donnez-lui une date d'expiration que vous remarquerez. Lorsqu'un jeton arrive à expiration, les pods en cours d'exécution continuent de tourner, mais un pod reprogrammé sur un nœud qui ne possède pas encore l'image ne peut pas la tirer. Nous avons inscrit la date d'expiration du jeton dans le même calendrier que celle du certificat.

Une nouvelle installation Enterprise

Si vous installez Enterprise dès le départ, suivez le chapitre 2.6, Installer Community sur Kubernetes, étape par étape, avec trois différences :

  1. Placez le jeton de tirage sur chaque nœud avant l'étape 6.

  2. Utilisez les valeurs Enterprise (les deux clés ci-dessus) à l'étape 4.

  3. À l'étape 6, installez à partir du fichier de chart Enterprise que vous avez téléchargé :

    helm install nexus enterprise/nexus-1.0.0-alpha.1.tgz \
      --namespace nexus -f harrow-values.yaml --timeout 45m

Tout ce qui suit la commande d'installation est identique au chapitre 2.6, Installer Community sur Kubernetes, tout comme la règle concernant --wait : ne l'utilisez pas. Si vous installez plutôt avec nexusctl, ajoutez --edition enterprise à la commande :

nexusctl install --context harrow-prod --values harrow-values.yaml --edition enterprise

Lorsque toutes les charges de travail sont prêtes, effectuez le premier démarrage décrit au chapitre 2.12, Le premier démarrage. La licence fait partie des six éléments que la console répertorie avant que quiconque ne se connecte. Tant qu'elle n'est pas importée, l'installation fonctionne au niveau plancher Community et chaque zone Enterprise apparaît grisée avec un cadenas.

Demander la licence

Une licence d'Adverant est émise pour l'identité d'une seule installation, celle que le magasin de clés a forgée sous keys.installationName lors de l'installation. Le compte doit donc savoir de quelle installation il s'agit avant de pouvoir en émettre une.

  1. Connectez-vous à votre compte Adverant à l'adresse https://account.adverant.ai.
  2. Sur l'installation, ouvrez Cette installation, puis Licence. Un code à usage unique et l'empreinte de l'installation s'affichent.
  3. Dans votre compte, ouvrez Revendiquer un déploiement et saisissez le code. Comparez ensuite l'empreinte reçue par le compte avec celle qu'affiche l'installation, groupe par groupe ; chaque groupe doit correspondre.
  4. Appuyez sur le bouton de revendication. L'installation rejoint la section Déploiements de votre compte, avec sa version et l'état de sa licence.
  5. Adverant émet la licence pour cette installation. Téléchargez le fichier depuis votre compte ; il porte le nom de son identifiant de licence, <licence-id>.json.

Un code de revendication ne fonctionne qu'une seule fois et pendant une courte durée. S'il expire, le compte le refuse avec CLAIM_CODE_EXPIRED, et l'installation en affiche un nouveau.

Revendiquer un déploiement
Revendiquer un déploiement
Revendication d'un déploiement dans le compte Adverant. Le code à usage unique est saisi en premier, puis l'empreinte est comparée par groupes de quatre, afin que personne ne puisse revendiquer une installation devant laquelle il ne se trouve pas.

Deux autres voies existent, et le chapitre 2.13, Licences, les couvre toutes deux en détail. Les appliances et les kits périphériques n'ont pas d'écran pour afficher un code ; ils sont donc revendiqués à l'aide d'une clé de revendication imprimée sur le boîtier, saisie dans Saisir une clé de revendication ou lue à partir du fichier de commande du fabricant. Une installation sans accès sortant utilise l'Échange hors ligne : elle produit un fichier de demande de licence signé, vous le transportez jusqu'à votre compte, puis vous rapportez le fichier de licence. Une fois par an, elle produit de la même manière un relevé d'utilisation signé. Chaque fichier de l'échange est signé, de sorte qu'un fichier modifié en chemin est refusé, avec LICENCE_REQUEST_SIGNATURE_INVALID pour une demande et USAGE_FILE_SIGNATURE_INVALID pour un fichier d'utilisation.

Échange hors ligne
Échange hors ligne
L'échange hors ligne dans le compte Adverant. Les fichiers signés voyagent manuellement dans les deux sens, et un fichier modifié en chemin est explicitement refusé.

Ce que contient le fichier de licence

La licence est un document JSON au format nexus-licence/v1, signé deux fois par Adverant avec deux clés indépendantes. Vous n'avez pas besoin de le lire, mais il est utile de savoir ce qu'il contient lorsqu'on vous demande ce que vous avez acheté.

Champ Ce qu'il indique
licence_id L'identifiant propre de la licence, un UUID (identifiant unique universel) en minuscules
type alpha, evaluation ou commercial
licensee Le nom de l'organisation et l'identifiant client Adverant
scope L'installation concernée, ainsi que toutes les organisations désignées par une attribution
edition enterprise
grants Les groupes de fonctionnalités qu'elle déverrouille, chacun pour l'ensemble de l'installation ou pour des organisations nommées
add_ons et domain_packs Les capacités sous licence séparée ; le pack Logistique et maritime en est un exemple
metric Le mode de décompte de la licence, named-seat, per-core ou per-environment, ainsi que la quantité
term starts_on, ends_on, ainsi que les jours d'avertissement et de grâce
matrix La version de la matrice d'édition pour laquelle elle a été rédigée
signatures Les deux signatures d'Adverant

Une licence d'évaluation dure au maximum 30 jours, pour cinq personnes nommées au plus, sans période de grâce. Une licence commerciale émet un avertissement 30 jours avant son échéance, puis accorde par défaut 30 jours de grâce. Ce qui se passe à chaque échelon est détaillé au chapitre 2.13, Licences.

Les signatures couvrent le document tel qu'Adverant l'a généré. Transmettez-le exactement tel que vous l'avez reçu ; ne l'ouvrez pas dans un éditeur susceptible de le reformater.

Importer la licence

Seul un administrateur de l'installation peut importer une licence : un propriétaire ou un administrateur de l'organisation globale qui détient l'installation, lorsqu'il y est connecté. Un administrateur complet de la plateforme peut également en importer une. La licence n'est jamais une valeur de chart ni un fichier monté dans un pod. Elle est envoyée au service de connexion, nexus-auth, qui la vérifie hors ligne par rapport aux racines de confiance intégrées à sa propre image et l'enregistre en une seule transaction. Vous pouvez l'importer de trois manières, qui aboutissent toutes au même endroit.

Dans la console

Lors du premier démarrage, ouvrez Six éléments avant que quiconque ne se connecte, puis Licence. La page Importer la licence accepte le fichier : déposez-le sur la page ou sélectionnez-le. La page le vérifie hors ligne sur l'installation elle-même, puis répertorie les groupes de fonctionnalités qu'il ouvre, en précisant comment chacun est protégé et jusqu'à quand. Les groupes que la licence n'inclut pas restent affichés, mais grisés.

Par la suite, cette même importation s'effectue via le bouton Importer une nouvelle licence sur la page de licence de l'installation. Lorsqu'une licence a expiré, la page de licence restreinte propose Importer une licence renouvelée.

Importer la licence
Importer la licence
Importation de la licence dans la console. Le fichier est vérifié sur l'installation elle-même ; la page répertorie ce qu'il déverrouille par groupe de fonctionnalités, et un fichier qui échoue à la vérification de signature est traité comme absent, avec son code.

Avec nexusctl

nexusctl licence import <licence-id>.json

nexusctl envoie le fichier, sans modification, à la route d'importation de l'installation en tant qu'administrateur de l'installation, et renvoie l'état de la licence ou le code de refus figurant dans le tableau ci-dessous.

Via l'API

La route d'importation fait partie de l'interface de programmation d'application (API) du service de connexion, à votre adresse hosts.auth. Le corps de la requête est le document de licence, octet par octet :

curl -sS -X POST https://auth.harrow.example/api/v1/installation/licence \
  -H "authorization: Bearer <admin-token>" \
  -H "content-type: application/json" \
  --data-binary @<licence-id>.json

<admin-token> est le jeton d'accès d'un administrateur de l'installation connecté. Utilisez --data-binary, jamais -d, qui supprime les sauts de ligne et modifie ainsi les octets envoyés. La route n'accepte aucune chaîne de requête et rien d'autre dans le corps que le document ; un corps qui tente de nommer une organisation ou une personne à son niveau supérieur est refusé avant toute lecture.

Une importation réussie répond 201 Created. En version abrégée, le corps ressemble à ceci :

{
  "licence": {
    "licence_id": "<licence-id>",
    "state": "licensed",
    "edition": "enterprise",
    "licensee": {"name": "Harrow Port Authority", "customer_id": "<customer-id>"},
    "term": {"starts_on": "2026-12-01", "ends_on": "2027-11-30", "warn_days": 30, "grace_days": 30},
    "groups": ["enterprise-base", "..."]
  },
  "organizations": 1,
  "tenants_without_organisation": 0
}

organizations compte les organisations présentes sur l'installation qui détiennent désormais la licence. tenants_without_organisation compte les organisations nommées par la licence mais que cette installation ne détient pas.

Lorsque l'importation est refusée

Une importation refusée ne modifie rien : aucune ligne n'est écrite et la licence en vigueur, s'il y en a une, reste inchangée. Le journal d'audit de l'installation enregistre chaque tentative, y compris celles qui sont refusées.

Code Statut Ce que cela signifie Que faire
LICENCE_SIGNATURE_INVALID 422 L'une des deux signatures d'Adverant est manquante ou échoue à la vérification ; le fichier a été modifié après sa signature Redemandez le fichier à Adverant ; ne le modifiez pas
LICENCE_FORMAT_INVALID 422 Le fichier n'est pas une licence que cette version peut lire Envoyez le fichier exactement tel qu'Adverant vous l'a fourni
LICENCE_ROOT_UNKNOWN 422 Elle est signée avec une clé à laquelle cette installation ne fait pas confiance Demandez une licence signée pour les racines de confiance de cette version, ou effectuez une mise à niveau
LICENCE_MATRIX_MISMATCH 422 Elle est rédigée pour une matrice d'édition que cette version ne lit pas, ou accorde un groupe que cette version ne connaît pas Effectuez une mise à niveau, ou demandez une licence rédigée pour cette version
LICENCE_OTHER_INSTALLATION 409 Elle a été émise pour une autre installation Demandez une licence émise pour l'identité de cette installation
TRANSITION_NOT_PERMITTED 409 Une licence portant cet identifiant a déjà été importée ; chacune ne s'importe qu'une seule fois Demandez une nouvelle licence à Adverant si les conditions doivent changer
LICENCE_REVOKED 403 Adverant a retiré cette licence Demandez-en une nouvelle à Adverant
LICENCE_LOCKED 403 La période de validité de la licence n'a pas commencé ; le niveau plancher Community s'applique jusque-là Importez-la à nouveau à partir de son premier jour de validité
RECORD_NOT_FOUND 404 L'installation n'a pas encore été déclarée ; elle n'a donc aucune identité à vérifier Terminez l'étape du premier administrateur (chapitre 2.12, Le premier démarrage), puis importez
VALIDATION_FAILED 400 Le corps était illisible ou dépassait 1 MiB, ou une chaîne de requête a été envoyée Envoyez le fichier comme seul corps de la requête, sans chaîne de requête

Un autre code peut être renvoyé lors d'une importation réussie, à titre d'avis plutôt que de refus : LICENCE_CLOCK_BEHIND_FLOOR signifie que l'horloge de l'installation indique une heure antérieure à l'heure la plus récente qu'elle a déjà enregistrée, de sorte que la licence est évaluée à cette heure ultérieure. Reculer une horloge ne réactive jamais une licence expirée. Seul un jeton de réinitialisation de l'heure signé par Adverant pour l'installation permet d'abaisser ce seuil temporel.

Migrer de Community vers Enterprise sur place

C'est ce que nous avons fait à Harrow. Rien n'est réinstallé et rien n'est migré : il s'agit de la même installation, avec la même identité et les mêmes données, avec simplement davantage de fonctionnalités activées. Le nom de l'installation et les dépositaires restent exactement tels qu'ils étaient ; lors d'une mise à niveau, le hook de garde vérifie que le magasin de clés est déjà initialisé et ne fait rien d'autre.

  1. Placez le jeton de tirage sur chaque nœud, puis redémarrez-y l'environnement d'exécution de conteneurs.

  2. Récupérez le chart Enterprise depuis la page Téléchargements et vérifiez-le ainsi que ses images comme indiqué ci-dessus.

  3. Modifiez les deux valeurs dans votre fichier de valeurs existant : edition: enterprise et enterprise.enabled: true. Ne modifiez rien d'autre.

  4. Exécutez les vérifications préalables avec le nouveau fichier.

    nexusctl preflight --context harrow-prod --values harrow-values.yaml
  5. Mettez à niveau la version vers le chart Enterprise, là encore sans --wait.

    helm upgrade nexus enterprise/nexus-1.0.0-alpha.1.tgz \
      --namespace nexus -f harrow-values.yaml --timeout 45m

    Lors d'une mise à niveau, les hooks s'exécutent avant le déploiement des nouveaux pods, et chaque migration n'applique que les fichiers qu'elle n'a pas encore appliqués. Les secrets générés sont relus depuis l'installation et conservés. Helm se termine par :

    NAME: nexus
    NAMESPACE: nexus
    STATUS: deployed
    REVISION: 2
  6. Attendez que les charges de travail soient prêtes, exactement comme à l'étape 7 du chapitre 2.6, Installer Community sur Kubernetes.

    kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900s
  7. Importez la licence, par l'une des trois méthodes ci-dessus.

  8. Dans la console, ouvrez Cette installation, puis Licence, puis Passer à Enterprise. La page lit la licence et indique ce qui sera récupéré et ce qui changera avant que quoi que ce soit ne se produise. Elle compte également les personnes et les contenus de l'organisation et marque chacun d'eux comme conservé. Appuyez sur Récupérer et activer. Chaque élément est vérifié à l'aide de la clé de publication d'Adverant avant d'être utilisé, et les groupes de fonctionnalités s'activent un par un.

Notre fenêtre était d'une heure ; le travail en lui-même a pris environ vingt minutes, principalement consacré à l'attente du schéma pendant l'exécution des hooks. Les participants au pilote se sont connectés le lendemain matin au même espace de travail, où les zones Enterprise du menu n'étaient plus grisées.

De Community à Enterprise
De Community à Enterprise
Passage d'une installation Community à Enterprise. La page confirme l'authenticité de la licence et répertorie ce qui sera récupéré avant toute récupération ; les personnes et les fichiers de l'organisation sont marqués comme conservés.

Après l'importation

La page de licence sous Cette installation répertorie chaque groupe de fonctionnalités de la licence avec ses postes et sa période de validité. Elle indique également le mode de fourniture de chaque partie, par exemple compilée et sous licence pour un groupe Enterprise, ou open source pour le niveau plancher Community. Les groupes hors licence restent affichés, mais grisés. Les administrateurs peuvent restreindre la portée d'un groupe au sein de l'organisation ; personne d'autre qu'Adverant ne peut élargir ce qu'accorde une licence.

L'état de la licence est recalculé à partir du document et de la date à chaque lecture ; l'expiration intervient donc sans tâche planifiée. Toutes les personnes présentes sur l'installation voient le même avis dans la console à mesure que l'échéance approche : LICENCE_ENDS_SOON à partir de 30 jours avant la fin, puis LICENCE_IN_GRACE pendant la période de grâce. Les membres voient l'avis et les dates ; seuls les administrateurs de l'installation voient la licence elle-même. Le chapitre 2.13, Licences, couvre le renouvellement et les échelons d'expiration.

La licence et ce qu'elle débloque
La licence et ce qu'elle débloque
Voici la page de licence d'une installation Enterprise. Les chiffres en haut indiquent les postes et la période de validité ; en dessous, chaque groupe de fonctionnalités est répertorié avec son mode de protection, et les groupes hors licence restent grisés.

En cas d'échec

Ce que vous voyez Cause Que faire
edition=enterprise but enterprise.enabled=false: they must agree Une seule des deux clés a été modifiée Modifiez les deux
files/images.lock.json is the community lock; this install is edition enterprise Le chart Community a été utilisé Utilisez le chart Enterprise depuis la page Téléchargements
image ... is a enterprise image; a community install takes only community images Un nom d'image Enterprise a atteint un rendu Community Vérifiez edition et le dossier du chart
ImagePullBackOff sur une image Enterprise après la mise à niveau Un nœud n'a pas de jeton de tirage, ou son jeton n'est plus valide Vérifiez registries.yaml sur ce nœud, ou créez un nouveau jeton
Un code de refus de licence Consultez le tableau des refus ci-dessus Suivez la ligne correspondante ; rien n'a été modifié

Lorsque la page de licence affiche Enterprise ainsi que les groupes attendus, l'installation est sous licence. L'étape suivante est le premier démarrage décrit au chapitre 2.12, Le premier démarrage, si vous n'avez pas encore revendiqué l'installation. Si vous l'avez fait, l'assistant a encore besoin des clés de modèles d'intelligence artificielle (IA) propres à l'organisation avant de pouvoir répondre à quiconque. Le chapitre 2.14, Fournisseurs et modèles d'IA, explique comment les connecter.