Azure Arc : diagnostiquer une extension en échec après un changement de proxy

Une règle proxy change pendant la nuit. Le serveur Azure Arc reste visible dans le portail, mais l’extension Azure Monitor Agent passe en échec sur une partie du parc. Relancer le déploiement ne change rien. Réinstaller le Connected Machine agent rétablit parfois un serveur, sans expliquer pourquoi les autres restent bloqués.

Le piège est de traiter « Azure Arc connecté » comme une preuve de bout en bout. Le canal de contrôle, le gestionnaire d’extensions, le téléchargement du package et le handler de l’extension n’empruntent pas nécessairement le même chemin. Ce runbook isole ces couches avant toute ouverture réseau ou réinstallation massive.

Figer le périmètre avant de relancer

Choisissez un serveur en échec et un serveur sain comparables : même site, même système, même version d’agent, même extension et même fenêtre de changement. Une comparaison contrôlée vaut mieux qu’une collecte globale qui mélange plusieurs causes.

Incident: inc-2026-08-11-arc-proxy
Changement: nouvelle URL proxy et nouvelle liste de bypass
Serveur en echec: srv-app-042
Serveur temoin: srv-app-017
Extension: AzureMonitorLinuxAgent
Version demandee et version observee
Heure UTC du dernier succes
Heure UTC du premier echec

Preuves attendues
Etat Arc et services dependants
Proxy effectif, bypass et version de l'agent
Resultat des tests vers les endpoints requis
Operation Azure et message de provisioning
Log du gestionnaire d'extensions
Log et statut du handler concerne
Decision: corriger, maintenir, retenter ou rollbacker

N’utilisez pas immédiatement « supprimer puis recréer » comme test. Cette action efface une partie de la chronologie utile et peut déclencher un nouveau téléchargement qui masque la panne initiale.

Séparer connexion Arc et chaîne d’extension

Sur le serveur en échec, commencez par l’état que voit réellement l’agent. azcmagent show expose notamment la connexion, les services dépendants, la version et la configuration proxy effective. azcmagent check teste les endpoints requis et indique si le chemin utilise un proxy, un endpoint privé ou une passerelle Arc selon la configuration.

sudo azcmagent show
sudo azcmagent config get proxy.url
sudo azcmagent config get proxy.bypass
sudo azcmagent check
sudo azcmagent check --extensions all

# Conserver les sorties avec l'heure UTC, le nom du serveur et la version de l'agent.
# Executer exactement les memes commandes sur le serveur temoin.

Interprétez les résultats par couche :

• azcmagent show déconnecté ou services dépendants arrêtés : rétablir d’abord le Connected Machine agent ;
• contrôle Arc sain mais check --extensions all en échec : qualifier proxy, DNS, inspection TLS et destinations propres aux extensions ;
• tests réseau sains mais provisioning en échec : passer aux logs du gestionnaire et du handler ;
• un seul handler en échec : éviter une modification globale du proxy ou de l’agent.

Le test doit partir du serveur concerné. Un curl depuis un bastion ou un poste d’administration ne prouve ni le proxy effectif de l’agent, ni l’identité du processus, ni la chaîne de certificats vue par le handler.

Vérifier le proxy effectif, pas seulement la configuration prévue

La configuration locale proxy.url du Connected Machine agent prend le pas sur les variables d’environnement système lorsqu’elle est définie. Une procédure peut donc avoir modifié HTTPS_PROXY sans changer le chemin réellement utilisé par l’agent. À l’inverse, certaines extensions n’héritent pas du proxy spécifique à l’agent et doivent être validées selon leur propre documentation.

Comparez le serveur sain et le serveur en échec sur quatre points : URL effective, liste de bypass, résolution DNS du proxy et certificat présenté après éventuelle inspection TLS. Vérifiez aussi que le proxy accepte les méthodes et destinations attendues, sans supposer qu’un simple accès HTTPS générique suffit.

Agent deconnecte et endpoint Arc bloque
Corriger le chemin du Connected Machine agent
Ne pas toucher a l'extension tant que Arc n'est pas stable

Agent connecte, endpoints extension bloques
Corriger la politique proxy ou firewall ciblee
Verifier les destinations specifiques de l'extension

Agent connecte, reseau sain, telechargement refuse
Examiner authentification proxy, inspection TLS et validation du package

Package telecharge, handler en echec
Diagnostiquer l'extension, le systeme et ses prerequis
Ne pas elargir les flux reseau sans preuve

