Skip to main content

Diagnostiquer un package qui ne se déploie pas

Lorsqu'un package Medulla ne se déploie pas, le problème peut intervenir à plusieurs étapes du processus :

  • avant le lancement du déploiement ;
  • pendant le transfert des fichiers ;
  • lors de l'interprétation du package ;
  • pendant l'exécution des commandes sur la machine ;
  • ou en raison d'une dépendance ou d'une condition du déploiement.

Information :
La première information à consulter est le statut du déploiement, puis le détail disponible dans l'audit. Le message d'audit permet souvent d'identifier directement l'étape qui pose problème.

1. Identifier à quelle étape le déploiement bloque

Commencez par relever le statut affiché dans Medulla.

Statut Interprétation
DEPLOYMENT PENDING Le déploiement est en attente de lancement
DEPLOYMENT SPOOLED Le déploiement est placé en file d'attente
WAITING MACHINE ONLINE La machine cible n'est pas disponible
ABORT TRANSFER FAILED Les fichiers du package n'ont pas pu être transférés
ERROR TRANSFER FAILED Le serveur de packages ne dispose pas du package demandé
ABORT MISSING DEPENDENCY Une dépendance du package est absente
ABORT PACKAGE WORKFLOW ERROR Le workflow ou le descriptor du package est incorrect
ABORT PACKAGE EXECUTION ERROR Une commande du package a échoué sur la machine
ABORT PACKAGE EXECUTION CANCELLED L'exécution a été annulée
ABORT ON TIMEOUT La plage de déploiement s'est terminée avant l'exécution

2. Consulter l'audit du déploiement

Avant toute modification du package, ouvrez l'audit du déploiement concerné.

Relevez notamment :

  • le statut exact ;
  • le dernier message affiché ;
  • l'UUID du package ;
  • la machine cible ;
  • le relais utilisé ;
  • l'étape du workflow atteinte ;
  • le retour de la commande lorsqu'il est disponible.

Conseil :
Le statut permet d'identifier la famille du problème, mais le message détaillé de l'audit permet souvent d'en connaître la cause exacte.

3. Vérifier que la machine est disponible

Si le déploiement reste dans :

WAITING MACHINE ONLINE

ou se termine par :

ABORT ON TIMEOUT

vérifiez tout d'abord que la machine cible est réellement disponible.

ping IP_DE_LA_MACHINE

Lorsqu'une machine est éteinte, Medulla effectue jusqu'à trois tentatives de Wake On LAN avant de passer dans l'état :

WAITING MACHINE ONLINE

Medulla attend ensuite que la machine revienne en ligne tant que la plage horaire du déploiement reste ouverte.

Si la machine ne revient pas avant la fin de cette plage, le déploiement peut se terminer par :

ABORT ON TIMEOUT

4. Le déploiement reste en PENDING

Le statut :

DEPLOYMENT PENDING

est un statut temporaire avant le lancement effectif du déploiement.

Une cause possible documentée est que tous les slots de déploiement disponibles sont déjà utilisés.

Pour connaître le nombre de déploiements en attente d'exécution :

SELECT
    COUNT(msc.commands.id) AS 'nb pending'
FROM
    msc.commands_on_host
INNER JOIN
    msc.commands
    ON msc.commands.id = msc.commands_on_host.fk_commands
INNER JOIN
    msc.target
    ON msc.target.id = msc.commands_on_host.fk_target
INNER JOIN
    msc.phase
    ON msc.phase.fk_commands_on_host = msc.commands_on_host.id
WHERE
    msc.phase.name = 'execute'
    AND msc.phase.state = 'ready'
    AND NOW() BETWEEN msc.commands.start_date
                  AND msc.commands.end_date;

Information :
Un statut DEPLOYMENT PENDING ne signifie donc pas nécessairement que le package est défectueux. Il peut simplement attendre qu'un slot d'exécution soit disponible.

5. Le déploiement reste en file d'attente

Le statut :

DEPLOYMENT SPOOLED

indique que le déploiement a été placé dans une file d'attente.

Le message associé peut être :

Spooling the deployment in queue

Il s'agit d'un statut dynamique et non d'une erreur du package en lui-même.

Si ce statut persiste anormalement longtemps, vérifiez les autres déploiements en cours ainsi que la disponibilité des ressources de déploiement.

6. Vérifier l'identifiant du package

Le statut :

ABORT PACKAGE IDENTIFIER MISSING

indique que l'UUID attendu du package est absent.

L'UUID du package peut être retrouvé dans l'audit du déploiement, dans les informations du package.

Vérifiez ensuite la présence de la clé uuid dans :

/var/lib/pulse2/packages/sharing/global/UUID_DU_PACKAGE/xmppdeploy.json

Par exemple :

grep -i "uuid" /var/lib/pulse2/packages/sharing/global/UUID_DU_PACKAGE/xmppdeploy.json

Si la clé UUID est absente, le document d'exploitation recommande de recréer le package.

