Bereitstellen von Agents für Bereitstellungsgruppen

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019

Mit Bereitstellungsgruppen lassen sich logische Gruppen von Zielcomputern für die Bereitstellung einfach definieren. Zudem wird der erforderliche Agent auf den einzelnen Computern installiert. In diesem Artikel wird erläutert, wie Sie eine Bereitstellungsgruppe erstellen und wie Sie den Agent auf jedem virtuellen oder physischen Computer in Ihrer Bereitstellungsgruppe installieren und bereitstellen.

Sie können den Agent auf eine der folgenden Arten installieren:

• Führen Sie das Skript aus, das automatisch generiert wird, wenn Sie eine Bereitstellungsgruppe erstellen.
• Installieren Sie die Azure-VM-Erweiterung für den Azure Pipelines-Agent auf allen VMs.
• Verwenden Sie die Aufgabe ARM-Vorlagenbereitstellung in Ihrer Releasepipeline.

Informationen zu Agents und Pipelines finden Sie unter folgenden Links:

• Parallelaufträge in Azure Pipelines
• Preise für Azure DevOps

Ausführen des Installationsskripts auf den Zielservern

1. Wählen Sie auf der Registerkarte Bereitstellungsgruppen von Azure Pipelines die Option +Neu aus, um eine neue Gruppe zu erstellen.

2. Geben Sie einen Namen für die Gruppe und optional eine Beschreibung ein, und wählen Sie dann Erstellen aus.

3. Wählen Sie auf der nächsten Seite im Abschnitt Computer mithilfe der Befehlszeile registrieren das Betriebssystem des Zielcomputers aus.

4. Wählen Sie Verwenden Sie für die Authentifizierung ein persönliches Zugriffstoken im Skript aus. Weitere Informationen

5. Wählen Sie Skript in die Zwischenablage kopieren aus.

