Provisionar agentes para grupos de implantação

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

Um grupo de implantação é um grupo lógico de computadores de destino de implantação para pipelines de versão clássicos 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 VM (máquina virtual) física ou virtual 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 é gerado quando você cria o grupo de implantação.
• Instale a extensão de VM do Azure do Agente do Azure Pipelines na VM.
• Use a tarefa AzureResourceGroupDeploymentV2 em seu pipeline de lançamento 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 um computador de destino de implantação do Windows ou Linux com as permissões apropriadas.
• Para os métodos de instalação do Agente do Azure Pipelines, uma conta e uma assinatura do Azure com permissões para criar e gerenciar VMs do Azure. Caso ainda não tenha uma conta do Azure, inscreva-se para uma conta gratuita.

Executar 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 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 no projeto.

3. Insira um Nome do 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 será gerado.

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

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

7. Em cada computador 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 computadores Windows, use um prompt de comando do PowerShell com privilégios elevados.

   À medida que o script é executado:

   • Para atribuir marcas que permitem limitar implantações a determinados servidores em um trabalho de grupo de implantação, insira Y quando solicitado a inserir marcas e, em seguida, insira uma marca ou marcas 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.

   Observação

   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 do Azure Pipelines, você pode verificar se o agente está em execução. Se necessário, atualize a página.

Instalar a extensão de VM do Azure Do Agente do Azure pipelines

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

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

1. No 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 no projeto.
3. Insira um Nome do grupo de implantação e uma Descrição opcional e selecione Criar.

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

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

2. Na guia Extensão , selecione Adicionar.

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

   

4. Na tela Configurar Extensão do Agente do Azure Pipelines , 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 meuProjeto.
   • 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 com o nome da VM anexado com -DG.
   • Token de Acesso Pessoal: insira o PAT (Token de Acesso Pessoal) a ser usado para autenticação no Azure Pipelines.
   • Tags: opcionalmente, especifique uma lista separada por vírgulas de tags a serem configuradas 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. Clique em Examinar + Criar e após a aprovação da validação clique em Criar.

Usar a tarefa AzureResourceGroupDeploymentV2

Você pode usar a tarefa AzureResourceGroupDeploymentV2 para implantar um modelo do ARM (Azure Resource Manager). O modelo pode instalar a extensão do Agente do Azure Pipelines 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 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 no projeto.
3. Insira um Nome do grupo de implantação e uma Descrição opcional e selecione Criar.

Usar um modelo do ARM para instalar o agente

Um modelo do 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 do ARM, adicione um elemento resources no 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')]"
     }
   }
  }
]

Observação

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 appended.
• 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 é o PAT necessário para autenticar no Azure Pipelines para baixar e configurar o agente.

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

Usar o modelo em um pipeline de lançamento

Crie um pipeline de lançamento:

1. Selecione Versões de Pipelines>no menu à esquerda e, em seguida, selecione Novo>novo pipeline de lançamento.
2. Na guia Versões do Azure Pipelines, crie um pipeline de lançamento com um estágio que contenha a tarefa de implantação do modelo do ARM.
3. Esse modelo usa a versão 2 da tarefa, portanto, na tela de 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 executada.
5. Salve o pipeline de lançamento e crie uma versão do pipeline para instalar os agentes.

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

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 o destino.

     Se você não tiver uma conexão de serviço existente, selecione Nova 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 um 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 no qual registrar os agentes.

   • Selecione Copiar marcas de VM do Azure para agentes para copiar todas as marcas já configuradas na VM do Azure para o agente do 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 do Azure Pipelines.

O arquivo de status é muito grande

Esse problema pode ocorrer em VMs do Windows. O arquivo 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 status e passa o objeto status como resposta a solicitações de API. O arquivo 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 o computador 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 poderá 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.

Esse problema de reinicialização da máquina foi corrigido a partir da versão 1.27.0.2 da extensão do Windows e 1.21.0.1 da 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 de versão secundária ou se um arquivo de status grande foi transportado de uma versão anterior para uma versão corrigida. Nesse caso, você pode resolver o problema desinstalando e reinstalando a extensão. A desinstalação da extensão limpa todo o diretório de 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 do Azure Pipelines funciona com o Python 3. Se você ainda usar versões do sistema operacional que não têm o Python 3 instalado por padrão, para executar a extensão, instale o Python 3 na VM ou alterne 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ê alternar as versões do sistema operacional.

Em VMs do 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 as 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 de VM, considere usar os dois caminhos no modelo para que, se um falhar, o outro seja bem-sucedido.

Ajuda e suporte

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

Conteúdo relacionado

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