Agentes do Azure Pipelines

Serviços de DevOps do Azure | Azure DevOps Server | Azure DevOps Server 2022

Você precisa de pelo menos um agente para criar seu código ou implantar seu software usando o Azure Pipelines. À medida que sua base de código e equipe crescem, você precisa de vários agentes.

Quando o pipeline é executado, o sistema inicia um ou mais trabalhos. Um agente é uma infraestrutura de computação com software de agente instalado que executa um trabalho de cada vez.

O Azure Pipelines fornece vários tipos diferentes de agentes.

Agentes autogeridos

Um agente auto-hospedado é um agente que você configura para executar trabalhos e gerenciar a si mesmo. Você pode usar agentes auto-hospedados no Azure Pipelines ou no Azure DevOps Server. Os agentes auto-hospedados oferecem mais controle para instalar o software dependente de que você precisa para suas compilações e implantações. Além disso, os caches e a configuração no nível da máquina persistem de execução em execução, o que pode aumentar a velocidade.

Embora vários agentes possam ser instalados por máquina, é altamente recomendável que você instale apenas um agente por máquina. Quando você instala dois ou mais agentes, isso pode afetar negativamente o desempenho e o resultado de seus pipelines.

Você pode instalar o agente em máquinas Linux, macOS e Windows. Você também pode instalar o agente em um contêiner do Docker. Para obter mais informações sobre a instalação de um agente hospedado localmente, consulte:

• Agente macOS
• Agente Linux
• Agente Windows
• Agente do Docker

No macOS, é necessário limpar o atributo especial no arquivo de download para impedir que a proteção do macOS Gatekeeper seja exibida para cada assembly no arquivo TAR quando ./config.sh for executado. O comando a seguir limpa o atributo estendido no arquivo:

xattr -c vsts-agent-osx-x64-V.v.v.tar.gz  ## replace V.v.v with the version in the filename downloaded.
 
# then unpack the gzip tar file normally:

tar xvfz vsts-agent-osx-x64-V.v.v.tar.gz

Depois de instalar o agente em uma máquina, você pode instalar qualquer outro software nessa máquina que seus trabalhos exijam.

Trabalhos paralelos

Capacidades

Cada agente auto-hospedado tem um conjunto de recursos que indicam o que ele pode fazer. Os recursos são pares nome/valor que são:

• Recursos que o software do agente descobre, chamados recursos do sistema.
• Recursos que você define, chamados de recursos do usuário.

O software do agente determina automaticamente diversas capacidades do sistema. Esses recursos incluem o nome da máquina, o tipo de sistema operacional e as versões de determinados softwares instalados na máquina. Além disso, as variáveis de ambiente definidas na máquina aparecem automaticamente na lista de recursos do sistema.

Quando você armazena variáveis de ambiente como recursos, os valores de capacidade armazenados são usados para definir as variáveis de ambiente quando um agente é executado. Além disso, quando você faz alterações nas variáveis de ambiente enquanto o agente está em execução, elas não são captadas e usadas por nenhuma tarefa. Se você não quiser que as variáveis de ambiente confidenciais que mudam sejam armazenadas como recursos, você pode direcionar o agente para ignorá-las. Defina a variável de ambiente, com uma lista delimitada por vírgulas VSO_AGENT_IGNORE de variáveis a serem ignoradas. Por exemplo, PATH é uma variável crítica que você pode querer ignorar se estiver instalando software.

Ao criar um pipeline, você especifica determinadas demandas do agente. O sistema envia o trabalho apenas para agentes que têm recursos que correspondem às demandas especificadas no pipeline. Consequentemente, as funcionalidades do agente permitem direcionar trabalhos para agentes específicos.

As exigências e capacidades são projetadas para uso com agentes autoalojados, para que as tarefas possam ser atribuídas a um agente que atenda aos requisitos da tarefa. Ao usar agentes hospedados pela Microsoft, você seleciona uma imagem para o agente que corresponde aos requisitos do trabalho. Embora seja possível adicionar recursos a um agente hospedado pela Microsoft, você não precisa usar recursos com agentes hospedados pela Microsoft.

Configurar demandas

pool:
  name: Default
  demands: SpecialSoftware # exists check for SpecialSoftware

Configurar recursos do agente

az pipelines agent list --pool-id
                        [--agent-name]
                        [--demands]
                        [--detect {false, true}]
                        [--include-assigned-request {false, true}]
                        [--include-capabilities {false, true}]
                        [--include-last-completed-request {false, true}]
                        [--org]
                        [--subscription]

