# Mettre à jour une passerelle d'actions locale sans interrompre le travail des agents

La mise à jour d'une passerelle d'actions est une modification du plan de contrôle, pas une tâche d'entretien ordinaire du poste de travail. Si un agent est en train de modifier un dépôt, d'effectuer une écriture HTTP ou une opération SSH, la mise à jour peut couper le travail en deux parties incertaines. La méthode sûre consiste à choisir une limite de travail, à terminer ou arrêter volontairement les actions actives, puis à vérifier que la nouvelle version peut autoriser, exécuter et tracer les opérations avant de relancer l'automatisation.

L'erreur courante consiste à considérer tous les agents actifs comme jetables. Certains le sont. D'autres contiennent un plan soigneusement préparé, un shell distant ouvert ou une requête dont l'appelant n'a pas encore reçu le résultat. Vous devez savoir à quel cas vous avez affaire avant de toucher à l'application.

## Planifier les mises à jour autour d'une limite de travail

Une bonne fenêtre de maintenance commence lorsque l'agent a atteint un état qu'une personne peut comprendre et reprendre. Cette limite ne signifie pas forcément que toutes les tâches sont terminées. Elle signifie que la personne, le processus ou l'agent suivant peut déterminer ce qui s'est passé, ce qui reste à faire et ce qu'il ne faut pas répéter.

Demandez d'abord à l'agent de ne plus lancer de nouvelles actions externes. Faites-lui ensuite rédiger une courte transmission dans le dépôt, le ticket ou les notes d'exploitation. Elle doit indiquer la branche et le commit actuels, les fichiers modifiés mais non validés, les tests déjà exécutés, les systèmes distants contactés et la prochaine action prévue. C'est plus utile qu'une transcription qui oblige quelqu'un à reconstituer l'intention à partir de centaines d'appels d'outils.

Une fenêtre de mise à jour raisonnable comporte quatre phases :

1. Annoncer le gel des nouvelles exécutions d'agents et des nouveaux appels nécessitant des identifiants.
2. Laisser se terminer le travail limité, ou l'arrêter à une limite enregistrée.
3. Effectuer la mise à jour et un petit nombre de contrôles avec un nouveau processus agent.
4. Lever le gel uniquement après avoir rapproché l'activité de la fenêtre.

N'attendez pas une date prévue si la passerelle présente une faille de sécurité qui touche les identifiants ou l'autorisation. Dans ce cas, arrêtez ou révoquez d'abord le travail exposé, consignez l'interruption et mettez à jour l'application comme lors d'un incident. Mais ne créez pas d'urgence simplement parce qu'une nouvelle version existe. Des mises à jour fréquentes et désinvoltes apprennent aux équipes à ignorer les contrôles qui révèlent les mauvaises hypothèses.

Pour la maintenance courante, préférez le moment qui suit la validation du code par l'agent et précède le déploiement, la migration de données, les changements de comptes ou le nettoyage distant. Une modification de code locale peut généralement reprendre. Une modification de permissions interrompue en plein milieu, souvent pas.

Il faut aussi désigner un responsable de la fenêtre. Cette personne décide quand geler le travail, évalue les résultats ambigus et déclare la passerelle prête. Un canal de discussion rempli de personnes qui pensent que quelqu'un d'autre surveille la mise à jour n'est pas un modèle d'exploitation.

## Considérer l'autorisation du processus et l'achèvement de l'action comme deux faits distincts

Un processus agent approuvé et une action externe terminée répondent à deux questions différentes. On les confond parce qu'ils apparaissent souvent à peu près au même moment, mais cette distinction détermine la façon de récupérer après une interruption.

L'autorisation du processus demande : « Ce programme précis en cours d'exécution peut-il demander une action à la passerelle ? » L'achèvement de l'action demande : « Le système distant a-t-il accepté et terminé cette requête précise ? » Le redémarrage d'une application peut modifier la première réponse. Une panne réseau peut masquer la seconde. Aucune de ces réponses n'implique l'autre.

