ConnexionPlanifier un briefing

Chapitre 2.28

Publier votre extension

Comment un plugin ou un pack passe d'une compilation validée aux unités qui l'exécutent, et comment il en est retiré. Versions, révision de mise en production, canaux et installations, signature, approbations de changement, enregistrement d'identité de livraison, migrations, retour arrière et retrait d'une version.

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

18 minutes de lecture

Cold chain 0.4.0 a été la première de nos versions à demander davantage que la précédente. Elle ajoutait l'envoi de courriels et une adresse externe, pour les alertes de conteneurs frigorifiques. La compilation était au vert, les tests réussissaient sur les trois branches synthétiques, et elle est pourtant restée deux jours dans l'espace de développement, le temps que deux personnes lisent ce qu'elle demandait et qu'une troisième approuve l'adresse. C'est ainsi que la publication sur Nexus doit se dérouler : le code est la partie facile, et ce sont les preuves et les approbations qui font la version.

Ce chapitre couvre tout ce qui se passe entre une compilation au vert et une version en service pour toutes les unités, ainsi que les moyens de revenir en arrière. Le parcours de promotion lui-même, de l'espace de développement à la préproduction, puis à une unité pilote et à toutes les unités, est présenté au chapitre 2.24, Construire un vertical sur mesure de bout en bout, et je n'en répéterai pas ici les contrôles. Une règle encadre l'ensemble. Le déploiement passe uniquement par les canaux de publication de l'installation. Il n'existe aucune porte dérobée pour un correctif urgent, et personne ne modifie à la main une image en cours d'exécution.

Versions

Trois numéros de version évoluent lors de la publication d'un pack, et il est utile de bien les distinguer.

Quoi Où il se trouve Exemple Règle
Le plugin version dans nexus.manifest.json 0.4.0 Version sémantique ; un suffixe de pré-version tel que -rc.1 est autorisé
Le pack version dans pack.json 0.4.0 Évolue avec les lentilles, le vocabulaire et les clusters du pack
Le modèle de connaissances La version propre du modèle 1.3 à 1.4 N'évolue que par une demande de modification du graphe

Une version de développement porte un suffixe, 0.4.0-dev, jusqu'à ce qu'elle atteigne la préproduction. Gardez des versions identiques pour le plugin et le pack lorsqu'ils sont livrés ensemble ; cela évite, à chaque revue de version, un débat sur le numéro auquel se rapportent les preuves.

Deux autres versions sont figées plutôt que choisies. La version du modèle de pack (domain-pack@1.6.0 pour Cold chain) est fixée à la création du pack et n'évolue que par une modification revue. Le SDK (kit de développement logiciel) est installé dans une version exacte, jamais une plage, afin que la même compilation donne le même résultat le mois suivant :

npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0

Les compétences du Skills Engine ont elles aussi des versions, et elles se comportent différemment. Chaque version publiée est figée, et live, canary et shadow sont des étiquettes posées sur des versions. Revenir en arrière consiste à déplacer une étiquette, et les exécutions déjà en cours se terminent sur la version avec laquelle elles ont démarré.

Avant de demander une révision : le manifeste

La page Manifeste et autorisations compare ce que cette version déclare avec la version précédente : ses portées, ses magasins, ses adresses sortantes et son profil de bac à sable. Lisez-la avant de demander une revue, car elle vous indique exactement ce que l'on demandera aux réviseurs d'accepter.

Manifeste et autorisations
Manifeste et autorisations
Ce que Cold chain 0.4.0 déclare par rapport à 0.3.2. Remarquez les deux lignes signalées comme un élargissement, l'envoi de courriels et une adresse externe, ainsi que l'encadré indiquant que la version ne quittera pas l'espace de développement tant que deux réviseurs ne les auront pas acceptées.

Une version qui demande davantage que ce que son manifeste déclarait auparavant est bloquée sur place, avec MANIFEST_SCOPE_WIDENED, jusqu'à ce que deux réviseurs acceptent le manifeste élargi. Une adresse externe nécessite en outre l'approbation de la personne responsable des adresses externes chez le client ; cette approbation est accordée pour une durée déterminée, et la nôtre portait sur 12 mois. Vous avez deux options : supprimer les lignes, ou demander une revue. La page propose les deux boutons.

Chaque ligne de cette page est appliquée à l'exécution, et pas seulement revue. Chaque appel d'outil est vérifié par rapport aux portées déclarées, une adresse externe est bloquée si elle ne figure pas dans la liste, et le profil de bac à sable n'autorise aucun autre réseau. Un plugin qui tente d'atteindre une ressource qu'il n'a pas déclarée est refusé, et la seule solution est une nouvelle version qui la déclare.