7. Vérifier le nom et la version du package

Les statuts suivants indiquent que des informations obligatoires du package sont absentes :

ABORT PACKAGE NAME MISSING
ABORT PACKAGE VERSION MISSING

Les informations du package sont notamment stockées dans :

xmppdeploy.json

Si ce fichier est absent ou incomplet, le package a probablement été mal créé ou modifié.

Action recommandée :
Lorsque le nom, la version ou l'identifiant du package sont absents de sa configuration, il est préférable de recréer le package plutôt que de modifier manuellement sa structure.

8. Vérifier le workflow du package

Le statut :

ABORT PACKAGE WORKFLOW ERROR

indique une erreur dans le workflow du package.

Le document d'exploitation identifie notamment :

  • une étape de workflow inexistante ;
  • une incohérence dans xmppdeploy.json ;
  • un descriptor absent pour le système d'exploitation ;
  • une erreur lors de l'initialisation du workflow.

Les messages associés peuvent être :

Package error: descriptor for OS %s missing

Descriptor inconsistency error

Error initializing grafcet

Descriptor du système d'exploitation manquant

Le message :

Package error: descriptor for OS %s missing

peut apparaître lorsqu'un mauvais système d'exploitation a été choisi lors de la création du package ou lorsque le système attendu n'existe pas dans :

xmppdeploy.json

Action recommandée :
Vérifiez le système d'exploitation configuré dans le package et son workflow. Si la structure du package est incohérente, le document d'exploitation recommande de recréer le package.

9. Vérifier les dépendances du package

Le message :

Deployment error: missing dependency

correspond au statut :

ABORT MISSING DEPENDENCY

Il indique qu'une dépendance nécessaire au package n'est plus disponible.

Une cause documentée est qu'un package référencé comme dépendance a été supprimé.

Action recommandée

  • ouvrez la configuration du package ;
  • vérifiez les packages déclarés comme dépendances ;
  • assurez-vous que ces packages existent toujours ;
  • retirez ou remplacez toute dépendance devenue invalide.

10. Vérifier le transfert des fichiers

Si le transfert du package vers la machine échoue, le déploiement peut se terminer par :

ABORT TRANSFER FAILED

Le document d'exploitation indique que le problème peut notamment concerner :

  • un transfert rsync ;
  • un téléchargement avec curl ;
  • la disponibilité du package sur le serveur utilisé pour le déploiement.

Un message possible est :

Transfer error: curl download

Information :
Consultez toujours le message détaillé dans l'audit. ABORT TRANSFER FAILED indique l'étape ayant échoué, mais plusieurs causes techniques peuvent provoquer cette erreur.

11. Le serveur de packages ne possède pas le package

Le message :

Transfer error: Package Server does not have this package

correspond à une erreur de type :

ERROR TRANSFER FAILED

Dans ce cas, le serveur utilisé pour le transfert ne dispose pas du package attendu.

Vérifiez :

  • que le package existe toujours ;
  • qu'il est présent sur le serveur de packages ;
  • qu'il est disponible sur le relais utilisé pour le déploiement ;
  • que sa synchronisation s'est correctement effectuée.

Attention :
Le fait qu'un package soit visible dans la console Medulla ne garantit pas nécessairement qu'il soit présent sur le serveur ou le relais utilisé pour le transfert.

12. Vérifier la localisation du package

Le document d'exploitation décrit également un cas dans lequel un package peut se retrouver dans la localisation global alors qu'une autre localisation était attendue.

Dans ce cas, vérifiez le champ :

localisation_server

dans les fichiers :

conf.json
xmppdeploy.json

Si la localisation est incorrecte, cela peut expliquer pourquoi le package n'est pas disponible à l'endroit attendu.

Attention :
Le document d'exploitation contient également des commandes permettant de modifier directement les fichiers et la base de données. Pour une documentation publique de diagnostic, il est recommandé de commencer par identifier l'incohérence et de ne modifier la localisation qu'après avoir confirmé la configuration attendue.

13. Vérifier l'exécution des commandes du package

Le statut :

ABORT PACKAGE EXECUTION ERROR

indique que le package a bien atteint l'étape d'exécution mais qu'une commande a échoué sur la machine cible.

Le message associé peut être :

Package execution error

ou, dans certains cas :

Package delayed execution error

Le document d'exploitation précise qu'une commande peut fonctionner sur une machine et échouer sur une autre.

L'erreur ne provient donc pas nécessairement du moteur de déploiement Medulla, mais peut être liée à la commande exécutée ou à l'environnement de la machine.

14. Afficher le retour complet des commandes

Pour diagnostiquer :

ABORT PACKAGE EXECUTION ERROR

éditez le package et configurez l'affichage du résultat complet de la commande.

Après un nouveau déploiement, le retour de la commande sera disponible dans l'audit.

Il permettra notamment d'identifier :

  • un code de retour en erreur ;
  • une commande inconnue ;
  • un fichier absent ;
  • un problème propre à la machine cible ;
  • le message exact retourné par le programme exécuté.