Pour les appels HTTP, notez si une opération peut être répétée sans risque. Une requête de lecture le peut généralement. Créer un utilisateur, envoyer un paiement, publier une version ou renouveler un identifiant peut ne pas l'être. Si l'agent expire après avoir envoyé une telle requête, il doit interroger le système cible pour retrouver l'objet ou l'événement correspondant avant de réessayer. Réessayer parce que l'appel d'outil n'a pas de résultat visible est la manière dont les doublons apparaissent.

SSH présente ses propres modes d'échec. Un terminal peut contenir une commande au premier plan, une tâche en arrière-plan, un éditeur, une transaction de base de données ou un outil de déploiement qui continue après la déconnexion du client. Avant la maintenance, demandez à l'agent d'indiquer l'hôte distant, le répertoire de travail, la commande actuelle et les identifiants des tâches éventuelles. S'il a lancé une opération longue, décidez s'il faut l'attendre, l'arrêter par une commande distante explicite ou la confier à un processus supervisé qui survit au shell.

N'utilisez pas le redémarrage de la passerelle comme une façon vague de « faire le ménage ». Cela crée de l'incertitude sans laisser de trace de l'arrêt voulu. Révoquez ou terminez l'exécution précise de l'agent lorsque vous voulez l'arrêter, et demandez à l'agent d'indiquer ce qu'il a observé en dernier.

Une note de transmission pratique peut être aussi simple que ceci :

```text
Agent run: release-fix
Repository state: commit 4f2c... created, working tree clean
Remote work: SSH command started on build host, job ID 8127
HTTP writes: staging deployment request accepted, status still pending
Safe next action: query deployment status; do not submit another deployment
```

Cet élément donne à l'opérateur un moyen de vérifier l'état du système après la mise à jour. Sans lui, l'équipe redémarre souvent l'agent et prend une nouvelle explication pour une continuité.

## Geler le nouveau travail avant de terminer l'ancien

Un gel de maintenance ne fonctionne que s'il ferme le point d'entrée des nouvelles tâches. Dire aux développeurs de ne pas lancer un autre agent est courtois, mais peu fiable, surtout lorsque des intégrations d'éditeur, des terminaux et des scripts planifiés peuvent démarrer des processus indépendamment.

Enregistrez chaque processus agent actif avant le gel. Notez suffisamment de détails pour les distinguer : qui l'a lancé, quel dépôt ou quelle tâche il possède, quels accès externes sont prévus et s'il a du travail en cours. Si la passerelle expose une vue des sessions, utilisez-la comme enregistrement principal. Complétez-la avec le responsable humain de la tâche, car un enregistrement de processus ne peut pas dire si une modification inachevée est encore souhaitée.

Séparez ensuite le travail actif en trois groupes :

- Le travail sans effet externe peut s'arrêter immédiatement.
- Les actions courtes et observables peuvent se terminer sous supervision.
- Les opérations longues ou irréversibles nécessitent une décision explicite du responsable de la tâche.

Ne laissez pas le drainage durer indéfiniment. Fixez une échéance adaptée à l'opération. Une requête qui devrait se terminer en quelques secondes mais qui dure beaucoup plus longtemps est déjà devenue une enquête, pas une raison de retarder la maintenance sans limite. Notez ses identifiants et déterminez son état auprès du service distant.

Un agent qui continue à produire des modifications locales pendant le gel peut encore créer de la confusion, même s'il ne peut plus appeler d'outils externes. Demandez-lui de s'arrêter proprement après avoir écrit sa transmission. Si vous devez préserver son contexte, conservez les notes de la tâche et l'état du dépôt plutôt que de compter sur la durée de vie ininterrompue du processus.

Sallyport enregistre les exécutions d'agents dans son journal Sessions et les appels individuels dans son journal Activity. Utilisez ces enregistrements pour identifier le travail que vous avez volontairement laissé se terminer, au lieu de le déduire plus tard du défilement d'un terminal.

## Traiter les résultats réseau ambigus comme un incident

Une requête qui perd sa réponse pendant une mise à jour a un résultat inconnu jusqu'à ce que le système distant indique le contraire. La déclarer échouée parce que le client local a reçu une erreur est un raccourci coûteux.

