Effettuare il provisioning degli agenti per i gruppi di distribuzione

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

Un gruppo di distribuzione è un gruppo logico di computer di destinazione della distribuzione per le pipeline di versione classica in Azure Pipelines. Ogni server di destinazione in un gruppo di distribuzione richiede l'installazione di un agente di distribuzione. Questo articolo illustra come installare ed eseguire il provisioning dell'agente di distribuzione in ogni macchina virtuale o fisica in un gruppo di distribuzione.

È possibile installare l'agente in un computer di destinazione in uno dei modi seguenti:

• Eseguire lo script che genera quando si crea il gruppo di distribuzione.
• Installare l'estensione della macchina virtuale di Azure Per l'agente di Azure Pipelines nella macchina virtuale.
• Usare l'attività AzureResourceGroupDeploymentV2 nella pipeline di versione per creare un gruppo di distribuzione e effettuare il provisioning degli agenti in modo dinamico.

Le sezioni seguenti illustrano i passaggi per implementare ogni metodo.

Prerequisiti

• Organizzazione e progetto di Azure DevOps. Per creare un'organizzazione o un progetto, vedere Creare una nuova organizzazione o Creare un progetto in Azure DevOps.
• Accesso ad almeno un computer di destinazione della distribuzione Windows o Linux con le autorizzazioni appropriate.
• Per i metodi di installazione dell'agente Azure Pipelines, un account e una sottoscrizione di Azure con autorizzazioni per creare e gestire macchine virtuali di Azure. Se non si ha un account Azure, iscriversi per ottenere un account gratuito.

Eseguire lo script di installazione nei server di destinazione

Quando si crea un gruppo di distribuzione, viene generato uno script che è possibile eseguire in ogni computer di destinazione per registrare il server e installare l'agente. Per installare l'agente usando lo script di registrazione generato:

1. Nel progetto Azure DevOps selezionare Gruppi di distribuzione pipeline>.

2. Nella schermata Gruppi di distribuzione selezionare Nuovo o selezionare Aggiungi un gruppo di distribuzione se questo gruppo di distribuzione è il primo del progetto.

3. Immettere un nome del gruppo di distribuzione e una descrizione facoltativa e quindi selezionare Crea.

4. Nella schermata successiva selezionare Windows o Linux per Tipo di destinazione da registrare. Viene generato uno script di registrazione.

5. Selezionare Usa un token di accesso personale nello script per l'autenticazione. Per altre informazioni, vedere Usare i token di accesso personali.

6. Selezionare Copia script negli Appunti.

7. In ogni computer di destinazione accedere usando un account con autorizzazioni amministrative.

8. Eseguire lo script copiato per registrare il computer e installare l'agente. Per i computer Windows, usare un prompt dei comandi di PowerShell con privilegi elevati.

   Durante l'esecuzione dello script:

   • Per assegnare tag che consentono di limitare le distribuzioni a determinati server in un processo del gruppo di distribuzione, immettere Y quando viene richiesto di immettere i tag e quindi immettere un tag o tag per questa macchina virtuale.

     I tag sono limitati a 256 caratteri, non fanno distinzione tra maiuscole e minuscole e non è previsto alcun limite al numero di tag che è possibile usare.

   • Quando viene richiesto un account utente, accettare le impostazioni predefinite.

   Nota

   Se viene visualizzato un errore durante l'esecuzione dello script che non è stato possibile creare un canale protetto, eseguire il comando seguente al prompt di PowerShell amministratore:

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

Dopo aver configurato ogni server di destinazione, lo script deve restituire il messaggio Service vstsagent.{organization-name}.{computer-name} started successfully.

Nella scheda Destinazioni della pagina Gruppi di distribuzione di Azure Pipelines è possibile verificare che l'agente sia in esecuzione. Se necessario, aggiornare la pagina.

Installare l'estensione della macchina virtuale di Azure Per l'agente di Azure Pipelines

Se si usano macchine virtuali di Azure come computer di distribuzione, è possibile installare l'estensione Agente di Azure Pipelines in ogni macchina virtuale. L'estensione registra automaticamente l'agente con il gruppo di distribuzione specificato nel progetto Azure DevOps.

Per installare l'agente usando l'estensione, creare prima di tutto il gruppo di distribuzione:

1. Nel progetto Azure DevOps selezionare Gruppi di distribuzione pipeline>.
2. Nella schermata Gruppi di distribuzione selezionare Nuovo o selezionare Aggiungi un gruppo di distribuzione se questo gruppo di distribuzione è il primo del progetto.
3. Immettere un nome del gruppo di distribuzione e una descrizione facoltativa e quindi selezionare Crea.

Nella portale di Azure installare l'estensione Dell'agente Azure Pipelines in ogni macchina virtuale di destinazione:

1. Nella pagina VM selezionare Impostazioni>Estensioni e applicazioni nel riquadro di spostamento a sinistra.

2. Nella scheda Estensione selezionare Aggiungi.

3. Nella pagina Installa un'estensione cercare e selezionare Agente Azure Pipelines e quindi selezionare Avanti.

   