Révision de mise en production

La page Revue de version regroupe dans un seul tableau les preuves d'une version, à l'intention d'un réviseur qui n'en est pas l'auteur.

Revue de version
Révision de mise en production
La vue d'un second réviseur sur Cold chain 0.4.0, avec le tableau des preuves, la comparaison des portées et les commentaires. Remarquez l'encadré à droite : l'auteur ne peut pas approuver sa propre version.
Preuve Ce qu'elle a montré pour 0.4.0
Tests 66 sur 66, sur trois branches synthétiques
Contrôles qualité La documentation et le code concordent
Politique Chaque lentille ne fait que restreindre ; champs personnels désactivés par défaut
Signatures Image et paquet signés par le pipeline
Comparaison des portées Ajoute l'envoi de courriels et une adresse externe, avec son approbation
Compatibilité La version de la plateforme et la version du pack de base sur lesquelles elle a été testée
Modification du modèle Simulation de la demande de modification du graphe : 1 284 liens renommés, aucune suppression

Sous le tableau figurent les commentaires sur la modification et la provenance : quel pipeline l'a compilée, à partir de quelle modification, l'empreinte de l'image et le modèle. Les réviseurs approuvent avec leur clé d'accès. Deux réviseurs qui ne sont pas l'auteur approuvent, puis le pipeline fait passer la version en préproduction. L'auteur ne compte jamais comme réviseur, et toute tentative est refusée avec NEEDS_SECOND_PERSON. Une demande de revue expire au bout de 3 jours.

Répondez aux questions des réviseurs dans les commentaires, et non dans une fenêtre de discussion. Lors de notre revue, notre responsable de la conformité a demandé pourquoi le montant de la réclamation était classé comme commercial, et le second réviseur a demandé le plan de retour arrière pour la modification du modèle. Ces deux réponses font désormais partie de l'historique de la version, là où le prochain réviseur ira chercher.

Approbations de la politique de changement

La revue de version porte sur la version dans son ensemble. Le bloc changePolicy du manifeste va plus loin : il indique quelles classes de modifications des éléments déployables de votre plugin nécessitent une approbation, et de combien de personnes.

"changePolicy": {
  "enabled": true,
  "classes": ["website", "bff", "migration"],
  "approvals": { "website": 1, "bff": 1, "migration": 2 }
}