6. Melden Sie sich nacheinander auf jedem Zielcomputer mit dem Konto mit den entsprechenden Berechtigungen an, und führen Sie die folgenden Schritte aus:

   • Öffnen Sie eine PowerShell-Administratoreingabeaufforderung, fügen Sie das kopierte Skript ein, und führen Sie es aus, um den Computer bei dieser Gruppe zu registrieren.

   • Wenn beim Ausführen des Skripts eine Fehlermeldung mit dem Hinweis angezeigt wird, dass kein sicherer Kanal erstellt werden konnte, führen Sie diesen Befehl an der PowerShell-Administratoreingabeaufforderung aus:

     [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

   • Wenn Sie zum Konfigurieren von Tags für den Agent aufgefordert werden, drücken Sie Y, und geben Sie alle Tags ein, mit denen Sie Teilmengen der Computer in der Gruppe für partielle Bereitstellungen ermitteln möchten.

     Mit den von Ihnen zugewiesenen Tags können Sie die Bereitstellung auf bestimmte Server beschränken, wenn die Bereitstellungsgruppe im Auftrag Für Computergruppe ausführen verwendet wird.

   • Wenn Sie zur Eingabe des Benutzerkontos aufgefordert werden, drücken Sie die EINGABETASTE , um die Standardwerte zu übernehmen.

   • Warten Sie, bis das Skript mit der folgenden Nachricht abgeschlossen wurde: Service vstsagent.{organization-name}.{computer-name} started successfully.

7. Öffnen Sie auf der Seite Bereitstellungsgruppen von Azure Pipelines die Registerkarte Computer, und überprüfen Sie, ob die Agents ausgeführt werden. Wenn die von Ihnen konfigurierten Tags nicht sichtbar sind, aktualisieren Sie die Seite.

Installieren der Azure-VM-Erweiterung für den Azure Pipelines-Agent

1. Wählen Sie auf der Registerkarte Bereitstellungsgruppen von Azure Pipelines die Option +Neu aus, um eine neue Gruppe zu erstellen.

2. Geben Sie einen Namen für die Gruppe und optional eine Beschreibung ein, und wählen Sie dann Erstellen aus.

3. Öffnen Sie im Azure-Portal für jeden virtuellen Computer, der in der Bereitstellungsgruppe enthalten sein wird, das Blatt Erweiterung, wählen Sie + Hinzufügen aus, um die Liste Neue Ressource zu öffnen, und wählen Sie Azure Pipelines-Agent aus.

   

4. Geben Sie auf dem Blatt Erweiterung installieren den Namen des zu verwendenden Azure Pipelines-Abonnements an. Wenn die URL beispielsweise https://dev.azure.com/contoso lautet, geben Sie einfach contoso an.

5. Geben Sie den Projektnamen und den Bereitstellungsgruppennamen an.

6. Geben Sie optional einen Namen für den Agent an. Wird kein Name angegeben, wird der VM-Name verwendet, an den -DG angefügt wird.

7. Geben Sie das persönliche Zugriffstoken (Personal Access Token, PAT) ein, das für die Authentifizierung bei Azure Pipelines verwendet werden soll.

8. Geben Sie optional eine durch Trennzeichen getrennte Liste von Tags an, die für den Agent konfiguriert werden. Bei Tags wird die Groß-/Kleinschreibung nicht beachtet, und die Tags dürfen nicht mehr als 256 Zeichen lang sein.

9. Wählen Sie OK aus, um mit der Installation des Agents auf dieser VM zu beginnen.

10. Fügen Sie die Erweiterung allen anderen VMs hinzu, die Sie in diese Bereitstellungsgruppe aufnehmen möchten.

Verwenden der Aufgabe „ARM-Vorlagenbereitstellung“

Wichtig

Diese Anweisungen beziehen sich auf Version 2 der Aufgabe. Ändern Sie Ihre Aufgabenversion von 3 in 2.

Mit der Aufgabe „ARM-Vorlagenbereitstellung“ können Sie eine ARM-Vorlage (Azure Resource Manager) bereitstellen, die die Azure-VM-Erweiterung für den Azure Pipelines-Agent beim Erstellen eines virtuellen Computers installiert, oder die Ressourcengruppe aktualisieren, um die Erweiterung nach der Erstellung des virtuellen Computers anzuwenden. Alternativ können Sie die erweiterten Bereitstellungsoptionen der Aufgabe für die ARM-Vorlagenbereitstellung verwenden, um den Agent in Bereitstellungsgruppen bereitzustellen.

Installieren der Azure-VM-Erweiterung „Azure Pipelines-Agent“ mithilfe einer ARM-Vorlage

Eine ARM-Vorlage ist eine JSON-Datei, die Azure-Ressourcen deklarativ definiert. Die Vorlage kann automatisch gelesen werden, und die Ressourcen können von Azure bereitgestellt werden. In einer Vorlage können Sie mehrere Dienste zusammen mit ihren Abhängigkeiten bereitstellen.

Erstellen Sie für eine Windows-VM eine ARM-Vorlage, und fügen Sie wie hier gezeigt ein resources-Element unter der Ressource Microsoft.Compute/virtualMachine hinzu:

"resources": [
  {
    "name": "[concat(parameters('vmNamePrefix'),copyIndex(),'/TeamServicesAgent')]",
    "type": "Microsoft.Compute/virtualMachines/extensions",
    "location": "[parameters('location')]",
    "apiVersion": "2015-06-15",
    "dependsOn": [
        "[resourceId('Microsoft.Compute/virtualMachines/',
                      concat(parameters('vmNamePrefix'),copyindex()))]"
    ],
    "properties": {
      "publisher": "Microsoft.VisualStudio.Services",
      "type": "TeamServicesAgent",
      "typeHandlerVersion": "1.0",
      "autoUpgradeMinorVersion": true,
      "settings": {
        "VSTSAccountName": "[parameters('VSTSAccountName')]",
        "TeamProject": "[parameters('TeamProject')]",
        "DeploymentGroup": "[parameters('DeploymentGroup')]",
        "AgentName": "[parameters('AgentName')]",
        "AgentMajorVersion": "auto|2|3",
        "Tags": "[parameters('Tags')]"
      },
      "protectedSettings": {
      "PATToken": "[parameters('PATToken')]"
     }
   }
  }
]

Hierbei gilt:

• VSTSAccountName ist erforderlich. Das zu verwendende Azure Pipelines-Abonnement. Beispiel: Wenn Ihre URL https://dev.azure.com/contoso lautet, geben Sie einfach contoso an.
• TeamProject ist erforderlich. Das Projekt, in dem die Bereitstellungsgruppe definiert ist
• DeploymentGroup ist erforderlich. Die Bereitstellungsgruppe, für die der Bereitstellungs-Agent registriert wird
• AgentName ist optional. Ohne Angabe wird der VM-Name verwendet, an den -DG angefügt wird.
• Tags ist optional. Eine durch Trennzeichen getrennte Liste von Tags, die für den Agent festgelegt werden. Bei Tags wird die Groß-/Kleinschreibung nicht beachtet, und die Tags dürfen nicht mehr als 256 Zeichen lang sein.
• PATToken ist erforderlich. Das persönliche Zugriffstoken, das für die Authentifizierung bei Azure Pipelines verwendet wird, um den Agent herunterzuladen und zu konfigurieren

