Version 1.0.0-alpha.1dernière version
Chapitre 2.4
Obtenir et vérifier une version
Où réside chaque composant d'une version de Nexus, comment récupérer les images Enterprise avec un jeton de tirage, et comment prouver hors ligne que chaque image, chart et téléchargement provient bien d'Adverant sans altération, avant d'installer quoi que ce soit.
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

Chaque image d'une version de Nexus est signée par la clé de publication d'Adverant, et chaque image est désignée par son condensat (digest), jamais par une étiquette (tag). Le chart ne générera que les images répertoriées par leur condensat dans son propre fichier de verrouillage des images. Mis bout à bout, cela signifie que vous pouvez prouver, depuis votre propre poste de travail et sans aucune connexion à qui que ce soit, que ce que vous vous apprêtez à exécuter correspond exactement à ce qu'Adverant a compilé.
Chez Harrow Port Authority, nous avons tout vérifié avant la première installation. Cela a pris une vingtaine de minutes, dont la majeure partie a été consacrée à la boucle de vérification des images. Ce chapitre suit le même cheminement : où se trouve chaque élément de la version, le jeton de téléchargement (pull token) pour les images Enterprise, le fichier de verrouillage des images, les vérifications cosign avec leurs commandes exactes, et la marche à suivre lorsqu'une vérification échoue.
Où réside la version
| Adresse | Ce que vous y récupérez |
|---|---|
registry.adverant.ai |
Les images de la plateforme, sur registry.adverant.ai/nexus/<service>@sha256:<digest>, et le chart Helm, sur oci://registry.adverant.ai/nexus/charts/nexus |
https://downloads.adverant.ai/nexus/1.0.0-alpha.1/ |
La clé publique de publication et son empreinte, les binaires nexusctl et les archives hors ligne (bundles) |
https://account.adverant.ai |
Votre compte Adverant : Téléchargements, Jetons de téléchargement et commandes d'installation, Déploiements et les pages de licence |
Les images Community et le chart Community sont publics ; vous pouvez les récupérer sans vous connecter. Les images Enterprise se récupèrent à l'aide d'un jeton de téléchargement issu de votre compte, et le chart ainsi que l'archive Enterprise se trouvent sur la page Téléchargements du compte, qui dépend de votre licence.
Lire les notes de version avant toute chose
Les notes de version sont fournies dans chaque archive sous le nom docs/RELEASE-NOTES.md, répertoriées dans son fichier SHA256SUMS, et ces mêmes notes figurent sur la page de la version dans votre compte. Lisez-les avant toute installation ou mise à niveau. Pour la version 1.0.0-alpha.1, elles sont courtes. Il s'agit de la toute première version ; une nouvelle installation n'est donc concernée par aucun des points de mise à niveau qui y sont décrits, et la liste des problèmes connus précise qu'aucun d'entre eux n'affecte une nouvelle installation qui suit les étapes documentées. Les versions ultérieures répertorient chaque problème connu avec la version qui le corrige.
La page de la version indique également, en trois lignes, ce que garantit une version alpha : les fonctionnalités peuvent évoluer avant la première version stable, une mise à niveau conserve vos données et effectue une sauvegarde préalable, et les correctifs de sécurité sont publiés sous 7 jours. À Harrow, nous avons imprimé cette page et l'avons jointe au dossier de changement, car c'est ce qui se rapproche le plus de l'engagement de support que le comité des changements était susceptible de demander.
Étape 1 : obtenir la clé de version et la vérifier par un second canal
Tout ce qui suit repose sur un seul fichier : la clé publique de publication d'Adverant. Une clé provenant du même endroit que l'élément qu'elle certifie ne prouve pas grand-chose ; vérifiez donc son empreinte en la comparant à une copie qui vous est parvenue par un autre canal.
Téléchargez la clé depuis le dossier de la version sur la page Téléchargements.
curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/release.pubCalculez son empreinte. L'empreinte correspond au hachage SHA-256 (Secure Hash Algorithm 256) du fichier de clé lui-même.
sha256sum release.pubSous macOS,
shasum -a 256 release.pubdonne le même résultat.Comparez-la, caractère par caractère, avec l'empreinte imprimée dans votre contrat avec Adverant et dans les notes de version. La page Téléchargements publie également l'empreinte, mais cette copie a emprunté le même chemin que la clé ; elle ne constitue donc pas une vérification valable.
Si le moindre caractère diffère, arrêtez tout. Ne procédez pas à l'installation et ne cherchez pas une autre copie de la clé sur Internet. Ouvrez une demande de support depuis votre compte en indiquant ce que vous avez constaté.
Étape 2 : obtenir nexusctl
nexusctl est l'interface en ligne de commande (CLI) de l'opérateur Nexus. Elle s'exécute sur votre poste de travail et interroge votre cluster via votre fichier kubeconfig. La page Téléchargements propose quatre versions compilées :
| Fichier | Plateforme |
|---|---|
nexusctl-linux-amd64 |
Linux sur Intel ou AMD |
nexusctl-darwin-arm64 |
macOS sur Apple silicon |
nexusctl-darwin-amd64 |
macOS sur Intel |
nexusctl-windows-amd64.exe |
Windows |
À côté de chaque fichier se trouve son lot de signature, portant le même nom suivi de l'extension .sigstore.json. Vérifiez le binaire avant de l'exécuter :
curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/nexusctl-linux-amd64
curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/nexusctl-linux-amd64.sigstore.json
cosign verify-blob --key release.pub --insecure-ignore-tlog=true \
--bundle nexusctl-linux-amd64.sigstore.json nexusctl-linux-amd64Verified OK
Placez-le ensuite dans votre variable PATH et vérifiez sa version :
install -m 0755 nexusctl-linux-amd64 /usr/local/bin/nexusctl
nexusctl versionÀ partir de là, nexusctl verify peut effectuer les vérifications de fichiers à votre place. Le chapitre 2.5, Vérifications préalables avec nexusctl, aborde sa fonction principale : les contrôles préalables (preflight).
Pourquoi l'option mentionne « insecure »
Chaque commande cosign de ce chapitre comporte l'option --insecure-ignore-tlog=true. Les versions de Nexus sont signées avec la clé d'Adverant et ne sont inscrites dans aucun journal de transparence public, de sorte que la vérification d'une version ne nécessite jamais de connexion à un tiers, y compris Sigstore. Par défaut, cosign exige une entrée dans un journal ; cette option lui indique de se fier uniquement à la clé. Sans elle, la vérification échoue de la manière suivante :
Error: not enough verified log entries from transparency log: 0 < 1
Lorsque l'option est définie, cosign affiche tout de même la phrase « Existence of the claims in the transparency log was verified offline ». Il s'agit d'une formulation figée dans cosign ; il n'y a aucune entrée de journal derrière cela. La vérification de la signature à l'aide de la clé est bien réelle, et c'est la seule partie qui compte.
Étape 3 : un jeton de tirage, pour Enterprise
Les images Enterprise sont protégées par un jeton de téléchargement. Vous pouvez en générer un dans votre compte, sur la page Jetons de téléchargement et commandes d'installation :
- Cliquez sur Ajouter un jeton.
- Indiquez à quel cluster il est destiné, ce qu'il est autorisé à récupérer et sa date d'expiration.
- Cliquez sur Copier le jeton et collez-le immédiatement à l'endroit où vous conservez vos identifiants, car la page ne l'affiche qu'une seule fois.
Chaque jeton est limité aux éléments qu'il est autorisé à récupérer et possède une date d'expiration. La révocation d'un jeton bloque immédiatement les nouveaux téléchargements ; les images qu'un cluster a déjà récupérées continuent de fonctionner. À Harrow, nous avons créé un jeton par cluster, de sorte que la révocation du jeton du cluster de test n'affecte jamais la production. Une installation Community ne nécessite aucun jeton ; vous n'en créez un que lorsque vous passez à l'édition Enterprise, et vous pouvez le faire le jour même.
Le chart ne comporte pas de valeur pour un secret de téléchargement (pull-secret). Ce sont vos nœuds qui récupèrent les images ; le jeton appartient donc à l'environnement d'exécution de conteneurs (container runtime) des nœuds. Sous k3s, ajoutez le registre au fichier /etc/rancher/k3s/registries.yaml sur chaque nœud et redémarrez-y k3s :
# /etc/rancher/k3s/registries.yaml (on every node)
configs:
"registry.adverant.ai":
auth: {username: "<registry-user>", password: "<pull-token>"}<registry-user> correspond au nom d'utilisateur du registre figurant dans votre invitation Adverant, et <pull-token> est le jeton que vous avez copié. Ce fichier contenant un identifiant d'accès, assurez-vous qu'il ne soit lisible que par l'utilisateur root.
Sur un cluster géré dont les nœuds ne lisent pas ce fichier, copiez les images dans un registre auquel vos nœuds font déjà confiance et définissez global.imageRegistry sur ce dernier ; chaque nœud doit approuver le certificat TLS (Transport Layer Security) de ce registre. Le chapitre 2.11, Variantes : magasins de données externes, TLS et ingress, traite de ce sujet, et le chapitre 2.10, Installation en environnement isolé (air-gap), aborde cette même copie pour un site sans accès externe.
Étape 4 : lire le fichier de verrouillage des images
Un chart Nexus ne désigne jamais une image par une étiquette (tag). Il désigne chacune d'elles par le condensat (digest) de son index multiplateforme, extrait du fichier de verrouillage des images, un fichier inclus dans le chart sous le nom files/images.lock.json. L'archive hors ligne contient ce même fichier de verrouillage sous le nom release/images.lock.json.
Récupérez le chart et décompressez-le pour lire le fichier de verrouillage :
helm pull oci://registry.adverant.ai/nexus/charts/nexus --version 1.0.0-alpha.1
tar -xzf nexus-1.0.0-alpha.1.tgz
jq -r '.version, .edition' nexus/files/images.lock.json1.0.0-alpha.1
community
La racine du fichier de verrouillage indique à quelle version et à quelle édition il appartient. Chaque entrée sous images décrit une image :
| Champ | Contenu |
|---|---|
svc |
Le service, tel que nexus-auth ou nexus-postgres |
index |
Le condensat sha256: de l'index de l'image, qui couvre à la fois linux/amd64 et linux/arm64 |
edition |
community, enterprise ou all pour la couche de données |
kind |
service, migrations ou data-tier pour les cinq magasins de données et OpenBao |
verified |
L'horodatage de la vérification de sa signature et de ses attestations lors de la compilation de la version |
Le chart génère chaque référence d'image sous la forme <global.imageRegistry>/nexus/<svc>@<index>. Ainsi, avec global.imageRegistry: registry.adverant.ai, le service de connexion correspond à registry.adverant.ai/nexus/nexus-auth@sha256: suivi de 64 caractères hexadécimaux, et aucun élément du cluster ne peut le remplacer par autre chose portant le même nom.
Le fichier de verrouillage est propre à chaque édition. Un fichier de verrouillage Community ne répertorie que les images dont l'édition est community ou all. Un fichier de verrouillage Enterprise répertorie celles-ci ainsi que les compilations Enterprise. Le chart vérifie cela à chaque génération de modèle et refuse de continuer plutôt que de deviner :
| Message du chart | Pourquoi |
|---|---|
edition=enterprise but enterprise.enabled=false: they must agree |
Les deux valeurs d'édition dans votre fichier de valeurs ne concordent pas |
files/images.lock.json is the community lock; this install is edition enterprise |
Vous installez l'édition Enterprise à partir du chart Community, ou inversement |
image nexus-auth is not in files/images.lock.json |
Le chart et son fichier de verrouillage ne correspondent pas ; récupérez à nouveau le chart |
image ... is in the lock but was never verified by build-all |
L'entrée du fichier de verrouillage ne comporte pas d'horodatage de vérification ; n'effectuez pas d'installation à partir de celui-ci |
NEXUS_EDITION_INVALID |
edition est vide ou ne correspond ni à community ni à enterprise |
RELEASE_VERSION_MISSING |
Le fichier de verrouillage ne mentionne aucune version |
Listez l'ensemble des images et de leurs condensats en une seule fois :
jq -r '.images[] | "\(.svc) \(.index)"' nexus/files/images.lock.jsonÉtape 5 : vérifier la signature de chaque image
Chaque index d'image est signé, tout comme chaque manifeste de plateforme qu'il contient. Effectuez la vérification par condensat, directement à partir du fichier de verrouillage, afin de contrôler exactement ce que le chart exécutera :
jq -r '.images[] | "\(.svc)@\(.index)"' nexus/files/images.lock.json |
while read -r ref; do
cosign verify --key release.pub --insecure-ignore-tlog=true \
"registry.adverant.ai/nexus/$ref" > /dev/null && echo "OK $ref" || echo "FAILED $ref"
doneChaque ligne doit commencer par OK. Sur notre connexion, la boucle a pris quelques minutes, principalement passées à attendre les réponses du registre. Elle ne lit que les signatures et ne télécharge aucune couche d'image, ce qui permet de la répéter facilement après chaque mise à niveau. Une ligne FAILED signifie qu'il faut s'arrêter : la section suivante explique la signification de chaque message.
Pour vérifier une seule image isolément, supprimez la redirection et lisez ce que cosign a contrôlé :
cosign verify --key release.pub --insecure-ignore-tlog=true \
registry.adverant.ai/nexus/nexus-auth@sha256:<digest>The following checks were performed on each of these signatures:
- Existence of the claims in the transparency log was verified offline
- The signatures were verified against the specified public key
<digest> correspond aux 64 caractères hexadécimaux issus du champ index du fichier de verrouillage pour cette image. Les images Enterprise nécessitent votre jeton de téléchargement pour cette vérification, comme pour tout téléchargement depuis le registre.
Les deux plateformes, et ce qu'il faut conserver
Chaque index d'image contient deux manifestes de plateforme, linux/amd64 et linux/arm64, et chacun d'eux est également signé. cosign verify réussit sur le condensat de l'index ainsi que sur le condensat de l'une ou l'autre plateforme ; un cluster composé de nœuds mixtes est donc couvert par la même vérification. Pour voir les deux plateformes derrière un index, demandez l'index brut au registre :
docker buildx imagetools inspect registry.adverant.ai/nexus/nexus-auth@sha256:<digest> --rawSa liste manifests mentionne une entrée amd64 et une entrée arm64.
Conservez le résultat de la boucle ci-dessus dans votre dossier de changement, à côté de l'empreinte que vous avez vérifiée. Lorsque quelqu'un vous demandera, des mois plus tard, comment vous savez que le cluster exécute bien ce qu'Adverant a livré, ce fichier et les condensats du fichier de verrouillage apporteront la réponse. C'est exactement la question que notre auditeur a posée à Harrow, et il n'a fallu qu'une minute pour y répondre.
Étape 6 : lire les attestations
Chaque image comporte également deux attestations signées, générées à partir de l'image au moment de la compilation : une nomenclature logicielle (SBOM, Software Bill of Materials) et une déclaration de provenance.
La nomenclature SBOM est au format SPDX (Software Package Data Exchange), à raison d'une par plateforme ; un index en comporte donc deux. Elle répertorie chaque paquet présent dans l'image ainsi que sa licence. Avant la publication, ces licences sont contrôlées par rapport à une liste d'exclusion ; aucune image Community ne contient de code sous licence GNU Affero General Public License (AGPL), Server Side Public License (SSPL), Redis Source Available License (RSAL) ou Business Source License (BUSL). La déclaration de provenance est au format SLSA (Supply-chain Levels for Software Artifacts) v1. Elle indique le commit source à partir duquel l'image a été compilée, les condensats des images de base, ainsi que les outils de compilation et leurs versions, ce qui permet de remonter d'une image jusqu'au code source audité sans avoir à interroger Adverant.
Toutes deux sont vérifiées à l'aide de la clé de publication que vous détenez déjà :
cosign verify-attestation --key release.pub --insecure-ignore-tlog=true \
--type spdxjson registry.adverant.ai/nexus/nexus-auth@sha256:<digest>
cosign verify-attestation --key release.pub --insecure-ignore-tlog=true \
--type slsaprovenance1 registry.adverant.ai/nexus/nexus-auth@sha256:<digest>La vérification spdxjson affiche deux résultats, un pour la nomenclature SBOM de chaque plateforme. Pour voir tout ce qui est rattaché à une image sans la vérifier, utilisez cosign tree :
cosign tree registry.adverant.ai/nexus/nexus-auth@sha256:<digest>Elle répertorie un lot de signature, deux attestations spdx.dev/Document et une attestation slsa.dev/provenance/v1. Demander un type que l'image ne comporte pas, tel que --type cyclonedx, échoue avec none of the attestations matched the predicate type: cyclonedx. Cet échec est normal ; la version joint le format SPDX, et non CycloneDX.
Étape 7 : vérifier le chart et les téléchargements
Le chart présent dans le registre est signé sur son condensat OCI (OCI désigne l'Open Container Initiative, le format d'image et d'artefact utilisé par les registres). helm pull affiche le condensat qu'il a récupéré ; vérifiez ce condensat de la même manière que pour une image :
cosign verify --key release.pub --insecure-ignore-tlog=true \
registry.adverant.ai/nexus/charts/nexus@sha256:<chart-digest>Pour un fichier de chart que vous avez téléchargé, ou pour l'archive hors ligne, nexusctl verify vérifie le fichier à l'aide de la clé de publication d'Adverant :
nexusctl verify nexus-1.0.0-alpha.1.tgzUn résultat valide se termine par la mention de la clé de publication d'Adverant et du début de son empreinte. Comparez ces groupes de caractères avec l'empreinte que vous avez vérifiée à l'étape 1.
L'archive hors ligne se présente sous la forme d'un fichier tar non compressé par édition, nexus-alpha-1.0.0-alpha.1-community.tar ou nexus-alpha-1.0.0-alpha.1-enterprise.tar, accompagné d'un fichier .sha256. À l'intérieur, elle contient :
| Chemin | En quoi cela consiste |
|---|---|
release/images.lock.json |
Le fichier de verrouillage des images pour cette édition |
release/facts.json |
Les informations de la version : numéro de version, édition, architectures et empreinte de la clé de publication |
images/<service>/ |
Chaque image avec les deux plateformes, sa signature et ses attestations |
charts/nexus-1.0.0-alpha.1.tgz |
Le chart |
sbom/ |
La nomenclature SBOM SPDX de chaque image, par plateforme |
docs/ |
Les notes de version, le guide d'installation en environnement isolé (air-gap) et des exemples de valeurs |
SHA256SUMS et SHA256SUMS.sigstore.json |
La somme de contrôle de chaque fichier, ainsi que sa signature |
La clé publique de publication ne se trouve jamais à l'intérieur de l'archive ; une clé livrée avec l'élément qu'elle signe ne prouve rien. Vérifiez l'intégralité de l'archive en deux commandes, depuis son dossier :
sha256sum -c SHA256SUMS
cosign verify-blob --key release.pub --insecure-ignore-tlog=true \
--bundle SHA256SUMS.sigstore.json SHA256SUMSChaque ligne de la première commande doit se terminer par OK, et la seconde doit afficher Verified OK. Le chapitre 2.10, Installation en environnement isolé (air-gap), prend le relais à partir de là pour l'utilisation de l'archive : chargement des images dans votre propre registre, nouvelle vérification de chacune d'elles à cet endroit, et contrôle de bout en bout propre à l'archive.
Lorsqu'une signature échoue à la vérification
Arrêtez tout. Ne procédez pas à l'installation et ne modifiez pas la commande pour forcer sa réussite. L'échec d'une vérification de signature prouve que le système fonctionne : cela signifie que le fichier dont vous disposez n'est pas celui qu'Adverant a signé, ou que la clé que vous détenez n'est pas celle d'Adverant.
| Ce que vous voyez | Ce que cela signifie | Que faire |
|---|---|---|
accepted signatures do not match threshold, Found: 0, Expected 1 (code de sortie 1) |
L'image est signée, mais pas par la clé que vous avez fournie | Vérifiez que vous avez bien utilisé la clé de publication dont vous avez contrôlé l'empreinte à l'étape 1 |
no signatures found (code de sortie 10) |
Aucun élément correspondant à ce condensat n'est signé | Vérifiez que le condensat provient bien du fichier de verrouillage ; ne vérifiez jamais une étiquette (tag) |
not enough verified log entries from transparency log: 0 < 1 |
--insecure-ignore-tlog=true est manquant |
Ajoutez l'option ; l'image elle-même ne présente aucun problème |
none of the attestations matched the predicate type |
Vous avez demandé un type d'attestation que l'image ne comporte pas | Utilisez spdxjson ou slsaprovenance1 |
Error: invalid signature when validating ASN.1 encoded signature |
Un fichier téléchargé a été modifié après avoir été signé | Téléchargez-le à nouveau |
FAILED renvoyé par sha256sum -c |
Un fichier ne correspond pas à celui dont la somme de contrôle a été calculée | Téléchargez-le à nouveau |
Si un téléchargement échoue à deux reprises, ouvrez une demande de support depuis votre compte en précisant le nom du fichier et le message obtenu. Conservez le fichier défaillant ; votre équipe de sécurité pourrait vouloir l'examiner.
Sur une installation qui charge les versions depuis un disque, la console exécute les mêmes vérifications et refuse toute version dont la signature ne correspond pas à la clé installée, en affichant MEDIA_SIGNATURE_INVALID. Elle indique ce qu'elle a vérifié, dans quel ordre, à quel endroit elle s'est arrêtée, et confirme qu'aucune modification n'a été apportée : aucune image n'a été chargée et la version en cours d'exécution reste intacte.
Une fois que la clé, les images et le chart ont tous passé les contrôles avec succès, l'étape suivante consiste à effectuer les vérifications préalables sur votre cluster, au chapitre 2.5, Vérifications préalables avec nexusctl.