Une liste de bypass trop large n’est pas un rollback acceptable. Elle peut restaurer le service tout en contournant le contrôle réseau attendu. Le rollback doit revenir à une configuration précédente identifiée, avec une fenêtre et un propriétaire.

Lire les deux niveaux de logs

Le gestionnaire d’extensions écrit les erreurs de téléchargement, de vérification et d’orchestration dans gc_ext.log. Sous Linux, cherchez-le dans /var/lib/GuestConfig/ext_mgr_logs/. Sous Windows, utilisez %ProgramData%\GuestConfig\ext_mgr_logs\. Ensuite seulement, ouvrez les logs et fichiers de statut propres à l’extension.

sudo tail -n 250 /var/lib/GuestConfig/ext_mgr_logs/gc_ext.log
sudo find /var/lib/GuestConfig -maxdepth 4 -type f -mmin -120 -print
sudo find /var/lib/waagent -maxdepth 5 -type f -mmin -120 -print

# Rechercher l'operation et l'heure de provisioning, pas seulement le mot "error".
# Ne pas copier de settings proteges ni de secrets dans le dossier d'incident.

La distinction est décisive :

• échec avant création du répertoire du handler : téléchargement, signature, proxy ou orchestration ;
• package présent mais installation non nulle : prérequis OS, montage noexec, gestionnaire de paquets ou script du handler ;
• installation réussie mais état non sain : configuration de l’extension ou accès à sa propre destination ;
• opération Azure absente des logs locaux : vérifier le canal de contrôle, le ciblage de ressource et les opérations concurrentes.

Conservez l’identifiant de corrélation, l’horodatage UTC et le code de sortie. Un extrait sans ces éléments est difficile à rapprocher de l’Activity Log et de l’état Azure.

Appliquer une correction minimale

La correction dépend du premier point de rupture confirmé. Modifiez une seule variable à la fois sur le serveur témoin en échec : configuration proxy de l’agent, règle de destination, chaîne de certificats, montage local ou prérequis du handler.

Si le proxy spécifique à l’agent est en cause, capturez sa valeur actuelle avant le changement. La commande azcmagent config set proxy.url applique une nouvelle URL sans redémarrage de service ; config clear proxy.url rend à nouveau la main au mécanisme de repli configuré sur l’hôte. Ne l’utilisez pas sans connaître ce repli.

Retentez ensuite le même déploiement d’extension via l’IaC ou l’automatisation qui fait autorité. Évitez une installation manuelle qui créerait un état différent du parc.

Valider, généraliser ou rollbacker

Une extension marquée Succeeded n’est pas la seule condition de sortie. Validez aussi la fonction attendue : télémétrie reçue, politique appliquée, script terminé ou contrôle de sécurité actif. Surveillez le serveur témoin pendant une fenêtre suffisante, puis élargissez par lot limité.

Conserver la correction
Arc reste connecte
Les tests endpoints passent par le chemin attendu
Le gestionnaire telecharge et verifie le package
Le handler termine sans erreur
La fonction de l'extension est validee
Aucun bypass large ni secret n'a ete ajoute

Rollbacker
La connectivite Arc regresse
Le proxy est contourne au-dela du perimetre approuve
D'autres extensions cessent de fonctionner
La correction exige une confiance TLS non maitrisee
Le serveur temoin diverge de la configuration geree

Escalader sans reinstaller
Le package est telecharge mais le handler echoue de facon reproductible
Les logs, versions, codes de sortie et identifiants sont conserves
Le reseau et le service d'extensions sont prouves sains

Le rollback remet l’ancienne URL et l’ancienne liste de bypass, reteste azcmagent check, puis confirme que les autres extensions n’ont pas régressé. Si l’extension reste en échec alors que la couche réseau est saine, la réinstallation devient une action ciblée, documentée et non un réflexe de premier niveau.

Conclusion

Une extension Azure Arc en échec après un changement de proxy n’implique pas que le Connected Machine agent soit corrompu. Il faut prouver séparément le canal Arc, le chemin réseau des extensions, le gestionnaire de packages et le handler.

La décision opérationnelle est simple : conserver uniquement la correction qui rétablit l’extension sur un serveur témoin sans élargir le bypass ni dégrader les autres composants. Sinon, rollbacker le proxy, garder les preuves et poursuivre au premier niveau de la chaîne encore non confirmé.