Agentes do Windows autogeridos

Serviços de DevOps do Azure | Azure DevOps Server

Para criar e implantar o Windows, o Azure e outras soluções do Visual Studio, você precisará de pelo menos um agente do Windows. Os agentes do Windows também podem criar aplicativos Java e Android.

Saiba mais sobre os agentes

Se você já sabe o que é um agente e como ele funciona, sinta-se à vontade para ir direto para as seções a seguir. Mas se quiseres mais informações sobre o que fazem e como funcionam, consulta Azure Pipelines agentes.

Verificar pré-requisitos

Certifique-se de que a sua máquina tem estes pré-requisitos:

• Versão do sistema operacional
  • Sistema Operativo Cliente
    • Windows 7 SP1 ESU
    • Windows 8.1
    • Janelas 10
    • Janelas 11
  • SO do servidor
    • Windows Server 2012 ou superior
• O software do agente instala sua própria versão do .NET, portanto, não há nenhum pré-requisito do .NET.
• PowerShell 3.0 ou superior
• Subversion - Se você estiver criando a partir de um repositório Subversion, deverá instalar o cliente Subversion na máquina.
• Recomendado - Ferramentas de compilação do Visual Studio (2015 ou superior)

Você deve executar a configuração do agente manualmente na primeira vez. Depois de ter uma ideia de como os agentes trabalham, ou se quiser automatizar a configuração de muitos agentes, considere usar configuração autônoma.

Especificações de hardware

As especificações de hardware para seus agentes variam de acordo com suas necessidades, tamanho da equipe, etc. Não é possível fazer uma recomendação geral que se aplique a todos. Como ponto de referência, a equipe do Azure DevOps cria o código dos agentes hospedados usando pipelines que utilizam agentes hospedados. Por outro lado, a maior parte do código do Azure DevOps é criada por máquinas de classe de servidor de 24 núcleos que executam quatro agentes auto-hospedados cada.

Preparar permissões

Segurança da informação para agentes hospedados localmente

O usuário que configura o agente precisa de permissões de administrador do pool, mas o usuário que executa o agente não.

As pastas controladas pelo agente devem ser restritas ao menor número possível de usuários porque contêm segredos que podem ser descriptografados ou exfiltrados.

O agente do Azure Pipelines é um produto de software projetado para executar o código baixado de fontes externas. Ele inerentemente pode ser um alvo para ataques de Execução Remota de Código (RCE).

Portanto, é importante considerar o modelo de ameaça em torno de cada uso individual de Agentes de Pipelines para executar o trabalho e decidir quais são as permissões mínimas que podem ser concedidas ao usuário que executa o agente, à máquina onde o agente é executado, aos usuários que têm acesso de gravação à definição de Pipeline, os repositórios git onde o yaml está armazenado, ou o grupo de usuários que controlam o acesso ao pool para novos pipelines.

É uma prática recomendada que a identidade que executa o agente seja diferente daquela que possui permissões para conectar o agente ao pool. O usuário que gera as credenciais (e outros arquivos relacionados ao agente) é diferente do usuário que precisa lê-las. Portanto, é mais seguro considerar cuidadosamente o acesso concedido à própria máquina do agente e às pastas do agente que contêm arquivos confidenciais, como logs e artefatos.

Faz sentido conceder acesso à pasta do agente somente para administradores de DevOps e a identidade do usuário que executa o processo do agente. Os administradores podem precisar investigar o sistema de arquivos para entender as falhas de compilação ou obter arquivos de log para poder relatar falhas do Azure DevOps.

Decida qual usuário você usará

Como uma etapa única, você deve registrar o agente. Alguém com permissão para administrar a fila de agentes deve concluir estas etapas. O agente não usará as credenciais dessa pessoa na operação diária, mas são necessárias para concluir o registo. Saiba mais sobre como os agentes se comunicam.

Confirme se o usuário tem permissão

Verifique se a conta de usuário que você vai usar tem permissão para registrar o agente.

O usuário é proprietário da organização do Azure DevOps ou administrador do TFS ou do Azure DevOps Server? Pare aqui, você tem permissão.

Caso contrário:

1. Abra um navegador e navegue até à guia pools de Agentes para a sua organização do Azure Pipelines, servidor Azure DevOps ou servidor TFS:

   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 no lado direito da página e clique em Security.