Hinweis

Stellen Sie bei der Bereitstellung auf einer Linux-VM sicher, dass der Parameter type im Code TeamServicesAgentLinux lautet.

Problembehandlung für die Erweiterung

Dies sind einige bekannte Probleme mit der Erweiterung:

• Die Statusdatei wird zu groß: Dieses Problem tritt auf Windows-VMs auf. Auf Linux-VMs wurde es nicht beobachtet. Die Statusdatei enthält ein JSON-Objekt, das den aktuellen Status der Erweiterung beschreibt. Das Objekt ist ein Platzhalter zum Auflisten der bisher ausgeführten Vorgänge. Azure liest diese Statusdatei und übergibt das Statusobjekt als Antwort auf API-Anforderungen. Für die Datei gilt eine maximal zulässige Größe. Wenn die Größe den Schwellenwert überschreitet, kann Azure sie nicht vollständig lesen und gibt einen Fehler für den Status aus. Bei jedem Computerneustart werden einige Vorgänge von der Erweiterung ausgeführt (auch wenn sie früher möglicherweise erfolgreich installiert wurde), durch die die Statusdatei ergänzt wird. Wenn der Computer häufig neu gestartet wird, überschreitet die Größe der Statusdatei den Schwellenwert, was zu diesem Fehler führt. Die Fehlermeldung lautet Handler Microsoft.VisualStudio.Services.TeamServicesAgent:1.27.0.2 status file 0.status size xxxxxx bytes is too big. Max Limit allowed: 131072 bytes. Beachten Sie, dass die Installation der Erweiterung möglicherweise erfolgreich war, aber dieser Fehler blendet den tatsächlichen Zustand der Erweiterung aus.

  Wir haben dieses Problem für Computerneustarts behoben (ab Version 1.27.0.2 für die Windows-Erweiterung und ab 1.21.0.1 für die Linux-Erweiterung). Bei einem Neustart wird der Statusdatei also nichts hinzugefügt. Wenn dieses Problem bei der Erweiterung vor dem Fix aufgetreten ist (d. h., wenn dieses Problem bei früheren Versionen der Erweiterung auftrat) und Ihre Erweiterung automatisch auf die Versionen mit dem Fix aktualisiert wurde, tritt das Problem weiterhin auf. Das liegt daran, dass beim Update der Erweiterung die neuere Version der Erweiterung weiterhin die frühere Statusdatei verwendet. Derzeit kann dieses Problem noch auftreten, wenn Sie eine frühere Version der Erweiterung mit dem Flag zum Deaktivieren automatischer Updates für Nebenversionen verwenden oder wenn eine große Statusdatei von einer früheren Erweiterungsversion auf die neueren Versionen übertragen wurde, die den Fix enthalten, (oder aus einem beliebigen anderen Grund). In diesem Fall können Sie dieses Problem umgehen, indem Sie die Erweiterung deinstallieren und erneut installieren. Durch das Deinstallieren der Erweiterung wird das gesamte Erweiterungsverzeichnis bereinigt, sodass eine neue Statusdatei für die Neuinstallation erstellt wird. Sie müssen die neueste Version der Erweiterung installieren. Diese Lösung ist ein permanenter Fix, und nach seiner Anwendung sollte das Problem nicht mehr auftreten.

• Problem mit benutzerdefinierten Daten: Dieses Problem hängt nicht mit der Erweiterung zusammen. Einige Kund*innen haben jedoch beim Wechsel der Betriebssystemversionen über Unklarheiten in Bezug auf den Speicherort von benutzerdefinierten Daten auf dem virtuellen Computer berichtet. Wir empfehlen die folgende Problemumgehung. Python 2 ist veraltet, daher haben wir die Erweiterung so gestaltet, dass sie mit Python 3 funktioniert. Wenn Sie weiterhin frühere Betriebssystemversionen verwenden, bei denen Python 3 nicht standardmäßig installiert ist, sollten Sie zum Ausführen der Erweiterung entweder Python 3 auf der VM installieren oder zu Betriebssystemversionen wechseln, unter denen Python 3 standardmäßig installiert ist. Auf Linux-VMs werden bei früheren Versionen des Microsoft Azure Linux-Agents benutzerdefinierte Daten in die Datei /var/lib/waagent/ovf-env.xml kopiert. Bei neueren Versionen des Microsoft Azure Linux-Agents werden sie in /var/lib/waagent/CustomData kopiert. Es scheint, dass Kund*innen, die nur einen dieser beiden Pfade hartcodiert haben, Probleme beim Wechseln der Betriebssystemversionen haben, da die Datei in der neuen Betriebssystemversion nicht vorhanden ist, die andere Datei aber schon. Um die VM-Bereitstellung nicht zu unterbrechen, sollten Sie also beide Dateien in der Vorlage berücksichtigen, sodass bei einem Fehler bei einer Datei die andere Datei erfolgreich sein sollte.