Les trois classes sont website (l'application web), bff (le backend for frontend) et migration (une migration de base de données). Chaque classe citée dans classes doit avoir son propre nombre dans approvals, de 1 à 10. Une classe que vous omettez n'est pas gouvernée, et le schéma vous oblige à l'écrire comme un choix plutôt qu'à y aboutir par omission. Nous exigeons deux approbations pour les migrations, car une migration est la seule modification difficile à annuler.

Les approbations sont comptées en personnes distinctes, et l'auteur de la proposition n'en fait jamais partie. Les règles qui garantissent cela méritent d'être connues, car chacune entraîne un refus :

  • Une approbation de la personne qui a proposé la modification est refusée avec TRUST_APPROVAL_SELF_APPROVAL.
  • Une personne qui n'est pas du tout autorisée à effectuer une modification de cette classe est refusée avec CHANGE_CLASS_NOT_PERMITTED.
  • Lorsqu'un commit de la modification est signé par l'identité d'agent de l'organisation, le quorum correspond au minimum habituel plus un, et le vote de l'agent lui-même ne compte pas.
  • Chaque approbation enregistre le diff et la tête qu'elle a vus. Si la modification évolue après la dernière approbation, sa fusion est refusée avec HASH_MISMATCH, et les approbations doivent être recueillies à nouveau pour le nouveau contenu.

Cette troisième règle compte si vous développez avec un outil de codage par IA (intelligence artificielle), comme le décrit le chapitre 2.26, Développer avec des outils de codage par IA. Un travail écrit par un agent nécessite une approbation humaine de plus qu'un travail écrit par une personne. Prévoyez-le.

Signature et vérification

Chaque image et chaque paquet sont signés par le pipeline qui les a compilés, et une image signée est l'un des contrôles d'accès à la préproduction. Un espace de développement n'exécute que des images signées dès le départ. Sur Enterprise, un administrateur configure chaque namespace pour soit enregistrer les images non signées, soit les refuser, et fait passer les namespaces au refus un par un, de sorte que la production finit par n'exécuter que des images compilées et signées par le pipeline. La signature fait partie de la compilation, ce n'est pas un élément que l'on ajoute avant une publication.

La règle qui traverse l'ensemble est qu'une signature en échec est un refus, jamais un avertissement. Un contrôle qui reçoit SIG_INVALID s'arrête. Il ne se rabat pas sur la version non signée et ne poursuit pas avec une simple note dans un journal, car un avertissement dans un journal de compilation vaut validation pour tous ceux qui ne l'ont pas lu.

La même règle s'applique à tout ce que vous remettez sur support physique. Un bundle scellé destiné à un client isolé du réseau est vérifié avec votre clé publique avant tout dépaquetage, et le chapitre 2.25, Développer pour chaque édition, présente la commande.

Identité de livraison

Un plugin est livré au moyen de plusieurs éléments qui portent chacun un nom : ses dépôts, une clé de signature, un namespace de déploiement, un préfixe de registre, un schéma de base de données, un ensemble de domaines et une politique de modification. Chacun d'eux est un point où deux plugins pourraient entrer en collision, ou un plugin pourrait dériver. L'identité de livraison est un enregistrement signé par plugin qui les réunit tous, de sorte que chaque contrôle du parcours de publication lit la même réponse et refuse en cas de divergence.

Vous fournissez votre part par le manifeste et par rien d'autre : schema, db, domains, changePolicy et l'URL du dépôt. La plateforme complète l'enregistrement avec le reste et le signe. Vous ne nommez jamais vous-même votre namespace, votre préfixe de registre ou votre clé de signature. Ils vous sont attribués, et un manifeste qui tenterait de les déclarer avancerait une affirmation que les contrôles devraient ensuite rejeter.

L'enregistrement signé contient onze champs : le slug du plugin, l'organisation propriétaire, l'organisation qui le compile, ses dépôts, le nom de sa clé de signature, son namespace de déploiement, son préfixe de registre, son schéma de base de données, ses domaines, sa politique de modification, et une courte liste d'anciens noms d'image utilisés avant l'existence de son préfixe de registre. Cette dernière liste ne peut que diminuer. Comme elle est signée, une nouvelle signature peut en retirer une entrée, et rien ne peut en ajouter une discrètement. La signature est une signature Ed25519 sur la forme JSON canonique standard de ces onze champs, de sorte qu'un enregistrement contenant « Tomás » ou « Sinéad » se vérifie de la même manière partout.

Lorsqu'une version ne correspond pas à son enregistrement, le premier refus l'emporte :

Code Situation HTTP
DELIVERY_IDENTITY_MISSING Il n'existe aucun enregistrement pour le plugin 403
DELIVERY_PATH_REFUSED Un envoi d'image hors du préfixe de registre qui ne figure pas dans la liste signée des anciens noms 403
NAMESPACE_MISMATCH Un déploiement ciblant un autre namespace 403
IMAGE_NAME_COLLISION Un nom d'image déjà revendiqué par un autre plugin 409
CHANGE_CLASS_NOT_PERMITTED Une classe de modification que la politique ne gouverne pas 403

IMAGE_NAME_COLLISION est celui qui surprend. Choisissez un autre nom, et n'en réutilisez jamais un : un nom d'image partagé signifie que la promotion d'un plugin peut déplacer les pods d'un autre plugin.

Migrations, validées et ciblées

Une migration est livrée dans l'image de votre plugin et s'exécute avant le démarrage de la nouvelle version, au moyen de l'unique exécuteur de migrations du SDK, nexus-migrate. Vous n'écrivez pas votre propre outil d'application. Avant qu'une version puisse avancer, ce même exécuteur applique vos migrations fichier par fichier sur une base de données jetable, de sorte qu'une migration qui échoue échoue à cet endroit. La compilation fantôme du modèle appelle l'exécuteur une fois par fichier, dans l'ordre, et enregistre chaque fichier comme le fera la production.

Les règles de l'exécuteur sont celles que vérifient les contrôles, écrites sous forme de code :

  1. Il se connecte avec le rôle de migration de votre schéma et exécute chaque fichier en tant que propriétaire du schéma. Toute autre connexion, à commencer par celle d'un superutilisateur, est refusée. Un fichier qui tente lui-même de changer de rôle est refusé avant toute exécution.
  2. Le fichier de tenancy, numéroté 0, n'est jamais modifié après son application. Une modification de la tenancy fait l'objet de son propre fichier de révision, 000_tenancy_r<N>.sql, que nexus-tenancy render --revision <N> rédige pour vous.
  3. Normalement, l'exécuteur gère la transaction de chaque fichier et refuse un BEGIN ou un COMMIT à l'intérieur. Un fichier qui gère ses propres transactions déclare qu'il s'exécute instruction par instruction, et chaque BEGIN qu'il ouvre doit alors avoir sa correspondance.
  4. Il tient un registre, une ligne par fichier, avec le SHA-256 du fichier et son mode d'exécution. Un fichier appliqué n'est jamais modifié sur place ; une modification constitue un nouveau fichier numéroté.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sql

Cloisonné signifie que chaque nouvelle table comporte organization_id, owner_user_id et business_unit_id, ainsi que la colonne de marquage is_demo sauf si gates/demo-exempt.json exempte la table avec une justification, avec une clé primaire commençant par l'organisation et des clés étrangères qui la portent, et la sécurité au niveau des lignes imposée. Le contrôle migrations-are-scoped vérifie ces règles sur chaque fichier, et migrations-commit-what-they-open vérifie que chaque fichier valide ce qu'il ouvre. Le second contrôle existe parce qu'une migration annulée silencieusement s'est un jour terminée avec le code 0, et que la table qu'elle aurait dû créer n'a jamais existé.

Un fichier supplémentaire accompagne chaque version. scripts/ci/required-env affiche les variables d'environnement dont votre service a besoin pour démarrer, sous forme de tableau JSON tiré de votre chargeur de configuration. Le parcours de publication l'exécute et refuse une version dont le déploiement ne définit pas chacune d'elles, de sorte qu'une variable manquante est détectée avant la publication, et non par un pod qui refuse de démarrer.

node scripts/ci/required-env

Publier des compétences

Les deux types de compétences parviennent aux utilisateurs par des voies différentes ; publiez-les donc différemment.

Une compétence de manifeste, une ligne typée dans le skills[] de votre plugin, est livrée avec le plugin et suit la même promotion que le reste. L'onboarding synchronise l'ensemble des compétences avec le registre à chaque version. Si vous omettez une compétence de l'ensemble, elle est désactivée, et sur Enterprise une synchronisation comportant une seule compétence défectueuse n'en applique aucune, de sorte que la version précédente continue de fonctionner plutôt que la moitié de la nouvelle.

Une compétence du Skills Engine est publiée depuis la bibliothèque. Dans l'édition Enterprise, une compétence qui ajoute un outil d'écriture attend l'approbation de deux personnes nommément désignées, avec leurs clés d'accès, et l'auteur de la proposition ne peut pas être l'une d'elles. Une version approuvée s'exécute ensuite en mode fantôme, puis en canari pour une unité derrière des seuils nommés, puis pour tous, et elle s'arrête d'elle-même si un seuil n'est pas atteint. Si votre plugin et une compétence du Skills Engine dépendent l'un de l'autre, publiez d'abord la compétence et laissez-la atteindre tout le monde avant que la version du plugin qui l'appelle ne sorte du pilote.

Canaux et installations

Une fois qu'une version a franchi le pilote et atteint toutes les unités, elle est proposée sur un canal, et chaque unité choisit son canal. Son administrateur approuve chaque changement. La page Canaux et installations indique quelles unités exécutent quelle version, avec des taux d'erreur exprimés uniquement en nombres : vous voyez comment votre extension se comporte, jamais ce que quiconque en a fait.

Canaux et installations
Canaux et installations
Quelles unités exécutent quelle version de carrier-sync, avec un retour arrière ouvert pour une unité. Remarquez ce que la fenêtre modale indique comme changeant, ce qui reste inchangé, et qu'elle requiert une seconde personne : l'administrateur de l'unité elle-même.

Notre plugin carrier-sync exécute trois versions simultanément, et c'est normal. La plupart des unités sont sur la version actuelle, une unité reste sur une version plus ancienne sur un canal maintenu jusqu'à une date annoncée, et une version candidate se trouve sur un canal que personne n'a encore choisi. Ne luttez pas contre cela ; une unité qui a besoin de stabilité pour un audit y a droit.

Journaux et métriques de votre extension

La page des journaux et métriques de votre pack est limitée à vos propres charges de travail, dans les unités que vous êtes autorisé à consulter. Vous pouvez filtrer par unité et par environnement, et vous voyez des nombres, des durées et des états.

Journaux et métriques de votre pack
Journaux et métriques de votre pack
Les journaux et métriques propres à Cold chain, filtrés sur le pilote de Rotterdam. Observez les lignes de journal : la personne qui a signalé un écart est masquée, et le texte de la note de réclamation n'est jamais journalisé.

Les champs personnels sont remplacés avant qu'une ligne ne soit écrite, et le contenu client, tel que le texte des réclamations, les e-mails ou le contenu des documents, n'est jamais écrit dans les journaux. Les journaux sont conservés 14 jours. L'organisation est définie par la passerelle, jamais par votre requête ; une requête qui désigne une autre organisation est donc refusée avec TENANT_BOUNDARY. L'assistant du dock peut lire les mêmes journaux avec vous, et uniquement ceux-ci : lorsque je lui ai demandé pourquoi les enregistrements d'écart étaient arrivés en retard un matin, il a attribué 18 minutes de nouvelles tentatives à des relevés en double provenant de l'alimentation électrique d'un quai.

Retour arrière

Il existe deux types de retour arrière, et tous deux sont des modifications soumises à revue plutôt que de simples bascules.

Le retour arrière d'un environnement utilise la version précédente. Chaque environnement la conserve pendant 30 jours. Le retour arrière est préparé sous forme de modification de la version, présente un aperçu de ses effets et requiert une seconde personne ; une fois approuvé, le pipeline effectue le retour arrière en une minute environ. Chaque retour arrière est chronométré, de même que chaque exercice ; entraînez-vous donc avant d'en avoir besoin. Le retour arrière d'une unité utilise la page Canaux et installations. La fenêtre modale de retour arrière indique ce qui change (cette unité exécute à nouveau l'ancienne version, et son taux d'erreur est surveillé pendant une heure), ce qui reste inchangé (les autres unités, ainsi que les paramètres et les enregistrements de l'unité), le motif, et qui est la seconde personne : l'administrateur de cette unité.