az pipelines agent list --pool-id 4 --output table

ID    Name          Is Enabled    Status    Version
----  ------------  ------------  --------  ---------
3     Hosted Agent  True          offline   2.155.1

az pipelines agent show --agent-id
                        --pool-id
                        [--detect {false, true}]
                        [--include-assigned-request {false, true}]
                        [--include-capabilities {false, true}]
                        [--include-last-completed-request {false, true}]
                        [--org]
                        [--subscription]

  <Some properties omitted for space>

  "status": "offline",
  "statusChangedOn": null,
  "systemCapabilities": {
    "ANDROID_HOME": "",
    "ANDROID_NDK_HOME": "",
    "Agent.Name": "Hosted Agent",
    "Agent.Version": "2.160.1",

    <Some capabilities omitted for space>

    "sh": "",
    "subversion": "",
    "svn": "",
    "To run tasks using Windows authentication to access an external service, the agent must run under an account with access to that service.

Comunicação

O agente se comunica com o Azure Pipelines ou o Azure DevOps Server. Ele determina qual tarefa precisa ser executada e comunica os registos e o estado da tarefa. O agente inicia sempre esta comunicação.

Todas as mensagens do agente para o Azure Pipelines ou o Azure DevOps Server têm lugar através de HTTP ou HTTPS, dependendo da forma como configurar o agente. Esse modelo pull permite configurar o agente para topologias diferentes, conforme mostrado nos exemplos a seguir.

Aqui está um padrão de comunicação comum entre o agente e o Azure Pipelines ou o Azure DevOps Server:

1. O usuário registra um agente no Azure Pipelines ou no Azure DevOps Server adicionando-o a um pool de agentes. Para registrar um agente nesse pool de agentes, você precisa ter a função de administrador do pool de agentes . A função de administrador do pool de agentes é necessária apenas no momento do registro e não persiste no agente. Ele não é usado em nenhuma comunicação adicional entre o agente e o Azure Pipelines ou o Azure DevOps Server.

   Após a conclusão do registro, o agente baixa um listener OAuth token e o usa para ouvir a fila de trabalhos.

2. O agente escuta para ver se uma nova solicitação de trabalho é postada na fila de trabalhos no Azure Pipelines ou no Azure DevOps Server usando uma pesquisa HTTP longa. Quando um trabalho está disponível, o agente baixa o trabalho e um arquivo job-specific OAuth token. O Azure Pipelines ou o Azure DevOps Server gera um token de curta duração para a identidade com escopo especificada no pipeline.

   O agente usa o token para acessar ou modificar recursos no Azure Pipelines ou no Azure DevOps Server dentro desse trabalho. Por exemplo, ele usa o token para acessar o código-fonte ou carregar resultados de teste.

3. O agente descarta o token OAuth específico do trabalho após a conclusão do trabalho e, em seguida, verifica se há uma nova solicitação de trabalho usando o token OAuth do ouvinte.

A carga útil das mensagens trocadas entre o agente e o Azure Pipelines ou o Azure DevOps Server é protegida usando criptografia assimétrica.

Cada agente tem um par de chaves públicas-privadas e a chave pública é trocada com o servidor durante o registo. O servidor usa a chave pública para criptografar a carga útil do trabalho antes de enviá-la ao agente. O agente descriptografa o conteúdo do trabalho usando sua chave privada.

Este método protege segredos armazenados em pipelines ou grupos de variáveis durante a troca com o agente.

Autenticação

Para registrar um agente, você precisa ser membro da função de administrador no pool de agentes. A identidade do administrador do pool de agentes é necessária apenas no momento do registro e não é mantida no agente. Ele não é usado em nenhuma comunicação subsequente entre o agente e o Azure Pipelines ou o Azure DevOps Server. Para configurar o agente, você também deve ser um administrador local no servidor.

Ao registrar um agente, selecione um dos seguintes tipos de autenticação. O processo de configuração do agente solicita as informações adicionais específicas necessárias para cada tipo de autenticação. Para obter mais informações, consulte Opções de autenticação de agente auto-hospedado.

O método de autenticação que você usa para registrar o agente é usado somente durante o registro do agente. Para saber mais sobre como os agentes se comunicam com o Azure Pipelines após o registro, consulte Comunicação com o Azure Pipelines ou o Azure DevOps Server.

Interativo vs. serviço

Pode executar o seu agente autogerido como um serviço ou um processo interativo.

Depois de configurar o agente, recomendamos que você primeiro experimente-o no modo interativo para garantir que ele funcione. Em seguida, para uso em produção, recomendamos que você execute o agente em um dos seguintes modos para que ele permaneça confiável em um estado de execução. Estes modos também asseguram que o agente é iniciado automaticamente caso a máquina seja reiniciada.

• Como serviço: você pode usar o gerenciador de serviços do sistema operacional para gerenciar o ciclo de vida do agente. A experiência para atualizar automaticamente o agente é melhor quando você executa o agente como um serviço.

• Como um processo interativo com o login automático habilitado: em alguns casos, talvez seja necessário executar o agente interativamente para uso em produção (por exemplo, para executar testes de interface do usuário). Quando você configura um agente para ser executado nesse modo, a proteção de tela é desabilitada. Algumas políticas de domínio podem impedi-lo de ativar o início de sessão automático ou desativar a proteção de ecrã. Nesses casos, talvez seja necessário buscar uma isenção da diretiva de domínio ou executar o agente em um computador do grupo de trabalho onde as diretivas de domínio não se aplicam.

  Nota

  Existem riscos de segurança quando ativa o início de sessão automático ou desativa a proteção de ecrã. Outros utilizadores poderão conseguir aceder ao computador e utilizar a conta que inicia sessão automaticamente. Se você configurar o agente para ser executado dessa forma, deverá garantir que o computador esteja fisicamente protegido (por exemplo, localizado em uma instalação segura).

  Se você usar uma área de trabalho remota para acessar um computador no qual um agente está sendo executado com entrada automática, fechar a área de trabalho remota fará com que o computador seja bloqueado. Qualquer teste de interface do usuário executado neste agente pode falhar. Para evitar esse problema, use o tscon comando para se desconectar da área de trabalho remota. Por exemplo:

  %windir%\System32\tscon.exe 1 /dest:console

Conta de agente

Se você executa um agente como um serviço ou interativamente, você pode escolher qual conta de computador você usa para executar o agente. A escolha da conta do agente depende exclusivamente das necessidades das tarefas executadas em suas tarefas de compilação e implantação.

Por exemplo, para executar tarefas usando a autenticação do Windows para acessar um serviço externo, o agente deve ser executado usando uma conta com acesso a esse serviço. No entanto, se você estiver executando testes de interface do usuário, como Selenium ou testes de interface do usuário codificada que exigem um navegador, o navegador será aberto no contexto da conta do agente.

No Windows, recomendamos que você use uma conta de serviço como Serviço de Rede ou Serviço Local. Essas permissões de contas são restritas e suas senhas não expiram, portanto, o agente requer menos gerenciamento ao longo do tempo.

Essas credenciais são diferentes das credenciais que você usa quando registra o agente no Azure Pipelines ou no Azure DevOps Server.

Versão e atualizações do agente

Você pode visualizar a versão de um agente. Vá para Pools de agentes e selecione a guia Recursos para o agente desejado, conforme descrito em Configurar recursos do agente.

Para acionar a atualização do agente programaticamente, você pode usar a API de atualização do agente conforme descrito na seção Como posso acionar atualizações do agente programaticamente para um pool de agentes específico?.

Para servidores sem acesso à Internet, copie manualmente o arquivo ZIP do agente para a seguinte pasta para usar como um arquivo local. Crie a pasta Agentes se ela não estiver presente:

• Janelas: %ProgramData%\Microsoft\Azure DevOps\Agents
• Linux: usr/share/Microsoft/Azure DevOps/Agents
• macOS: usr/share/Microsoft/Azure DevOps/Agents

Estrutura do diretório do agente

Quando trabalhos de pipeline são executados em agentes, uma estrutura de diretórios é criada para armazenar o código-fonte, binários e artefatos.

O diretório base do agente é o diretório onde o agente está instalado. O diretório normalmente está localizado:

• Agentes hospedados pela Microsoft: C:\agents\<agent version> no Windows, /Users/runner/runners/<agent version> no macOS e /home/vsts/agents/<agent version> no Linux.
• Agentes auto-hospedados: C:\agent no Windows, Users/<username>/agent (~/agent) no macOS e /home/vsts/agent no Linux.

O diretório de trabalho do agente contém o espaço de trabalho onde a origem e a saída de trabalhos são armazenadas. O diretório de trabalho normalmente está localizado:

• Agente hospedado pela Microsoft: C:\a no Windows, /Users/runner/work no macOS e/home/vsts/work no Linux.
• Agente auto-hospedado: C:\agent\_work no Windows, ~/agent/work no macOS e /home/agent/_work no Linux.

A estrutura do diretório de trabalho é:

    - /work directory
        - /1 build directory/pipeline workspace
            - /s source/working directory
            - /b binaries directory
            - /a artifacts staging directory
            - /TestResults Test results directory

Em agentes hospedados pela Microsoft, um agente diferente é usado em cada execução, portanto, o diretório de trabalho não é retido entre as execuções. Em agentes auto-hospedados, somente o diretório de estágio de artefatos e os diretórios de resultados de teste são limpos entre execuções por padrão. Para obter mais informações sobre a opção de limpeza do espaço de trabalho, consulte Workspace.

Para obter mais informações sobre variáveis predefinidas, consulte Variáveis predefinidas.

FAQ

Como posso certificar-me de que tenho a versão mais recente do agente?

1. Vá para o separador Pools de agentes:

   1. Inicie sessão na sua organização (https://dev.azure.com/{yourorganization}).

   2. SelecioneConfigurações da Organização>.

      

   3. Selecione Pools de agentes.

      

   1. Inicie sessão na sua coleção de projetos (http://your-server/DefaultCollection).

   2. Selecione Azure DevOps>Configurações da Coleção.

      

   3. Selecione Pools de agentes.

      

   

2. Selecione o pool que contém o agente.

3. Verifique se o agente está habilitado.

4. Vá para a guia de recursos:

   1. Na guia Pools de agentes, selecione o pool de agentes desejado.

      

   2. Selecione Agentes e escolha o agente desejado.

      

   3. Escolha o separador Recursos.

      

      Nota

      Os agentes hospedados pela Microsoft não exibem recursos do sistema. Para obter uma lista de software instalado em agentes hospedados pela Microsoft, consulte Usar um agente hospedado pela Microsoft.

   1. No separador Pools de agentes, selecione o pool desejado.

      

   2. Selecione Agentes e escolha o agente desejado.

      

   3. Escolha o separador Recursos.

      

5. Procure a capacidade Agent.Version. Você pode comparar esse valor com a versão mais recente publicada do agente na página Agente de Pipelines do Azure .

6. Cada agente se atualiza automaticamente quando executa uma tarefa que requer uma versão mais recente do agente. Se desejar atualizar manualmente alguns agentes, clique com o botão direito do mouse no pool e selecione Atualizar todos os agentes.

Os agentes auto-hospedados têm alguma vantagem de desempenho em relação aos agentes hospedados pela Microsoft?

Em muitos casos, sim. Se você usar um agente auto-hospedado, poderá executar compilações incrementais. Por exemplo, se você definir um pipeline que não limpa o repositório e não executa uma compilação limpa, suas compilações normalmente são executadas mais rapidamente. Você não obtém esses benefícios com um agente hospedado pela Microsoft, a menos que use recursos como cache, porque o agente é destruído após a conclusão do pipeline.

Um agente hospedado pela Microsoft pode levar mais tempo para iniciar sua compilação. Embora muitas vezes demore apenas alguns segundos para que seu trabalho seja atribuído a um agente hospedado pela Microsoft, às vezes pode levar vários minutos para que um agente seja alocado, dependendo da carga em nosso sistema.

Posso instalar vários agentes auto-hospedados na mesma máquina?

Sim. Essa abordagem pode funcionar bem para agentes que executam trabalhos que não consomem muitos recursos compartilhados. Por exemplo, experimente para agentes que executam lançamentos que principalmente orquestram implantações e não fazem muito trabalho pelo próprio agente.

Você pode achar que, em outros casos, você não ganha muita eficiência executando vários agentes na mesma máquina. Por exemplo, pode não valer a pena para agentes que executam compilações que consomem muito espaço em disco e recursos de entrada/saída.

Você também pode enfrentar problemas se tarefas de construção paralelas estiverem utilizando a mesma configuração de ferramenta singleton (por exemplo, pacotes npm). Uma compilação pode atualizar uma dependência enquanto outra compilação está usando-a, o que pode causar resultados e erros não confiáveis.

POST https://dev.azure.com/{organization}/_apis/distributedtask/pools/{poolId}/messages?agentId={agentId}&api-version=6.0

POST https://{server url}/tfs/{collection}/_apis/distributedtask/pools/{poolId}/messages?agentId={agentId}&api-version=6.0