Weitere Informationen zu ARM-Vorlagen finden Sie unter Define resources with Bicep, ARM templates, and Terraform AzAPI provider (Definieren von Ressourcen mit Bicep, ARM-Vorlagen und dem Terraform AzAPI-Anbieter).

So verwenden Sie die Vorlage

1. Wählen Sie auf der Registerkarte Bereitstellungsgruppen von Azure Pipelines die Option +Neu aus, um eine neue Gruppe zu erstellen.

2. Geben Sie einen Namen für die Gruppe und optional eine Beschreibung ein, und wählen Sie dann Erstellen aus.

3. Erstellen Sie auf der Registerkarte Releases von Azure Pipelines eine Releasepipeline mit einer Stufe, die die Aufgabe ARM-Vorlagenbereitstellung enthält.

4. Geben Sie die für die Aufgabe erforderlichen Parameter wie Azure-Abonnement, Ressourcengruppenname, Standort und Vorlageninformationen an, und speichern Sie dann die Releasepipeline.

5. Erstellen Sie ein Release über die Releasepipeline, um die Agents zu installieren.

Installieren von Agents mithilfe der erweiterten Bereitstellungsoptionen

1. Wählen Sie auf der Registerkarte Bereitstellungsgruppen von Azure Pipelines die Option +Neu aus, um eine neue Gruppe zu erstellen.

2. Geben Sie einen Namen für die Gruppe und optional eine Beschreibung ein, und wählen Sie dann Erstellen aus.

3. Erstellen Sie auf der Registerkarte Releases von Azure Pipelines eine Releasepipeline mit einer Stufe, die die Aufgabe ARM-Vorlagenbereitstellung enthält.

4. Wählen Sie die Aufgabe aus, und erweitern Sie den Abschnitt Erweiterte Bereitstellungsoptionen für virtuelle Computer. Konfigurieren Sie die Parameter in diesem Abschnitt wie folgt:

   • Erforderliche Komponenten aktivieren: Wählen Sie Mit Bereitstellungsgruppen-Agent konfigurieren aus.

   • Azure Pipelines-/TFS-Endpunkt: Wählen Sie eine vorhandene Azure Pipelines-/TFS-Dienstverbindung aus, die auf Ihr Ziel verweist. Die Agent-Registrierung für Bereitstellungsgruppen erfordert Zugriff auf Ihr Visual Studio-Projekt. Wenn Sie noch Dienstverbindung vorhanden ist, wählen Sie Hinzufügen aus, und erstellen Sie jetzt eine. Konfigurieren Sie sie für die Verwendung eines persönlichen Zugriffstokens (Personal Access Token, PAT), dessen Gültigkeitsbereich auf die Bereitstellungsgruppe beschränkt ist.

   • Projekt: Geben Sie das Projekt an, das die Bereitstellungsgruppe enthält.

   • Bereitstellungsgruppe: Geben Sie den Namen der Bereitstellungsgruppe an, für die die Agents registriert werden sollen.

   • Azure-VM-Tags zu Agents kopieren: Wenn diese Option festgelegt (aktiviert) ist, werden alle Tags, die bereits auf der Azure-VM konfiguriert sind, auf den entsprechenden Bereitstellungsgruppen-Agent kopiert. Standardmäßig werden alle Azure-Tags im Format Key: Value kopiert. Beispiel: Role: Web.

5. Geben Sie die für die Aufgabe weiteren erforderlichen Parameter wie Azure-Abonnement, Ressourcengruppenname und Standort an, und speichern Sie dann die Releasepipeline.

6. Erstellen Sie ein Release über die Releasepipeline, um die Agents zu installieren.

Zugehörige Themen

• Ausführen auf einem Computergruppenauftrag
• Bereitstellen eines Agents unter Windows
• Bereitstellen eines Agents unter macOS
• Bereitstellen eines Agents unter Linux

Hilfe und Support

• Erkunden Sie Tipps zur Fehlerbehebung.
• Holen Sie sich Rat auf Stack Overflow.
• Stellen Sie Ihre Fragen, suchen Sie nach Antworten, oder schlagen Sie eine Funktion in der Azure DevOps Developer Community vor.
• Erhalten Sie Unterstützung für Azure DevOps.