Les paramètres et les enregistrements sont conservés lors d'un retour arrière ; planifiez donc chaque version en partant du principe que la version précédente pourra s'exécuter à nouveau sur les données écrites par la plus récente. C'est la raison pratique pour laquelle les migrations doivent rester additives au sein d'une version que vous pourriez annuler, et la raison pour laquelle nous demandons à deux personnes d'approuver chacune d'elles. Il en va de même pour une modification de modèle : un relecteur peut, et doit, demander le plan de retour arrière d'une demande de modification du graphe avant de l'approuver.

Le retour arrière des compétences est plus en douceur. Ramener le libellé actif sur une version antérieure se fait en une étape, et les exécutions déjà en cours se terminent sur la version avec laquelle elles ont commencé.

Retirer une version

Une version, une fois publiée, n'est jamais modifiée. Une version qui ne doit plus être utilisée est retirée, et un correctif est livré sous un nouveau numéro de version. Les canaux de publication du SDK suivent la même pratique : une version défectueuse du SDK est retirée, jamais remplacée par un contenu différent sous le même numéro. Reprenez cette pratique, car un numéro de version pouvant désigner deux builds différents rend sans valeur toute preuve qui s'y rapporte.

Le retrait d'un plugin ou d'un pack arrête les nouvelles installations. Les unités conservent la version qu'elles exécutent jusqu'à ce qu'elles changent ; le retrait est donc un signal et une échéance, pas un interrupteur. Indiquez aux administrateurs des unités vers quelle version migrer et dans quel délai.