4. Nella schermata Configura estensione agente di Azure Pipelines specificare le informazioni seguenti:

   • URL organizzazione di Azure DevOps: immettere l'URL dell'organizzazione Azure DevOps, ad esempio https://dev.azure.com/contoso.
   • Progetto team: immettere il nome del progetto, ad esempio myProject.
   • Gruppo di distribuzione: immettere il nome del gruppo di distribuzione creato.
   • Nome agente: facoltativamente, immettere un nome per l'agente. Se non si immette nulla, l'agente viene denominato il nome della macchina virtuale aggiunto con -DG.
   • Token di accesso personale: immettere il token di accesso personale da usare per l'autenticazione in Azure Pipelines.
   • Tag: facoltativamente, specificare un elenco delimitato da virgole di tag da configurare nell'agente. I tag sono limitati a 256 caratteri, non fanno distinzione tra maiuscole e minuscole e non è previsto alcun limite al numero di tag che è possibile usare.

5. Selezionare Verifica e crea e, quando la convalida ha esito positivo, selezionare Crea.

Usare l'attività AzureResourceGroupDeploymentV2

È possibile usare l'attività AzureResourceGroupDeploymentV2 per distribuire un modello di Azure Resource Manager (ARM). Il modello può installare l'estensione agente di Azure Pipelines durante la creazione di una macchina virtuale di Azure oppure aggiornare il gruppo di risorse per applicare l'estensione dopo la creazione di una macchina virtuale.

In alternativa, è possibile usare le opzioni di distribuzione avanzate dell'attività AzureResourceGroupDeployment per distribuire l'agente.

Creare un gruppo di distribuzione

Creare prima di tutto il gruppo di distribuzione:

1. Nel progetto Azure DevOps selezionare Gruppi di distribuzione pipeline>.
2. Nella schermata Gruppi di distribuzione selezionare Nuovo o selezionare Aggiungi un gruppo di distribuzione se questo gruppo di distribuzione è il primo del progetto.
3. Immettere un nome del gruppo di distribuzione e una descrizione facoltativa e quindi selezionare Crea.

Usare un modello di Resource Manager per installare l'agente

Un modello di Resource Manager è un file JSON che definisce in modo dichiarativo un set di risorse di Azure. Azure legge automaticamente il modello ed effettua il provisioning delle risorse. È possibile distribuire più servizi e le relative dipendenze in un singolo modello.

Per registrare e installare l'agente di distribuzione usando un modello di Resource Manager, aggiungere un elemento resources nella Microsoft.Compute/virtualMachine risorsa, come illustrato nel codice seguente.

"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')]"
     }
   }
  }
]

"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|N",
        "Tags": "[parameters('Tags')]"
      },
      "protectedSettings": {
      "PATToken": "[parameters('PATToken')]"
     }
   }
  }
]

Nel codice precedente:

• VSTSAccountName è l'organizzazione di Azure Pipelines necessaria per l'uso. Ad esempio, se l'URL di Azure DevOps è https://dev.azure.com/contoso, è sufficiente specificare contoso
• TeamProject è il progetto obbligatorio con il gruppo di distribuzione definito.
• DeploymentGroup è il gruppo di distribuzione necessario a cui registrare l'agente.
• AgentName è un nome facoltativo dell'agente. Se non specificato, all'agente viene assegnato il nome della macchina virtuale con -DG aggiunta.
• Tags è un elenco facoltativo delimitato da virgole di tag da impostare nell'agente. I tag sono limitati a 256 caratteri, non fanno distinzione tra maiuscole e minuscole e non è previsto alcun limite al numero di tag che è possibile usare.
• PATToken è il pat richiesto per l'autenticazione in Azure Pipelines per il download e la configurazione dell'agente.

Per altre informazioni sui modelli di Resource Manager, vedere Definire le risorse nei modelli di Azure Resource Manager.

Usare il modello in una pipeline di versione

Creare una pipeline di versione:

1. Selezionare Pipeline>versioni dal menu a sinistra e quindi nuova >pipeline di versione.
2. Nella scheda Versioni di Azure Pipelines creare una pipeline di versione con una fase che contiene l'attività di distribuzione del modello di Resource Manager.
3. Questo modello usa la versione 2 dell'attività, quindi nella schermata delle impostazioni di distribuzione del gruppo di risorse di Azure modificare la versione dell'attività da 3.* a 2.*.
4. Specificare i parametri necessari per l'attività, ad esempio la sottoscrizione di Azure, il nome del gruppo di risorse, il percorso, le informazioni sul modello e l'azione da eseguire.
5. Salvare la pipeline di versione e creare una versione dalla pipeline per installare gli agenti.

Installare gli agenti usando le opzioni di distribuzione avanzate

In alternativa, è possibile installare l'agente usando opzioni di distribuzione avanzate. Seguire i passaggi precedenti, ma nella schermata delle impostazioni di distribuzione del gruppo di risorse di Azure espandere la sezione Opzioni di distribuzione avanzate per le macchine virtuali.