3. Se a conta de usuário que você vai usar não for mostrada, peça a um administrador para adicioná-la. O administrador pode ser um administrador do pool de agentes, um proprietário da organização do Azure DevOps ou um administrador do TFS ou do Azure DevOps Server.

   Se for um agente de grupo de implantação, o administrador pode ser um administrador de grupo de implantação, um proprietário de organização do Azure DevOps ou um administrador do TFS ou do Azure DevOps Server.

   Você pode adicionar um utilizador à função de administrador do grupo de implementação no separador Segurança da na página Grupos de Implementação do emAzure Pipelines.

Baixar e configurar o agente

Azure Pipelines (Pipelines do Azure)

1. Faça logon na máquina usando a conta para a qual você preparou permissões, conforme explicado acima.

2. No navegador, inicie sessão em Azure Pipelines e navegue até ao separador Agent pools:

   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.

      

   

3. Selecione a pool padrão, selecione a guia Agentes e escolha Novo agente.

4. Na caixa de diálogo Obter o agente , escolha Windows.

5. No painel esquerdo, selecione a arquitetura do processador da versão do sistema operacional Windows instalada em sua máquina. A versão do agente x64 destina-se ao Windows de 64 bits, enquanto a versão x86 se destina ao Windows de 32 bits. Se você não tiver certeza de qual versão do Windows está instalada, siga estas instruções para descobrir.

6. No painel direito, clique no botão Download .

7. Siga as instruções na página para baixar o agente.

8. Descompacte o agente no diretório de sua escolha. Certifique-se de que o caminho para o diretório não contém espaços porque as ferramentas e scripts nem sempre escapam corretamente dos espaços. Uma pasta recomendada é C:\agents. Extrair na pasta de download ou em outras pastas de usuário pode causar problemas de permissão.

Instalar o agente

1. Inicie uma janela elevada (PowerShell) e defina o local para onde você descompactou o agente.

   cd C:\agents 
   
   

2. Execute config.cmd. Isto irá colocar-lhe uma série de perguntas destinadas a configurar o agente.

   .\config.cmd
   
   

URL do servidor

Tipo de autenticação para configuração de agente

Ao registrar um agente, escolha entre os seguintes tipos de autenticação e a configuração solicitará 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 usado 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 TFS.

Escolha o modo interativo ou de serviço

Para obter orientação sobre como executar o agente no modo interativo ou como um serviço, consulte Agents: Interactive vs. service.

Se optar por executar como um serviço (o que recomendamos), o nome de utilizador deve ter 20 caracteres ou menos.

Executar o agente

Executar interativamente

Se você configurou o agente para ser executado interativamente, execute o seguinte comando para iniciar o agente.

.\run.cmd

Para reiniciar o agente, pressione Ctrl+C para parar o agente e execute run.cmd para reiniciá-lo.

variables:
 AZP_AGENT_CLEANUP_PSMODULES_IN_POWERSHELL: "true"

Executar uma vez

Você também pode optar por fazer com que o agente aceite apenas um trabalho e, em seguida, saia. Para executar nessa configuração, use o seguinte comando.

.\run.cmd --once

Os agentes neste modo aceitarão apenas um trabalho e, em seguida, desligarão de forma elegante (útil para execução no Docker num serviço como as Instâncias de Contentor do Azure).

Executar como um serviço

Se você configurou o agente para ser executado como um serviço, ele será iniciado automaticamente. Você pode visualizar e controlar o estado de execução do agente a partir da ferramenta snap-in de serviços. Execute services.msc e procure por um dos seguintes:

• "Azure Pipelines Agent (nome do seu agente)"
• "Agente VSTS (nome do seu agente)"
• "VSTSagent. (nome da organização). (nome do seu agente)"

Para reiniciar o agente, clique com o botão direito do mouse na entrada e escolha Reiniciar.

Para usar o seu agente, execute um trabalho usando o pool do agente. Se você não escolheu um pool diferente, seu agente estará no pool padrão .

Substituir um agente

Para substituir um agente, siga as etapas Baixar e configurar o agente novamente.

Quando você configura um agente usando o mesmo nome de um agente que já existe, você é perguntado se deseja substituir o agente existente. Se responder Y, assegure-se de remover o agente (veja abaixo) que está a substituir. Caso contrário, após alguns minutos de conflitos, um dos agentes será desligado.

Remover e reconfigurar um agente

Para remover o agente:

.\config remove

Depois de remover o agente, você pode configurá-lo novamente .

Configuração não assistida

O agente pode ser configurado a partir de um script sem intervenção humana. Você deve passar --unattended e as respostas para todas as perguntas.

Para configurar um agente, ele deve saber a URL da sua organização ou coleção e as credenciais de alguém autorizado a configurar agentes. Todas as outras respostas são opcionais. Qualquer parâmetro de linha de comando pode ser especificado usando uma variável de ambiente: colocar o seu nome em maiúsculas e prefixar VSTS_AGENT_INPUT_. Por exemplo, VSTS_AGENT_INPUT_PASSWORD em vez de especificar --password.

Opções necessárias

• --unattended - a configuração do agente não solicitará informações e todas as configurações devem ser fornecidas na linha de comando
• --url <url> - URL do servidor. Por exemplo: https://dev.azure.com/myorganization ou http://my-azure-devops-server:8080/tfs
• --auth <type> - tipo de autenticação. Os valores válidos são:
  • pat (Token de acesso pessoal)
  • SP (Entidade de Serviço) (Requer o agente versão 3.227.1 ou mais recente)
  • negotiate (Kerberos ou NTLM)
  • alt (autenticação básica)
  • integrated (credenciais padrão do Windows)

Opções de autenticação

• Se você escolheu --auth pat:
  • --token <token> - especifica o seu token de acesso pessoal
  • Você também pode passar um token OAuth 2.0 como parâmetro --token .
• Se você escolheu --auth negotiate ou --auth alt:
  • --userName <userName> - especifica um nome de utilizador do Windows no formato ___domain\userName ou userName@___domain.com
  • --password <password> - especifica uma senha
• Se você escolheu --auth SP:
  • --clientID <clientID> - especifica o ID do Cliente do Principal de Serviço com acesso para registar agentes
  • --tenantId <tenantID> - especifica o ID do Inquilino no qual a Entidade de Serviço está registada
  • --clientSecret <clientSecret> - especifica o segredo do cliente do Principal de Serviço
  • Veja Registar um agente usando um principal de serviço para mais informações

Nomes de pool e agentes

• --pool <pool> - nome do pool a que o agente se junte
• --agent <agent> - nome do agente
• --replace - Substitua o agente num pool. Se outro agente estiver a ouvir pelo mesmo nome, começará a falhar devido a um conflito.

Configuração do agente

• --work <workDirectory> - diretório de trabalho onde os dados do trabalho são armazenados. Por padrão, utiliza-se _work na raiz do diretório do agente. O diretório de trabalho pertence a um determinado agente e não deve ser compartilhado entre vários agentes.
• --acceptTeeEula - aceite o Contrato de Licença de Usuário Final do Team Explorer Everywhere (somente macOS e Linux)
• --disableloguploads - Não transmita nem envie a saída do log do console para o servidor. Em vez disso, você pode recuperá-los do sistema de arquivos do host do agente após a conclusão do trabalho.

Inicialização somente do Windows

• --runAsService - configurar o agente para ser executado como um serviço do Windows (requer permissão de administrador)
• --runAsAutoLogon - configurar o logon automático e executar o agente na inicialização (requer permissão de administrador)
• --windowsLogonAccount <account> - utilizado com --runAsService ou --runAsAutoLogon para especificar o nome de utilizador do Windows no formato ___domain\userName ou userName@___domain.com
• --windowsLogonPassword <password> - usado com --runAsService ou --runAsAutoLogon para especificar a senha de logon do Windows (não necessário para Contas de Serviço Gerenciado de Grupo e contas integradas do Windows, como 'NT AUTHORITY\NETWORK SERVICE')
• --enableservicesidtypeunrestricted - usado com --runAsService para configurar o agente com o tipo SID de serviço como SERVICE_SID_TYPE_UNRESTRICTED (requer permissão de administrador)
• --overwriteAutoLogon - usado com --runAsAutoLogon para substituir o logon automático existente na máquina
• --noRestart - usado com --runAsAutoLogon para impedir que o host seja reiniciado após a conclusão da configuração do agente

Resolução de problemas na configuração do agente com a opção runAsAutoLogon

Configurar o agente com a runAsAutoLogon opção executa o agente cada vez depois de reiniciar a máquina. Execute as próximas etapas se o agente não for executado após reiniciar a máquina.

Se o agente já estava configurado na máquina

