Kennen Sie das? Sie haben mit viel Mühe eine komplexe Azure DevOps Pipeline entworfen, die Ihre CI/CD-Prozesse automatisiert. Alles scheint perfekt, doch plötzlich stoßen Sie auf einen hartnäckigen Fehler, der den gesamten Workflow zum Erliegen bringt: „CLI 2 is not installed on this machine”. Dieser Satz kann besonders frustrierend sein, wenn Sie glauben, einen „Managed DevOps Pool” zu nutzen, bei dem Microsoft sich um die Installation der Tools kümmern sollte. Aber keine Sorge, Sie sind nicht allein mit diesem Problem. Dieser Artikel ist Ihr umfassender Leitfaden, um die Ursachen dieses Fehlers zu verstehen und ihn systematisch zu beheben.
Wir tauchen tief in die Welt der Azure Pipelines ein, beleuchten die Funktionsweise von Microsoft-gehosteten Agenten und zeigen Ihnen Schritt für Schritt, wie Sie Ihre Pipeline wieder zum Laufen bringen. Machen Sie sich bereit, dieses Hindernis aus dem Weg zu räumen und Ihre DevOps-Ziele zu erreichen!
Was bedeutet „CLI 2 is not installed”? Eine Einführung in Azure CLI und Managed Pools
Bevor wir uns den Lösungen widmen, ist es wichtig, die Fehlermeldung genau zu verstehen. „CLI 2” bezieht sich in diesem Kontext fast immer auf die Azure Command-Line Interface (Azure CLI), Version 2.x. Die Azure CLI ist ein leistungsstarkes plattformübergreifendes Befehlszeilentool, das es Ihnen ermöglicht, Azure-Ressourcen direkt über Ihr Terminal oder in Skripten zu verwalten. Ob das Bereitstellen von virtuellen Maschinen, das Konfigurieren von Speicherkonten oder das Verwalten von Web-Apps – die Azure CLI ist ein unverzichtbares Werkzeug für Entwickler und DevOps-Ingenieure.
Die Fehlermeldung besagt also, dass das benötigte Azure CLI v2 auf der Maschine, die Ihre Pipeline-Aufgabe ausführt, nicht gefunden wurde. Aber warum passiert das in einem „Managed DevOps Pool”?
Microsoft-gehostete Agenten vs. Selbstgehostete Agenten
Der Begriff „Managed DevOps Pool” bezieht sich in der Regel auf die von Microsoft bereitgestellten Microsoft-gehosteten Agenten. Diese Agenten sind vorgefertigt und enthalten eine Vielzahl von gängigen Tools und SDKs, darunter in der Regel auch die Azure CLI. Der Vorteil ist, dass Sie sich nicht um die Wartung oder Skalierung der Agent-Infrastruktur kümmern müssen.
Im Gegensatz dazu stehen selbstgehostete Agenten, die Sie auf Ihrer eigenen Infrastruktur (virtuelle Maschinen, Container) betreiben. Hier sind Sie selbst für die Installation und Wartung aller benötigten Tools, einschließlich der Azure CLI, verantwortlich.
Wenn die Fehlermeldung in einem *Microsoft-gehosteten* Pool auftritt, liegt der Fehler selten daran, dass die Azure CLI *grundsätzlich* fehlt, sondern eher an einer speziellen Anforderung, einer veralteten Task-Version oder einem Missverständnis darüber, wie die CLI im Kontext Ihrer Pipeline aufgerufen wird.
Erste Schritte zur Fehleranalyse: Wo anfangen?
Bevor Sie in komplizierte Lösungen eintauchen, sollten Sie einige grundlegende Überprüfungen durchführen. Diese können oft schon die Ursache ans Licht bringen.
1. Pipeline-Logs genau prüfen
Die Pipeline-Logs sind Ihre beste Freundin bei der Fehlersuche. Suchen Sie nach der exakten Aufgabe, die fehlschlägt, und analysieren Sie die Zeilen davor und danach. Manchmal geben andere Warnungen oder Hinweise Aufschluss über das Problem. Die Fehlermeldung „CLI 2 is not installed” erscheint oft als Output eines Skripts oder einer Task, die versucht, den Befehl az auszuführen.
2. Agent-Spezifikation überprüfen
Welchen Agent-Typ verwenden Sie? In Ihrer YAML-Datei sollte dies unter pool: vmImage: definiert sein. Gängige Images sind ubuntu-latest, windows-latest oder vs2019-windows. Microsoft-gehostete Agenten werden regelmäßig aktualisiert und sollten die Azure CLI enthalten. Überprüfen Sie die Dokumentation der Runner-Images auf GitHub, um zu sehen, welche Tools und Versionen auf den aktuellen Agent-Images vorinstalliert sind.
3. Verwendete Azure CLI Task-Version
Wenn Sie eine dedizierte Azure CLI Task verwenden, überprüfen Sie deren Version. Die gängige und empfohlene Task ist AzureCLI@2. Wenn Sie versehentlich eine ältere Version wie AzureCLI@1 verwenden oder ein generisches Skript, das az aufruft, könnte dies der Grund sein.
Detaillierte Ursachen und Lösungen
Nach den ersten Überprüfungen gehen wir nun tiefer ins Detail und betrachten die häufigsten Ursachen für den Fehler „CLI 2 is not installed” und ihre jeweiligen Lösungen.
Ursache 1: Die Azure CLI ist nicht (richtig) auf dem Agenten verfügbar oder nicht im PATH
Obwohl Microsoft-gehostete Agenten die Azure CLI in der Regel vorinstalliert haben, kann es in seltenen Fällen vorkommen, dass sie aus einem bestimmten Grund nicht in der erwarteten Version oder nicht im System-PATH verfügbar ist, insbesondere wenn Sie eine sehr spezifische oder ältere Agent-Version anfordern oder die Pipeline in einer untypischen Umgebung läuft.
Lösung: Explizite Installation der Azure CLI
Dies ist oft die robusteste und zuverlässigste Lösung, selbst wenn die CLI eigentlich vorinstalliert sein sollte. Sie können die Azure CLI explizit als Teil Ihrer Pipeline installieren. Dafür gibt es zwei Hauptmethoden:
-
Verwendung des
AzureCLIInstaller@0Tasks: Dies ist die empfohlene Methode in Azure Pipelines. Dieser Task wurde speziell entwickelt, um die Azure CLI auf dem Agenten zu installieren oder eine bestimmte Version sicherzustellen.- task: AzureCLIInstaller@0 displayName: 'Install Azure CLI' inputs: azureCliVersion: 'latest' # Oder eine spezifische Version, z.B. '2.50.0'Platzieren Sie diesen Task *vor* jedem anderen Task oder Skript, das die Azure CLI verwendet. Durch die Angabe von
lateststellen Sie sicher, dass immer die aktuellste Version installiert wird. Wenn Sie jedoch eine feste, reproduzierbare Umgebung benötigen, sollten Sie eine spezifische Versionsnummer angeben. -
Manuelle Installation über ein Skript (Bash/PowerShell): Wenn Sie mehr Kontrolle wünschen oder der
AzureCLIInstaller@0Task aus irgendeinem Grund nicht ausreicht, können Sie die Azure CLI auch über ein benutzerdefiniertes Skript installieren. Dies ist besonders nützlich für selbstgehostete Agenten, kann aber auch auf Microsoft-gehosteten Agenten funktionieren.Für Linux-Agenten (z.B.
ubuntu-latest):- script: | curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash displayName: 'Install Azure CLI (Linux)' condition: eq(variables['Agent.OS'], 'Linux') # Nur auf Linux-Agenten ausführenFür Windows-Agenten (z.B.
windows-latest):- powershell: | Invoke-WebRequest -Uri https://aka.ms/installazurecliwindows -OutFile AzInstaller.msi; ` Start-Process -FilePath msiexec.exe -ArgumentList "/i AzInstaller.msi /quiet" -Wait; ` Remove-Item AzInstaller.msi displayName: 'Install Azure CLI (Windows)' condition: eq(variables['Agent.OS'], 'Windows') # Nur auf Windows-Agenten ausführenBeachten Sie, dass diese Skripte die Azure CLI global installieren. Stellen Sie sicher, dass der Benutzer, unter dem der Agent-Dienst läuft, die Berechtigung zur Installation hat, falls es sich um einen selbstgehosteten Agent handelt.
Ursache 2: Verwendung eines generischen Skript-Tasks anstelle des dedizierten Azure CLI Tasks
Manchmal versuchen Entwickler, Azure CLI-Befehle direkt in einem generischen script– oder powershell-Task auszuführen, anstatt den spezialisierten AzureCLI@2-Task zu verwenden. Während dies technisch möglich ist, bietet der AzureCLI@2-Task Vorteile wie die automatische Authentifizierung und das Einrichten der Umgebung.
Lösung: Verwenden Sie AzureCLI@2 für Azure CLI-Befehle
Wenn Sie Azure CLI-Befehle ausführen, die eine Authentifizierung gegenüber Azure erfordern, ist es am besten, den dedizierten Task zu verwenden. Dieser Task nimmt eine Azure Resource Manager service connection entgegen und authentifiziert sich automatisch.
- task: AzureCLI@2
displayName: 'Execute Azure CLI Command'
inputs:
azureSubscription: 'Ihre_Dienstverbindung_Hier' # Name Ihrer Service Connection
scriptType: 'bash' # oder 'pscore' für PowerShell Core auf Linux/macOS, 'ps' für PowerShell auf Windows
scriptLocation: 'inlineScript'
inlineScript: |
az account show
az group list --output table
# Ihre weiteren Azure CLI Befehle hier
Wenn Sie nur einen einzelnen Befehl ausführen möchten, der keine Authentifizierung erfordert (z.B. az --version), können Sie auch ein einfaches script verwenden, *nachdem* Sie sichergestellt haben, dass die CLI installiert ist.
Ursache 3: Authentifizierungsprobleme maskieren den Fehler
In seltenen Fällen kann die Fehlermeldung „CLI 2 is not installed” irreführend sein und eigentlich ein Problem mit der Authentifizierung oder den Berechtigungen der Dienstverbindung (Service Connection) verschleiern. Die CLI ist zwar installiert, kann aber die angeforderten Azure-Operationen nicht ausführen, was zu einem generischen Fehler führt.
Lösung: Überprüfen Sie Ihre Azure Service Connection
Stellen Sie sicher, dass Ihre Azure Resource Manager service connection korrekt konfiguriert ist und der zugrunde liegende Service Principal über die notwendigen Berechtigungen in Ihrem Azure-Abonnement verfügt. Testen Sie die Verbindung und überprüfen Sie die Gültigkeit des Service Principals im Azure Portal (Azure Active Directory -> App-Registrierungen).
- Ist der Client Secret abgelaufen?
- Hat der Service Principal die erforderlichen Rollen (z.B. „Mitwirkender” für die Ressourcengruppe oder das Abonnement)?
Wenn die Service Connection fehlerhaft ist, kann der AzureCLI@2 Task nicht initialisiert werden und könnte indirekt zu einem Fehler führen, der fälschlicherweise auf die fehlende CLI hinweist.
Ursache 4: Veraltete oder nicht mehr unterstützte Agent-Images
Obwohl selten, ist es möglich, dass Sie ein sehr spezifisches oder älteres Agent-Image verwenden, das möglicherweise nicht die erwarteten Tools enthält oder von Microsoft nicht mehr aktiv gepflegt wird.
Lösung: Aktualisieren Sie Ihr Agent-Image
Stellen Sie sicher, dass Sie ein aktuelles und gut gewartetes Agent-Image verwenden, wie z.B. ubuntu-latest oder windows-latest. Diese Images werden regelmäßig aktualisiert und enthalten die neuesten Versionen der gängigen Tools. Wenn Sie eine feste Version (z.B. ubuntu-20.04) verwenden, überprüfen Sie, ob diese noch aktiv unterstützt wird und aktualisieren Sie sie bei Bedarf auf eine neuere stabile Version (z.B. ubuntu-22.04).
Ursache 5: Konflikte mit Environment-Variablen oder Shell-Umgebung
Manchmal können Skripte oder vorangehende Tasks die Umgebungsvariablen oder den PATH auf dem Agenten so manipulieren, dass die Azure CLI nicht mehr gefunden wird.
Lösung: Isolierte Skript-Ausführung und PATH-Debugging
Wenn Sie vermuten, dass dies der Fall ist, versuchen Sie:
- Skripte in isolierten Schritten ausführen: Manchmal hilft es, Installation und Ausführung in separate Tasks aufzuteilen.
- PATH-Variable debuggen: Fügen Sie einen Debugging-Schritt in Ihre Pipeline ein, um den Inhalt der PATH-Variable anzuzeigen:
- script: echo "PATH: $PATH" displayName: 'Show PATH (Linux)' condition: eq(variables['Agent.OS'], 'Linux') - powershell: Write-Host "PATH: $env:PATH" displayName: 'Show PATH (Windows)' condition: eq(variables['Agent.OS'], 'Windows')Prüfen Sie, ob der Pfad zur Azure CLI (z.B.
/usr/binoderC:Program Files (x86)Microsoft SDKsAzureCLI2wbin) korrekt enthalten ist.
Best Practices zur Vermeidung des CLI-Fehlers
Vorbeugen ist besser als Heilen. Hier sind einige Best Practices, um den „CLI 2 is not installed”-Fehler in Zukunft zu vermeiden:
-
Immer
AzureCLIInstaller@0verwenden: Wenn Ihre Pipeline stark von der Azure CLI abhängt, ist es eine gute Praxis, denAzureCLIInstaller@0Task am Anfang des Jobs auszuführen. Dies stellt sicher, dass die CLI in der gewünschten Version vorhanden und verfügbar ist, unabhängig von der Vorinstallation des Agenten.jobs: - job: BuildAndDeploy displayName: 'Build and Deploy Application' pool: vmImage: 'ubuntu-latest' # Oder 'windows-latest' steps: - task: AzureCLIInstaller@0 displayName: 'Ensure Azure CLI is installed' inputs: azureCliVersion: 'latest' # Oder eine spezifische Version - task: AzureCLI@2 displayName: 'Run Azure CLI commands' inputs: azureSubscription: 'MyAzureServiceConnection' scriptType: 'bash' inlineScript: | az group create --name my-resource-group --location eastus # ... weitere Befehle -
Agent-Images fixieren: Anstatt
ubuntu-latestoderwindows-latestzu verwenden, die sich regelmäßig ändern, können Sie eine spezifische Version wieubuntu-22.04oderwindows-2022angeben. Dies sorgt für mehr Reproduzierbarkeit in Ihrer Build-Umgebung. Denken Sie jedoch daran, diese Versionen regelmäßig zu überprüfen und zu aktualisieren, um von den neuesten Sicherheitsupdates und Tools zu profitieren. -
Lokales Testen: Testen Sie Ihre Azure CLI-Skripte und -Befehle lokal auf einer Umgebung, die der Pipeline-Agenten-Umgebung so nahe wie möglich kommt. Dies hilft, Syntaxfehler oder Berechtigungsprobleme frühzeitig zu erkennen.
-
Regelmäßige Überprüfung: Überprüfen Sie regelmäßig die Microsoft Azure DevOps Release Notes und die Dokumentation der Agent-Images, um über Änderungen an den vorinstallierten Tools oder potenziellen Breaking Changes informiert zu sein.
Fazit: Systematisch zur Lösung
Der Fehler „CLI 2 is not installed on this machine” in einem Azure Managed DevOps Pool kann anfangs entmutigend wirken, ist aber in den allermeisten Fällen mit einer systematischen Herangehensweise lösbar. Die Kernursache liegt oft in der Erwartungshaltung an die Vorinstallation auf dem Agenten oder in der Art und Weise, wie die Azure CLI in der Pipeline aufgerufen wird.
Indem Sie die Pipeline-Logs sorgfältig analysieren, die korrekten Agent-Spezifikationen und Azure CLI Task-Versionen verwenden und bei Bedarf die Azure CLI explizit installieren, können Sie Ihre Azure Pipeline schnell wieder in einen funktionierenden Zustand versetzen. Denken Sie daran, Best Practices wie die Verwendung des AzureCLIInstaller@0-Tasks und das Fixieren von Agent-Images zu implementieren, um zukünftige Probleme proaktiv zu vermeiden.
Mit diesem umfassenden Wissen sind Sie bestens gerüstet, um diesen spezifischen DevOps-Stolperstein zu überwinden und Ihre CI/CD-Prozesse reibungslos am Laufen zu halten. Viel Erfolg beim Meistern Ihrer Pipelines!