Aprovisionar agentes para grupos de implementação

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

Um grupo de implantação é um grupo lógico de máquinas de destino de implantação para pipelines de versão clássica no Azure Pipelines. Cada servidor de destino em um grupo de implantação requer um agente de implantação instalado. Este artigo explica como instalar e provisionar o agente de implantação em cada máquina física ou virtual (VM) em um grupo de implantação.

Você pode instalar o agente em uma máquina de destino de qualquer uma das seguintes maneiras:

• Execute o script que gera quando você cria o grupo de implantação.
• Instale a extensão de VM do Azure Pipelines Agent na VM.
• Use a tarefa AzureResourceGroupDeploymentV2 em seu pipeline de liberação para criar um grupo de implantação e provisionar agentes dinamicamente.

As seções a seguir fornecem etapas para implementar cada método.

Pré-requisitos

• Uma organização e um projeto do Azure DevOps. Para criar uma organização ou projeto, consulte Criar uma nova organização ou Criar um projeto no Azure DevOps.
• Acesso a pelo menos uma máquina de destino de implantação do Windows ou Linux com as permissões apropriadas.
• Para os métodos de instalação do Agente de Pipelines do Azure, uma conta do Azure e uma assinatura com permissões para criar e gerenciar VMs do Azure. Se não tiver uma conta do Azure, inscreva-se numa conta gratuita.

Execute o script de instalação nos servidores de destino

Quando você cria um grupo de implantação, é gerado um script que pode ser executado em cada máquina de destino para registrar o servidor e instalar o agente. Para instalar o agente usando o script de registro gerado:

1. No seu projeto do Azure DevOps, selecione Grupos de implantação de pipelines>.

2. Na tela Grupos de implantação, selecione Novo ou selecione Adicionar um grupo de implantação se esse grupo de implantação for o primeiro do projeto.

3. Insira um nome de grupo de implantação e uma Descrição opcional e selecione Criar.

4. Na próxima tela, selecione Windows ou Linux para o Tipo de destino a ser registrado. Um script de registro é gerado.

5. Selecione Utilizar um token de acesso pessoal no script para autenticação. Para obter mais informações, consulte Usar tokens de acesso pessoal.

6. Selecione Copiar script para a área de transferência.

7. Em cada máquina de destino, entre usando uma conta com permissões administrativas.

8. Execute o script copiado para registrar a máquina e instalar o agente. Para máquinas Windows, use um prompt de comando do PowerShell elevado.

   Como o script é executado:

   • Para atribuir tags que permitem limitar implantações a determinados servidores em um trabalho de grupo de implantação, digite Y quando solicitado a inserir tags e, em seguida, insira uma tag ou tags para essa VM.

     As tags são limitadas a 256 caracteres cada, não diferenciam maiúsculas de minúsculas e não há limite para o número de tags que você pode usar.

   • Quando for solicitada uma conta de usuário, aceite os padrões.

   Nota

   Se você receber um erro ao executar o script informando que um canal seguro não pôde ser criado, execute o seguinte comando no prompt do PowerShell do administrador:

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

Depois de configurar cada servidor de destino, o script deve retornar a mensagem Service vstsagent.{organization-name}.{computer-name} started successfully.

Na guia Destinos da página Grupos de Implantação de Pipelines do Azure, você pode verificar se o agente está em execução. Atualize a página, se necessário.

Instalar a extensão de VM do Azure Pipelines Agent

Se você usar VMs do Azure como suas máquinas de implantação, poderá instalar a extensão do Agente de Pipelines do Azure em cada VM. A extensão registra automaticamente o agente com o grupo de implantação especificado em seu projeto de DevOps do Azure.

Para instalar o agente usando a extensão, primeiro crie o grupo de implantação:

1. No seu projeto do Azure DevOps, selecione Grupos de implantação de pipelines>.
2. Na tela Grupos de implantação, selecione Novo ou selecione Adicionar um grupo de implantação se esse grupo de implantação for o primeiro do projeto.
3. Insira um nome de grupo de implantação e uma Descrição opcional e selecione Criar.

No portal do Azure, instale a extensão do Agente de Pipelines do Azure em cada VM de destino:

1. Na página VM, selecione Configurações>Extensões + Aplicativos na navegação à esquerda.

2. Na guia Extensão, selecione Adicionar.

3. Na página Instalar uma Extensão, procure e selecione Agente de Pipelines do Azure e selecione Avançar.

   