Antes de reconfigurar o agente, é necessário remover a configuração antiga do agente, portanto, tente executar este comando a partir da pasta do agente:

.\config.cmd remove --auth 'PAT' --token '<token>'

Verifique se o agente foi removido do pool de agentes depois de executar o comando:

<Azure DevOps organization> / <Project> / Settings / Agent pools / <Agent Pool> / Agents

Remova o agente do pool de agentes manualmente se ele não tiver sido removido executando o comando.

Em seguida, tente reconfigurar o agente executando este comando na pasta do agente:

.\config.cmd --unattended --agent '<agent-name>' --pool '<agent-pool-name>' --url '<azure-dev-ops-organization-url>' --auth 'PAT' --token '<token>' --runAsAutoLogon --windowsLogonAccount '<___domain\user-name>' --windowsLogonPassword '<windows-password>'

Especifique o nome do agente (qualquer nome exclusivo específico) e verifique se esse agente apareceu no pool de agentes após a reconfiguração.

Será muito melhor descompactar um arquivo do agente (que pode ser baixado aqui) e executar esse comando a partir da nova pasta do agente descompactado.

Verifique se a chave de registo do Windows está registada e guardada corretamente

Execute o comando whoami /user para obter o <sid>. Abra Registry Editor e siga o caminho:

Computer\HKEY_USERS\<sid>\SOFTWARE\Microsoft\Windows\CurrentVersion\Run

Verifique se existe a VSTSAgent chave. Exclua essa chave se ela existir, feche Registry Editor e configure o agente executando o .\config.cmd comando (sem args) da pasta do agente. Antes de responder à pergunta Enter Restart the machine at a later time?, abra Registry Editor novamente e verifique se a VSTSAgent chave apareceu. Pressione Enter para responder à pergunta e verifique se a VSTSAgent chave permanece em seu lugar depois de reiniciar a máquina.

Verifique se as chaves de registo do Windows funcionam bem na sua máquina

Crie um autorun.cmd arquivo que contenha a seguinte linha: echo "Hello from AutoRun!". Abra Registry Editor e crie no caminho acima um novo par chave-valor com a chave AutoRun e o valor

C:\windows\system32\cmd.exe /D /S /C start "AutoRun" "D:\path\to\autorun.cmd"

Reinicie o computador. Você tem um problema com as chaves do Registro do Windows se não vir uma janela do console com a mensagem Hello from AutoRun!.

Apenas grupo de implantação

• --deploymentGroup - Configurar o agente como um agente do grupo de implantação
• --deploymentGroupName <name> - usado com --deploymentGroup para especificar o grupo de implantação ao qual o agente deve aderir
• --projectName <name> - usado com --deploymentGroup para definir o nome do projeto
• --addDeploymentGroupTags - usado com --deploymentGroup para indicar que as tags do grupo de implantação devem ser adicionadas
• --deploymentGroupTags <tags> - usado com --addDeploymentGroupTags para especificar a lista separada por vírgulas de tags para o agente do grupo de implantação - por exemplo, "web, db"

Somente ambientes

• --addvirtualmachineresourcetags - usado para indicar que as tags de recursos de ambiente devem ser adicionadas
• --virtualmachineresourcetags <tags> - usado com --addvirtualmachineresourcetags para especificar a lista separada por vírgulas de tags para o agente de recursos de ambiente - por exemplo, "web, db"

.\config --help sempre lista as últimas respostas obrigatórias e opcionais.

Diagnóstico

Se estiveres a ter problemas com o teu agente auto-hospedado, podes tentar executar diagnósticos. Depois de configurar o agente:

.\run --diagnostics

Isso irá passar por um conjunto de ferramentas de diagnóstico que pode ajudá-lo a solucionar o problema. O recurso de diagnóstico está disponível a partir da versão 2.165.0 do agente.

Ajuda sobre outras opções

Para saber mais sobre outras opções:

.\config --help

A ajuda fornece informações sobre alternativas de autenticação e configuração não assistida.

Capacidades

As capacidades do seu agente são catalogadas e divulgadas no pool, de modo que apenas as compilações e versões que ele pode gerir sejam atribuídas a ele. Consulte as capacidades do agente de construção e liberação .

Em muitos casos, depois de implantar um agente, você precisará instalar software ou utilitários. Geralmente, você deve instalar em seus agentes qualquer software e ferramentas que você usa em sua máquina de desenvolvimento.