Le retrait d'une compétence suit le même principe avec une étape supplémentaire. Le Skills Engine transfère tous les appelants restants vers une compétence de remplacement après avoir exécuté les cas de celle-ci, arrête les nouvelles exécutions, et conserve les versions, les cas et les enregistrements d'exécution scellés, afin que la compétence puisse être rétablie si le remplacement s'avère inadéquat.

Liste de contrôle de mise en production

Voici la liste que nous relisons avant chaque version de Cold chain. Elle est courte, car la plateforme en vérifie l'essentiel pour nous.

  1. Les versions concordent : le manifeste, pack.json, et le modèle de connaissances s'il a évolué.
  2. Tous les contrôles sont au vert en local, à partir d'un état propre, et chaque nouveau test a d'abord été vu en échec.
  3. La page Manifeste et autorisations n'indique aucun élargissement, ou l'élargissement est voulu et les relecteurs savent pourquoi.
  4. Chaque migration est un nouveau fichier numéroté, délimité, et appliqué proprement sur une base de données jetable.
  5. scripts/ci/required-env répertorie toutes les variables dont le service a besoin, et le déploiement définit chacune d'elles.
  6. Le plan de retour arrière est rédigé dans la modification, y compris pour toute modification de modèle.
  7. Deux relecteurs autres que l'auteur sont disponibles cette semaine.

Le dernier point semble anodin. C'est pourtant celui qui a retardé davantage de nos versions que tous les contrôles réunis.