Supposons qu'un agent envoie une requête API pour créer un déploiement et que la passerelle locale se ferme ou redémarre avant l'arrivée de la réponse. Quatre résultats restent possibles : la requête n'a jamais quitté la machine, le service l'a refusée, le service l'a acceptée mais ne l'a pas encore terminée, ou le service l'a terminée. Le message d'erreur local ne permet pas de distinguer ces cas de manière fiable.

Levez l'ambiguïté dans cet ordre :

1. Trouvez l'identifiant de requête, le nom du déploiement, la référence du commit ou toute autre valeur de corrélation utilisée par l'agent.
2. Interrogez le service distant avec cette valeur au moyen d'une action fraîche et supervisée.
3. Comparez le résultat distant avec la modification prévue et l'enregistrement d'audit.
4. Réessayez uniquement si le système distant montre qu'aucune opération équivalente n'a eu lieu.

C'est pourquoi l'idempotence compte. Lorsqu'une API prend en charge un jeton d'idempotence ou un identifiant de requête fourni par le client, demandez à l'agent d'en utiliser un pour les opérations d'écriture. Le même jeton transforme une nouvelle tentative incertaine en opération interrogeable. Si l'API ne le permet pas, utilisez un nom d'objet ou une référence de modification qui permet à une personne de déterminer si la première tentative a abouti.

La spécification HTTP Semantics, RFC 9110, définit les méthodes idempotentes selon l'effet prévu de requêtes répétées, et non selon le fait que le serveur renvoie ou non la même réponse à chaque fois. C'est utile, mais cela ne rend pas tous les `PUT` ou `DELETE` inoffensifs dans votre environnement. Une requête répétée peut encore déclencher des notifications, entrer en concurrence avec une autre écriture ou supprimer une ressource recréée par un autre acteur. Considérez la classification du RFC comme un point de départ, puis tenez compte du comportement du service cible.

Pour SSH, recueillez les preuves sur l'hôte distant. Vérifiez les tables de processus, les journaux de service, l'état du déploiement, l'état des transactions et les fichiers créés par la commande. Ne demandez pas à l'agent de relancer une commande shell simplement parce que sa session locale a disparu. Les commandes shell offrent rarement les protections contre la répétition que les API matures proposent.

## Vérifier la version avant de la placer dans le chemin des actions

Un paquet d'application signé indique qui a signé le code et si le paquet a changé après la signature. Il ne dit pas si la version conserve le format de votre coffre-fort, le comportement des sessions, la compatibilité des assistants ou le flux de travail de l'opérateur.

Apple Platform Security explique que la signature du code permet à macOS d'identifier le code signé et de détecter les modifications. C'est une propriété nécessaire pour une application qui manipule des identifiants. Elle ne remplace ni les notes de version, ni l'exécution de tests, ni un plan de récupération. Les équipes accordent parfois trop de pouvoir à la signature parce que le contrôle cryptographique est clair et visible, alors que la compatibilité opérationnelle l'est moins.

Avant la fenêtre, lisez les notes de version pour connaître les changements touchant :

- le stockage ou la migration du coffre-fort
- l'autorisation et la gestion des sessions
- les assistants de commandes inclus et les détails de connexion des agents
- le stockage, l'exportation ou la vérification des audits
- les versions de macOS et les permissions requises

Notez la version en cours et la version cible dans la fiche de maintenance. Décidez aussi ce qui vous ferait arrêter : échec du déverrouillage du coffre-fort, impossibilité d'établir une nouvelle session agent approuvée, refus inattendu d'une action ou échec de la vérification d'audit sont autant de conditions valables.

Un plan de retour en arrière demande plus qu'une ancienne copie de l'application. Il lui faut une règle d'utilisation et un plan pour l'état que la nouvelle version peut avoir modifié. Si une version migre des données locales, revenir en arrière sans les instructions du fournisseur peut transformer un problème récupérable en perte de données. Testez le chemin exact de mise à niveau sur un Mac de rechange ou une installation sans importance lorsque la version modifie le stockage ou l'autorisation. Une installation propre ne vous apprend presque rien sur l'état que vous exploitez réellement.