4. Na tela Configurar Extensão do Agente de Pipelines do Azure, especifique as seguintes informações:

   • URL da Organização do Azure DevOps: insira a URL da sua organização do Azure DevOps, como https://dev.azure.com/contoso.
   • Projeto de equipe: insira o nome do projeto, como myProject.
   • Grupo de Implantação: insira o nome do grupo de implantação que você criou.
   • Nome do agente: Opcionalmente, insira um nome para o agente. Se você não inserir nada, o agente será nomeado o nome da VM anexado com -DG.
   • Token de Acesso Pessoal: insira o Token de Acesso Pessoal (PAT) a ser usado para autenticação no Azure Pipelines.
   • Tags: Opcionalmente, especifique uma lista separada por vírgulas de tags para configurar no agente. As tags são limitadas a 256 caracteres cada, não diferenciam maiúsculas de minúsculas e não há limite para o número de tags que você pode usar.

5. Selecione Rever + criar e, quando a validação for aprovada, selecione Criar.

Usar a tarefa AzureResourceGroupDeploymentV2

Você pode usar a tarefa AzureResourceGroupDeploymentV2 para implantar um modelo do Azure Resource Manager (ARM). O modelo pode instalar a extensão do Agente de Pipelines do Azure ao criar uma VM do Azure ou pode atualizar o grupo de recursos para aplicar a extensão após a criação de uma VM.

Como alternativa, você pode usar as opções avançadas de implantação da tarefa AzureResourceGroupDeployment para implantar o agente.

Criar um grupo de implantação

Primeiro, crie o grupo de implantação:

1. No seu projeto do Azure DevOps, selecione Grupos de implantação de pipelines>.
2. Na tela Grupos de implantação, selecione Novo ou selecione Adicionar um grupo de implantação se esse grupo de implantação for o primeiro do projeto.
3. Insira um nome de grupo de implantação e uma Descrição opcional e selecione Criar.

Usar um modelo ARM para instalar o agente

Um modelo ARM é um arquivo JSON que define declarativamente um conjunto de recursos do Azure. O Azure lê automaticamente o modelo e provisiona os recursos. Você pode implantar vários serviços e suas dependências em um único modelo.

Para registrar e instalar o agente de implantação usando um modelo ARM, adicione um elemento resources sob o Microsoft.Compute/virtualMachine recurso, conforme mostrado no código a seguir.

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

Nota

Para uma VM Linux, o type parâmetro no properties código deve ser TeamServicesAgentLinux.

No código anterior:

• VSTSAccountName é a organização necessária do Azure Pipelines a ser usada. Por exemplo, se a URL do Azure DevOps for https://dev.azure.com/contoso, basta especificar contoso
• TeamProject é o projeto necessário que tem o grupo de implantação definido nele.
• DeploymentGroup é o grupo de implantação necessário para registrar o agente.
• AgentName é um nome de agente opcional. Se não for especificado, o agente receberá o nome da VM com -DG anexado.
• Tags é uma lista opcional separada por vírgulas de tags a serem definidas no agente. As tags são limitadas a 256 caracteres cada, não diferenciam maiúsculas de minúsculas e não há limite para o número de tags que você pode usar.
• PATToken é a PAT necessária para autenticar no Azure Pipelines para baixar e configurar o agente.

Para obter mais informações sobre modelos ARM, consulte Definir recursos em modelos do Azure Resource Manager.

Usar o modelo em um pipeline de liberação

Crie um pipeline de versão:

1. Selecione Pipelines>Releases no menu esquerdo e, em seguida, selecione New>New release pipeline.
2. Na guia Versões do Azure Pipelines, crie um pipeline de liberação com um estágio que contenha a tarefa de implantação de modelo ARM.
3. Este modelo usa a versão 2 da tarefa, portanto, na tela Configurações de implantação do grupo de recursos do Azure, altere a versão da tarefa de 3.* para 2.*.
4. Forneça os parâmetros necessários para a tarefa, como a assinatura do Azure, o nome do grupo de recursos, o local, as informações do modelo e a ação a ser tomada.
5. Salve o pipeline de liberação e crie uma liberação do pipeline para instalar os agentes.

Instalar agentes usando as opções avançadas de implantação

Como alternativa, você pode instalar o agente usando opções avançadas de implantação. Siga as etapas anteriores, mas na tela Configurações de implantação do grupo de recursos do Azure, expanda a seção Opções avançadas de implantação para máquinas virtuais.

1. Em Habilitar pré-requisitos, selecione Configurar com o agente do Grupo de Implantação.