1. In Abilita prerequisiti selezionare Configura con l'agente del gruppo di distribuzione.

2. Specificare i parametri e le impostazioni obbligatori seguenti:

   • Connessione al servizio Azure Pipelines: selezionare una connessione al servizio esistente che punta alla destinazione.

     Se non si ha una connessione al servizio esistente, selezionare Nuovo e crearne uno. Per altre informazioni, vedere Creare una connessione al servizio. Configurare la connessione al servizio per l'uso di un token di accesso personale con ambito limitato al gruppo di distribuzione.

   • Progetto team: selezionare il progetto che contiene il gruppo di distribuzione.

   • Gruppo di distribuzione: selezionare il gruppo di distribuzione in cui registrare gli agenti.

   • Selezionare Copy Azure VM tags to agents (Copia tag di macchine virtuali di Azure negli agenti) per copiare i tag già configurati nella macchina virtuale di Azure nell'agente del gruppo di distribuzione corrispondente.

     Per impostazione predefinita, tutti i tag di Azure vengono copiati usando il Key: Value formato , ad esempio Role: Web.

3. Salvare la pipeline e creare una versione per installare gli agenti.

Risolvere i problemi relativi all'estensione

Esistono alcuni problemi noti con l'estensione Dell'agente di Azure Pipelines.

Il file di stato è troppo grande

Questo problema può verificarsi nelle macchine virtuali Windows. Il file di stato contiene un oggetto JSON che descrive lo stato corrente dell'estensione. L'oggetto è un segnaposto per elencare le operazioni eseguite finora.

Azure legge questo file di stato e passa l'oggetto stato come risposta alle richieste API. Il file ha una dimensione massima consentita. Se le dimensioni superano il valore massimo, Azure non può leggerlo completamente e restituisce un errore per lo stato.

Anche se l'estensione potrebbe essere installata inizialmente, ogni volta che il computer riavvia l'estensione esegue alcune operazioni che vengono aggiunte al file di stato. Se il computer viene riavviato più volte, le dimensioni del file di stato possono superare la soglia, causando l'errore Handler Microsoft.VisualStudio.Services.TeamServicesAgent:1.27.0.2 status file 0.status size xxxxxx bytes is too big. Max Limit allowed: 131072 bytes. Anche se l'installazione dell'estensione potrebbe avere esito positivo, questo errore nasconde lo stato effettivo dell'estensione.

Questo problema di riavvio del computer è stato risolto a partire dalla versione 1.27.0.2 per l'estensione Windows e 1.21.0.1 per l'estensione Linux. Un riavvio ora non aggiunge alcun elemento al file di stato. Tuttavia, se si è verificato questo problema con una versione precedente dell'estensione e l'estensione è stata aggiornata automaticamente alla versione fissa, il problema può persistere. Le versioni più recenti dell'estensione possono comunque funzionare con un file di stato precedente.

Questo problema può verificarsi se si usa una versione precedente dell'estensione con il flag per disattivare gli aggiornamenti automatici delle versioni secondarie o se un file di stato di grandi dimensioni è stato trasportato da una versione precedente a una versione fissa. In tal caso, è possibile risolvere il problema disinstallando e reinstallando l'estensione. La disinstallazione dell'estensione pulisce l'intera directory di estensione e crea un nuovo file di stato per una nuova installazione della versione più recente.

Problema di dati personalizzati

Python 2 è deprecato e l'estensione dell'agente di Azure Pipelines funziona con Python 3. Se si usano ancora versioni del sistema operativo che non hanno Python 3 installato per impostazione predefinita, per eseguire l'estensione è necessario installare Python 3 nella macchina virtuale o passare a una versione del sistema operativo con Python 3 installato per impostazione predefinita. In caso contrario, può verificarsi confusione riguardo al percorso dei dati personalizzato nella macchina virtuale quando si cambiano le versioni del sistema operativo.

Nelle macchine virtuali Linux i dati personalizzati vengono copiati in /var/lib/waagent/ovf-env.xml per le versioni precedenti dell'agente e in /var/lib/waagent/CustomData per le versioni più recenti. Se si imposta come hardcode solo uno di questi due percorsi, è possibile che si verifichino problemi durante il cambio di versioni del sistema operativo perché uno dei percorsi non esiste nella nuova versione del sistema operativo, anche se l'altro percorso è presente. Per evitare l'interruzione del provisioning della macchina virtuale, è consigliabile usare entrambi i percorsi nel modello in modo che, in caso di errore, l'altro abbia esito positivo.

Assistenza e supporto

• Esplorare i suggerimenti per la risoluzione dei problemi.
• Ottenere consigli su Stack Overflow.
• Pubblicare domande, cercare risposte o suggerire una funzionalità nella community di sviluppatori di Azure DevOps.
• Ottenere supporto per Azure DevOps.

Contenuto correlato

• Processi del gruppo di distribuzione
• Agenti Windows self-hosted
• Agenti macOS self-hosted
• Agenti Linux self-hosted
• Configurare e pagare i processi in parallelo
• Prezzi per Azure DevOps