Évitez de tester avec l'identifiant qui pourrait provoquer l'impact le plus important. Commencez par un compte limité à une lecture inoffensive ou à une cible jetable. Vous vérifiez le parcours dans l'application, l'autorisation, l'injection de l'identifiant et le traitement du résultat. Un déploiement de production n'est pas nécessaire pour prouver qu'une application dans la barre des menus s'est lancée.

## Effectuer les contrôles après la mise à jour avec un nouveau processus agent

Un test après mise à jour doit prouver les parcours que les agents actifs utiliseront, pas seulement montrer que l'interface s'ouvre. Utilisez un processus agent fraîchement lancé afin de tester la limite d'autorisation attendue après la maintenance.

Commencez par le coffre-fort. Verrouillez-le et déverrouillez-le selon le parcours local habituel. Lorsqu'il est verrouillé, tentez l'action de test sûre et vérifiez que la passerelle la refuse. Déverrouillez-le ensuite et vérifiez qu'un nouveau processus reçoit la demande d'autorisation ou le parcours d'approbation attendu. Cela révèle l'hypothèse erronée selon laquelle une ancienne approbation aurait survécu, ou la nouvelle version incapable d'identifier le processus appelant.

Exécutez ensuite une requête HTTP sûre et une requête SSH sûre si votre équipe utilise les deux canaux. Un bon test HTTP demande un point de terminaison en lecture seule qui renvoie un résultat reconnaissable. Un bon test SSH exécute une commande inoffensive sur un hôte sans importance, par exemple l'affichage du répertoire courant ou d'un marqueur fixe. Notez l'heure, la destination et le résultat afin de retrouver ces appels dans l'historique d'activité.

Sallyport conserve les identifiants dans son coffre-fort chiffré et effectue lui-même les actions HTTP et SSH, de sorte que l'agent reçoit le résultat sans recevoir le secret. Cette conception réduit ce que le test de mise à jour doit exposer, mais elle ne dispense pas de tester chaque canal dont vous dépendez.

Enfin, testez la piste d'audit. Exécutez la commande de vérification hors ligne documentée :

```sh
sp audit verify
```

Le résultat attendu doit signaler que la vérification de la chaîne d'audit a réussi. Ne vous fiez pas à une phrase mémorisée et ne l'extrayez pas avec un script fragile, sauf si la documentation de la commande garantit un format lisible par machine. Le résultat utile est simple : la commande se termine correctement, signale une vérification réussie et vous pouvez retrouver les appels de test dans les journaux.

Si la vérification échoue, arrêtez-vous. Ne laissez pas passer le problème parce que l'application peut encore effectuer une requête. Une chaîne d'audit impossible à vérifier après la maintenance supprime les preuves précisément au moment où vous en avez besoin pour comprendre la modification.

## Rapprocher chaque action qui a franchi la fenêtre de maintenance

La mise à jour ne se termine qu'après avoir rendu compte des actions commencées avant le gel, poursuivies pendant celui-ci ou apparues après le démarrage de la nouvelle version. C'est lors de ce rapprochement que les opérateurs attentifs découvrent la nouvelle tentative qui a dupliqué un appel API ou la tâche SSH qui a continué sans être vue.

Faites un tableau court dans le relevé de maintenance. Pour chaque agent actif au début, indiquez la dernière action prévue, le résultat observé, la source qui l'a confirmé et si une personne a autorisé une nouvelle tentative. La source peut être un enregistrement d'activité, l'état d'un service distant, un journal d'hôte ou un commit de dépôt. Si deux sources sont en désaccord, considérez le système distant comme l'autorité pour l'état externe et recherchez la cause de la différence.

Portez une attention particulière aux actions qui renvoient leur résultat lentement. Une passerelle peut consigner l'envoi d'une requête alors que le système cible reste en attente. Ce n'est pas une contradiction. Cela indique jusqu'où l'action est parvenue, pas si une tâche distante asynchrone est terminée. Continuez la surveillance via le mécanisme d'état habituel de la cible jusqu'à un état final, ou jusqu'à la prise en charge par le responsable de la tâche.

Les enregistrements de session indiquent qui disposait d'une autorisation pendant la fenêtre. Les enregistrements d'activité indiquent quels appels ont eu lieu. Ne remplacez pas l'un par l'autre. Un processus approuvé peut n'effectuer aucun appel, tandis qu'un appel terminé peut avoir commencé avant l'ouverture du relevé de maintenance.