Recommandation :
Lorsqu'un package fonctionne sur certaines machines mais pas sur d'autres, l'affichage du résultat complet de la commande dans l'audit constitue le contrôle prioritaire.

15. Cas d'une erreur d'inventaire pendant l'exécution

Le document d'exploitation recense également le message :

Deployment aborted: inventory error

associé à :

ABORT PACKAGE EXECUTION ERROR

Ce message indique que l'échec est intervenu pendant une opération d'inventaire liée au déploiement.

Information :
Le document d'exploitation identifie ce message mais ne fournit pas de procédure corrective plus détaillée. Dans ce cas, le diagnostic doit être poursuivi à partir de l'audit du déploiement et des logs de la machine concernée.

16. Vérifier si l'exécution a été annulée

Le statut :

ABORT PACKAGE EXECUTION CANCELLED

indique que l'exécution du package a été annulée.

Le message associé peut être :

Package delayed execution cancelled

Le document d'exploitation donne comme exemple un déploiement différé pour lequel le nombre de machines attendu n'a pas été atteint.

Dans ce cas, vérifiez les conditions configurées pour le déploiement plutôt que le contenu du package.

17. Vérifier si le package demande un redémarrage

Le statut :

WAITING REBOOT

indique qu'un redémarrage volontaire de la machine a été demandé dans le package.

Il ne s'agit donc pas d'une erreur.

Vérifiez le workflow du package afin de confirmer que cette étape de redémarrage est bien attendue.

18. Tester le package sur une autre machine

Lorsque le package fonctionne sur une machine mais pas sur une autre, cela oriente le diagnostic vers la machine cible ou vers la commande exécutée.

Le document d'exploitation indique explicitement qu'une commande présente dans un package peut fonctionner correctement sur une machine mais échouer sur une autre.

Dans cette situation :

  1. activez l'affichage complet du résultat de la commande ;
  2. relancez le package sur la machine en erreur ;
  3. comparez le retour avec celui d'une machine sur laquelle le déploiement fonctionne.

19. Arbre de diagnostic rapide

Symptôme Vérification prioritaire
Package en PENDING Vérifier les déploiements en attente et les slots disponibles
Package en SPOOLED Vérifier la file d'attente des déploiements
WAITING MACHINE ONLINE Vérifier que la machine est disponible
ABORT ON TIMEOUT Vérifier la machine et la plage horaire de déploiement
ABORT PACKAGE IDENTIFIER MISSING Vérifier l'UUID dans xmppdeploy.json
ABORT PACKAGE NAME MISSING Vérifier la structure du package
ABORT PACKAGE VERSION MISSING Vérifier la structure du package
ABORT PACKAGE WORKFLOW ERROR Vérifier le workflow et le descriptor
ABORT MISSING DEPENDENCY Vérifier les dépendances du package
ABORT TRANSFER FAILED Consulter le message de transfert dans l'audit
ERROR TRANSFER FAILED Vérifier que le serveur de packages dispose du package
ABORT PACKAGE EXECUTION ERROR Afficher le résultat complet de la commande
ABORT PACKAGE EXECUTION CANCELLED Vérifier les conditions du déploiement
WAITING REBOOT Vérifier l'étape de redémarrage du package

20. Procédure de diagnostic recommandée

Lorsqu'un package ne se déploie pas, effectuez les contrôles suivants dans cet ordre :

  1. ouvrir l'audit du déploiement ;
  2. identifier le statut exact ;
  3. vérifier que la machine cible est disponible ;
  4. vérifier si le déploiement est simplement en attente ou en file ;
  5. contrôler l'UUID, le nom et la version du package ;
  6. contrôler le workflow et le descriptor ;
  7. vérifier les dépendances ;
  8. si le transfert échoue, vérifier la disponibilité du package sur le serveur ou le relais ;
  9. si l'exécution échoue, activer le retour complet des commandes ;
  10. comparer le comportement avec une autre machine lorsque cela est possible.

21. Informations à collecter si le problème persiste

Avant de poursuivre le diagnostic ou d'ouvrir un ticket support, collectez :

  • le nom du package ;
  • son UUID ;
  • la machine cible ;
  • le statut exact du déploiement ;
  • le message complet affiché dans l'audit ;
  • le serveur relais utilisé ;
  • le résultat complet de la commande en cas d'erreur d'exécution ;
  • les dépendances du package ;
  • la date et l'heure du déploiement ;
  • l'information indiquant si le même package fonctionne sur une autre machine.

Recommandation :
Pour diagnostiquer un package qui ne se déploie pas, commencez toujours par identifier l'étape qui échoue : attente, transfert, lecture du package ou exécution. Un problème de transfert doit être diagnostiqué côté disponibilité du package et relais, alors qu'un ABORT PACKAGE EXECUTION ERROR doit être diagnostiqué à partir du retour complet de la commande dans l'audit.

Back to top