Por exemplo, se sua compilação incluir a tarefa npm, a compilação não será executada a menos que haja um agente de compilação no pool que tenha o npm instalado.

FAQ

Qual versão do Git meu agente executa?

Por padrão, o agente do Windows usa a versão do Git que acompanha o software do agente. A Microsoft recomenda usar a versão do Git que acompanha o agente, mas você tem várias opções para substituir esse comportamento padrão e usar a versão do Git que a máquina do agente instalou no caminho.

• Defina uma variável de pipeline denominada System.PreferGitFromPath como true nos seus pipelines.
• Em agentes auto-hospedados, você pode criar um arquivo chamado .env no diretório raiz do agente e adicionar uma System.PreferGitFromPath=true linha ao arquivo. Para obter mais informações, consulte Como definir variáveis de ambiente diferentes para cada agente individual?

Para ver a versão do Git usada por um pipeline, podes examinar os logs de uma etapa checkout no teu pipeline, conforme mostrado no exemplo a seguir.

Syncing repository: PathFilter (Git)
Prepending Path environment variable with directory containing 'git.exe'.
git version
git version 2.26.2.windows.1

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

1. Navegue até ao 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. Clique no pool que contém o agente.

3. Verifique se o agente está habilitado.

4. Navegue até 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.

      

      Observação

      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 verificar esse valor em relação à versão mais recente do agente publicada. Consulte Azure Pipelines Agent e verifique na página o número da versão mais alta listado.

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

13.107.6.0/24
13.107.9.0/24
13.107.42.0/24
13.107.43.0/24
150.171.22.0/24 
150.171.23.0/24 
150.171.73.0/24 
150.171.74.0/24 
150.171.75.0/24 
150.171.76.0/24

2620:1ec:4::/48
2620:1ec:a92::/48
2620:1ec:21::/48
2620:1ec:22::/48
2620:1ec:50::/48 
2620:1ec:51::/48 
2603:1061:10::/48

Como posso executar o agente com um certificado autoassinado?

Execute o agente com certificado autoassinado

Como executar o agente atrás de um proxy web?

Executar o agente atrás de um proxy web

Como posso reiniciar o agente

Se você estiver executando o agente interativamente, consulte as instruções de reinicialização em Executar interativamente. Se você estiver executando o agente como um serviço, reinicie o agente seguindo as etapas em Executar como um serviço.

MyEnv0=MyEnvValue0
MyEnv1=MyEnvValue1
MyEnv2=MyEnvValue2
MyEnv3=MyEnvValue3
MyEnv4=MyEnvValue4

https://login.microsoftonline.com
https://app.vssps.visualstudio.com 
https://{organization_name}.visualstudio.com
https://{organization_name}.vsrm.visualstudio.com
https://{organization_name}.vstmr.visualstudio.com
https://{organization_name}.pkgs.visualstudio.com
https://{organization_name}.vssps.visualstudio.com

https://dev.azure.com
https://*.dev.azure.com
https://login.microsoftonline.com
https://management.core.windows.net
https://download.agent.dev.azure.com
https://vssps.dev.azure.com

13.107.6.0/24
13.107.9.0/24
13.107.42.0/24
13.107.43.0/24
150.171.22.0/24 
150.171.23.0/24 
150.171.73.0/24 
150.171.74.0/24 
150.171.75.0/24 
150.171.76.0/24

2620:1ec:4::/48
2620:1ec:a92::/48
2620:1ec:21::/48
2620:1ec:22::/48
2620:1ec:50::/48 
2620:1ec:51::/48 
2603:1061:10::/48

O que é habilitar SERVICE_SID_TYPE_UNRESTRICTED para o serviço do agente?

Ao configurar o software do agente no Windows Server, você pode especificar o identificador de segurança do serviço no prompt a seguir.

Enter enable SERVICE_SID_TYPE_UNRESTRICTED for agent service (Y/N) (press enter for N)

As versões anteriores do software do agente definiam o tipo de identificador de segurança do serviço como SERVICE_SID_TYPE_NONE, que é o valor padrão para as versões atuais do agente. Para configurar o tipo de identificador do serviço de segurança para SERVICE_SID_TYPE_UNRESTRICTED, pressione Y.

Para obter mais informações, consulte SERVICE_SID_INFO estrutura e identificadores de segurança.