Ce rapprochement doit aussi révéler les appelants inattendus. Un nouveau processus apparu pendant le gel signifie que celui-ci était incomplet, même si sa requête n'a causé aucun dommage. Trouvez le mode de lancement avant la prochaine fenêtre. Il peut s'agir d'un terminal de développeur, d'une extension d'éditeur ou d'un script local automatique que personne ne considérait comme faisant partie du flux de travail des agents.

## Conserver les limites d'approbation après la mise à jour

Les mises à jour sont un moment tentant pour affaiblir les contrôles, car les opérateurs veulent que les tests réussissent rapidement. Évitez de transformer une approbation large en solution permanente pour un flux de travail bruyant.

L'autorisation par session convient au travail agent courant lorsqu'un processus connu doit effectuer plusieurs appels liés. Elle permet à l'opérateur d'identifier et d'approuver cette exécution, puis d'en examiner l'activité comme un ensemble. La confirmation par appel convient aux identifiants dont chaque utilisation mérite une décision humaine explicite, par exemple ceux qui modifient les accès de production, suppriment des données ou déclenchent un événement externe irréversible.

L'erreur consiste à configurer le réglage le plus strict comme punition après un incident, puis à le laisser en place pour les lectures courantes à faible risque jusqu'à ce que les utilisateurs approuvent les demandes sans les regarder. Des approbations répétées les habituent à cliquer sur l'écran même qui devrait les faire réfléchir. Activez la confirmation par appel pour les identifiants dont une seule mauvaise action aurait un coût élevé. Gardez le reste sous revue au niveau de la session et limitez la portée des identifiants lorsque c'est possible.

Le verrouillage du coffre-fort doit rester un arrêt absolu. Pendant une maintenance planifiée, verrouillez-le lorsque vous avez besoin d'une limite stricte qui refuse toutes les actions. Lorsque vous le déverrouillez pour vérification, faites-le avec le processus de test choisi à l'avance. Vous transformez ainsi un événement de maintenance général en un petit nombre d'actions observées.

Ne confondez pas une passerelle d'actions avec un moteur général de politiques. Une passerelle peut éloigner les identifiants d'un agent et placer un humain aux limites d'autorisation. Elle ne peut pas comprendre le sens métier de chaque appel API, réparer un mauvais plan de déploiement ou savoir qu'un point de terminaison apparemment inoffensif déclenche un flux coûteux en aval. Le responsable de la tâche reste responsable de ces décisions.

## Écrire le runbook pour l'interruption qui se produira réellement

Un runbook utile ne dit pas seulement « mettre à jour la passerelle et tester ». Il nomme les preuves à recueillir, les décisions à prendre en cas d'incertitude et le point exact où le travail autonome peut reprendre.

Gardez-le assez court pour qu'une personne l'utilise sous pression. Le mien comporte un responsable du gel, la liste des exécutions actives, une règle explicite pour les SSH actifs et les écritures HTTP ambiguës, la version cible, une décision de retour en arrière, les tests avec un processus neuf, la vérification d'audit et le rapprochement. Il contient aussi un emplacement pour noter la question inconfortable qui arrive toujours : « Cette action s'est-elle terminée avant notre interruption ? »

Si vous ne pouvez pas répondre à cette question à partir de la transmission de l'agent, de l'enregistrement d'activité et du système cible, ne redémarrez pas l'agent avec l'autorisation de répéter l'action. Mettez la tâche en pause et clarifiez d'abord l'état externe. Cette discipline prend quelques minutes de plus et reste bien plus rapide que de démêler deux déploiements, deux changements d'accès ou une commande distante que l'agent et l'opérateur pensaient tous deux avoir arrêtée.

La première amélioration à apporter est simple : exigez de tout agent pouvant atteindre des systèmes externes qu'il laisse une transmission reprenable avant la maintenance. Une fois cette habitude installée, le calendrier des versions, l'autorisation, les tests de mise à jour et la récupération ne dépendent plus du souvenir que quelqu'un garde d'une fenêtre de terminal.