2. Forneça os seguintes parâmetros e configurações necessários:

   • Conexão de serviço do Azure Pipelines: selecione uma conexão de serviço existente que aponte para seu destino.

     Se você não tiver uma conexão de serviço existente, selecione Novo e crie uma. Para obter mais informações, consulte Criar uma conexão de serviço. Configure a conexão de serviço para usar uma PAT com escopo restrito ao Grupo de Implantação.

   • Projeto de equipe: selecione o projeto que contém o grupo de implantação.

   • Grupo de implantação: selecione o grupo de implantação para o qual registrar os agentes.

   • Selecione Copiar marcas de VM do Azure para agentes para copiar quaisquer marcas já configuradas na VM do Azure para o agente de grupo de implantação correspondente.

     Por padrão, todas as marcas do Azure são copiadas usando o Key: Value formato, por exemplo Role: Web.

3. Salve o pipeline e crie uma versão para instalar os agentes.

Solucionar problemas da extensão

Há alguns problemas conhecidos com a extensão do Agente de Pipelines do Azure.

O arquivo de status é muito grande

Esse problema pode ocorrer em VMs do Windows. O arquivo de status contém um objeto JSON que descreve o status atual da extensão. O objeto é um espaço reservado para listar as operações executadas até agora.

O Azure lê esse arquivo de status e passa o objeto de status como resposta às solicitações de API. O ficheiro tem um tamanho máximo permitido. Se o tamanho exceder o máximo, o Azure não poderá lê-lo completamente e fornecerá um erro para o status.

Mesmo que a extensão possa ser instalada inicialmente, toda vez que a máquina reinicializa, a extensão executa algumas operações que são anexadas ao arquivo de status. Se a máquina for reinicializada muitas vezes, o tamanho do arquivo de status pode exceder o limite, causando o erro Handler Microsoft.VisualStudio.Services.TeamServicesAgent:1.27.0.2 status file 0.status size xxxxxx bytes is too big. Max Limit allowed: 131072 bytes. Embora a instalação da extensão possa ser bem-sucedida, esse erro oculta o estado real da extensão.

Este problema de reinicialização da máquina é corrigido a partir da versão 1.27.0.2 para a extensão do Windows e 1.21.0.1 para a extensão do Linux. Uma reinicialização agora não adiciona nada ao arquivo de status. No entanto, se você teve esse problema com uma versão anterior da extensão e sua extensão foi atualizada automaticamente para a versão corrigida, o problema pode persistir. As versões mais recentes da extensão ainda podem funcionar com um arquivo de status anterior.

Você pode enfrentar esse problema se estiver usando uma versão anterior da extensão com o sinalizador para desativar as atualizações automáticas da versão secundária ou se um arquivo de status grande tiver sido transportado de uma versão anterior para uma versão corrigida. Em caso afirmativo, você pode resolver o problema desinstalando e reinstalando a extensão. A desinstalação da extensão limpa todo o diretório da extensão e cria um novo arquivo de status para uma nova instalação da versão mais recente.

Problema de dados personalizados

O Python 2 foi preterido e a extensão do Agente de Pipelines do Azure funciona com o Python 3. Se você ainda usa versões do sistema operacional que não têm o Python 3 instalado por padrão, para executar a extensão, você deve instalar o Python 3 na VM ou alternar para uma versão do sistema operacional que tenha o Python 3 instalado por padrão. Caso contrário, pode haver confusão em relação ao local de dados personalizados na VM quando você alterna as versões do sistema operacional.

Em VMs Linux, os dados personalizados são copiados para /var/lib/waagent/ovf-env.xml para versões anteriores do agente e para /var/lib/waagent/CustomData para versões mais recentes. Se você codificar apenas um desses dois caminhos, poderá enfrentar problemas ao alternar versões do sistema operacional porque um dos caminhos não existe na nova versão do sistema operacional, embora o outro caminho esteja presente. Para evitar interromper o provisionamento da VM, considere usar os dois caminhos no modelo para que, se um falhar, o outro seja bem-sucedido.

Ajuda e suporte

• Explore as dicas de solução de problemas.
• Obtenha conselhos sobre Stack Overflow.
• Publique suas perguntas, procure respostas ou sugira um recurso na Comunidade de Desenvolvedores do Azure DevOps.
• Obtenha suporte para o Azure DevOps.

Conteúdos relacionados

• Trabalhos do grupo de implantação
• Agentes do Windows auto-alojados
• Agentes do macOS auto-alojados
• Agentes do Linux auto-alojados
• Configurar e pagar trabalhos paralelos
• Preços do DevOps do Azure