Exercício – Criar um agente de build em execução no Azure

  • 20 minutos

Nesta unidade, para configurar um agente de build que pode ser usado no Microsoft Azure Pipelines, você usará uma máquina virtual executada no Microsoft Azure. Nós fornecemos uma máquina virtual que você pode usar ao longo deste módulo.

Nesta unidade, você:

  • Criar uma máquina virtual do Ubuntu no Azure para servir como o agente de build.
  • Criar um pool de agentes no Microsoft Azure DevOps.
  • Criar um token de acesso para autenticar seu agente com o Azure DevOps.
  • Configurar o agente com o software necessário para criar o site do Space Game.
  • Configurar o agente para se conectar ao Azure DevOps para que ele possa receber trabalhos de build.
  • Verificar se o agente está conectado ao Azure DevOps e pronto para receber trabalhos de build.

Há muitas maneiras de criar uma máquina virtual no Azure. Nesta unidade, você criará uma máquina virtual do Ubuntu usando um terminal interativo chamado Cloud Shell.

Para configurar sua VM, há várias opções:

  • Para uma VM do Linux, você pode se conectar diretamente por SSH e configurar o sistema interativamente.
  • Você pode automatizar a implantação usando um modelo do ARM, o Bicep ou outra ferramenta de provisionamento automatizado.
  • Se você precisar implantar vários agentes de build, poderá criar uma imagem de VM que tem todo o software pré-instalado.

Configurar um sistema de forma interativa é uma boa maneira de começar porque ajuda a compreender o processo e o que é necessário. Para simplificar o processo, conecte-se à VM do Ubuntu por SSH e execute scripts do shell para configurar o agente de build.

Observação

Se você não está familiarizado com a conexão ou a configuração de sistemas Linux, basta acompanhar. Você pode aplicar os mesmos conceitos a agentes de build do Windows.

Criar uma máquina virtual do Linux

Nesta seção, você criará uma VM que executa o Ubuntu 20.04 e que servirá como o agente de build. A VM ainda não está configurada para ser um agente de build nem para ter as ferramentas necessárias para compilar o aplicativo Web Space Game. Você configurará isso em breve.

Ativar o Cloud Shell por meio do portal do Azure

Importante

Para concluir os exercícios neste módulo, você precisará de sua assinatura do Azure.

  1. Acesse o portal do Azure e entre.

  2. No menu, selecione Cloud Shell. Quando solicitado, escolha a experiência do Bash.

    A screenshot of the Azure portal showing the location of the Cloud Shell menu item.

    Observação

    O Cloud Shell exige um recurso de Armazenamento do Azure para manter todos os arquivos que você criar no Cloud Shell. Ao abrir o Cloud Shell pela primeira vez, você precisará criar um grupo de recursos, uma conta de armazenamento e um compartilhamento de arquivo do Azure. Essa configuração é usada automaticamente para todas as sessões futuras do Cloud Shell.

Selecionar uma região do Azure

Uma região é um ou mais datacenters do Azure em uma localização geográfica. Leste dos EUA, Oeste dos EUA e Norte da Europa são exemplos de regiões. Todos os recursos do Azure, incluindo uma VM do Azure, são atribuídos a uma região.

Para facilitar a execução dos comandos, comece selecionando uma região padrão. Depois que você especificar a região padrão, os comandos posteriores usarão essa região, a menos que você especifique outra.

  1. No Cloud Shell, para listar as regiões disponíveis em sua assinatura do Azure, execute o seguinte comando az account list-locations:

    az account list-locations \
  --query "[].{Name: name, DisplayName: displayName}" \
  --output table

  2. Na coluna Name na saída, selecione uma região perto de você. Por exemplo, escolha eastasia ou westus2.

  3. Execute az configure para definir a região padrão. Substitua <REGION> pelo nome da região selecionada:

    az configure --defaults location=<REGION>

    Este exemplo define westus2 como a região padrão:

    az configure --defaults location=westus2

Criar um grupo de recursos

Crie um grupo de recursos para conter os recursos usados neste módulo de treinamento.

  • Para criar um grupo de recursos chamado tailspin-space-game-rg, execute o seguinte comando az group create:

    az group create --name tailspin-space-game-rg

Criar a VM

Para criar sua VM, execute o seguinte comando az vm create:

az vm create \
    --name MyLinuxAgent \
    --resource-group tailspin-space-game-rg \
    --image canonical:0001-com-ubuntu-server-focal:20_04-lts:latest \
    --size Standard_DS2_v2 \
    --admin-username azureuser \
    --generate-ssh-keys

A sua VM levará alguns minutos para ser exibida.

Standard_DS2_v2 especifica o tamanho da VM. O tamanho de uma VM define a velocidade do processador, a quantidade de memória, a quantidade inicial de armazenamento e a largura de banda da rede esperada. Esse é o mesmo tamanho fornecido pelos agentes hospedados pela Microsoft. Na prática, você pode escolher um tamanho que fornece mais capacidade de computação ou funcionalidades adicionais, como o processamento de gráficos.

O argumento --resource-group especifica o grupo de recursos que contém tudo o que precisamos criar. Um grupo de recursos permite a você administrar todas as VMs, discos, adaptadores de rede e outros elementos que compõem a solução como uma unidade.

Criar o pool de agentes

Lembre-se de que um pool de agentes organiza os agentes de build. Nesta seção, você criará o pool de agentes no Azure DevOps. Posteriormente, você especificará o nome do pool de agentes ao configurar seu agente para que ele possa se registrar para o pool correto.

  1. No Azure DevOps, navegue até o projeto Space Game – Web – Agente.

  2. Selecione Project settings.

  3. Em Pipelines, selecione Pools de agente.

    A screenshot of the project settings in Azure DevOps showing the location of the Agent pools menu item.

  4. Selecione Add pool.

  5. Na janela Adicionar pool:

    1. Em Pool to link, selecione New.
    2. Em Pool type, selecione Self-hosted.
    3. Em Name, insira MyAgentPool.

    Na prática, você escolheria um nome mais descritivo para o pool.

  6. Selecione Criar. Você verá o novo pool de agentes aparecer na lista.

Criar um token de acesso pessoal

Para o agente de build se registrar com o Azure DevOps, você precisa de um modo para que ele se autentique.

Para fazer isso, você pode criar um token de acesso pessoal. Um token de acesso pessoal — ou PAT — é uma alternativa a uma senha. Você pode usar o PAT para autenticar com serviços como o Azure DevOps.

Importante

Como faria ao usar uma senha, mantenha sempre o token de acesso em um local seguro. Nesta seção, você armazenará seu token de acesso como uma variável de ambiente para que ele não apareça no script do shell.

  1. No Azure DevOps, abra as configurações de perfil e selecione tokens de acesso pessoal.

    A screenshot of Azure DevOps showing the location of the Personal access tokens menu item.

  2. Selecione New Token.

  3. Insira um nome para o token, como Agente de build.

  4. Em Escopos, selecione o link Mostrar todos os escopos na parte inferior.

  5. Procure Pools de agentes e selecione Ler e gerenciar.

  6. Selecione Criar.

  7. Copie o token para um local seguro.

    Em breve, você usará seu token para habilitar o agente de build para autenticar o acesso ao Azure Pipelines.

Conectar-se à sua VM

Nesta seção, você se conectará à VM do Linux por SSH para poder configurá-la.

Lembre-se de que você não pode entrar interativamente em um agente hospedado pela Microsoft. Como um agente de build privado é seu, você pode entrar e configurá-lo como desejar.

A capacidade de se conectar ao agente de build permite que você o configure com as ferramentas necessárias para criar o seu software. Ele também permite que você solucione problemas à medida que cria sua configuração de pipeline.

  1. Para obter o endereço IP da VM, execute az vm show no Cloud Shell:

    IPADDRESS=$(az vm show \
  --name MyLinuxAgent \
  --resource-group tailspin-space-game-rg \
  --show-details \
  --query [publicIps] \
  --output tsv)

    Este comando armazena o endereço IP em uma variável de Bash chamada IPADDRESS.

  2. Imprima o endereço IP da VM no console:

    echo $IPADDRESS

  3. Crie uma conexão SSH para a VM. No lugar de $IPADDRESS, insira o endereço IP recebido na etapa anterior. No prompt, insira sim para prosseguir com a conexão.

    ssh azureuser@$IPADDRESS

    Agora você está conectado à sua VM por SSH.

    Esse comando funciona porque você forneceu a opção --generate-ssh-keys quando executou az vm create anteriormente. Essa opção cria um par de chaves SSH para que você possa entrar na VM.

Instalar ferramentas de build na sua VM

Nesta seção, você configurará sua VM com as ferramentas necessárias para criar o site do Space Game.

Lembre-se de que o processo de build existente usa essas ferramentas:

  • SDK do .NET, que é usado para criar o aplicativo
  • Node.js, que é usado para executar tarefas de build
  • npm, o gerenciador de pacotes do Node.js
  • gulp, um pacote de Node.js que é usado para minificar arquivos JavaScript e CSS

Essas são as principais ferramentas que o processo de build requer. Para instalá-los, você deverá baixar e executar um script de shell do GitHub.

Observação

O processo de build usa outras ferramentas, como node-sass para converter arquivos do Sass (.scss) em arquivos CSS (.css). No entanto, o Node.js instala essas ferramentas quando o build é executado.

Vamos começar atualizando o gerenciador de pacotes do Ubuntu, chamado apt. Essa ação busca as informações mais recentes dos repositórios de pacote e é geralmente a primeira coisa que você faz ao configurar um novo sistema Ubuntu.

  1. Em sua conexão SSH, atualize o cache do gerenciador de pacotes apt:

    sudo apt-get update

    sudo executa o comando com privilégios de administrador ou raiz.

  2. Execute o seguinte comando curl para baixar um script de shell chamado build-tools.sh do GitHub:

    curl https://raw.githubusercontent.com/MicrosoftDocs/mslearn-tailspin-spacegame-web/main/.agent-tools/build-tools.sh > build-tools.sh

  3. Imprima o script no terminal para que você possa examinar o seu conteúdo:

    cat build-tools.sh

    O seguinte resultado é exibido:

    #!/bin/bash
set -e

# Select a default .NET version if one is not specified
if [ -z "$DOTNET_VERSION" ]; then
  DOTNET_VERSION=6.0.300
fi

# Add the Node.js PPA so that we can install the latest version
curl -sL https://deb.nodesource.com/setup_16.x | bash -

# Install Node.js and jq
apt-get install -y nodejs

apt-get install -y jq

# Install gulp
npm install -g gulp

# Change ownership of the .npm directory to the sudo (non-root) user
chown -R $SUDO_USER ~/.npm

# Install .NET as the sudo (non-root) user
sudo -i -u $SUDO_USER bash << EOF
curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin -c LTS -v $DOTNET_VERSION
EOF

    O script instala o Node.js, o npm, o gulp e o .NET Core.

    Ao configurar a variável de ambiente DOTNET_VERSION, você pode especificar a versão do .NET a ser instalada. Se você não definir essa variável, o script instalará a versão que sua configuração de build existente usa. Para fins de aprendizado, você não define essa variável. Você permite que o script use a versão padrão.

  4. Torne o script executável e execute o script:

    chmod u+x build-tools.sh
sudo ./build-tools.sh

    O script demora alguns minutos para ser executado.

    Na prática, agora você pode executar comandos para verificar se cada componente de software foi instalado com êxito.

Instalar o software do agente na sua VM

Agora é hora de instalar o software do agente em sua VM. Esse software permite que a VM atue como um agente de build e receba trabalhos de build do Azure Pipelines.

O processo de registro verifica a existência de software instalado antes de registrar o agente com o Azure Pipelines. Portanto, é importante que você configure o agente depois de instalar todos os outros programas de software. Na prática, você poderá registrar o agente uma segunda vez se precisar instalar software adicional.

A documentação explica como configurar os agentes do Linux auto-hospedados, bem como os agentes do macOS e do Windows, manualmente. Você executa um script de shell para configurar seu agente da mesma forma que configurou ferramentas de build na seção anterior.

Importante

O script que você executará aqui é para fins de aprendizado. Na prática, você deve primeiro entender como cada comando nos scripts que você compila afeta o sistema em geral. Ao final do módulo, direcionaremos você para a documentação que descreve de maneira mais completa as suas opções.

  1. Para baixar um script de shell chamado build-agent.sh do GitHub, execute o seguinte comando curl:

    curl https://raw.githubusercontent.com/MicrosoftDocs/mslearn-tailspin-spacegame-web/main/.agent-tools/build-agent.sh > build-agent.sh

  2. Imprima o script no terminal para que você possa examinar o seu conteúdo:

    cat build-agent.sh

    O seguinte resultado é exibido:

    #!/bin/bash
set -e

# Select a default agent version if one is not specified
if [ -z "$AZP_AGENT_VERSION" ]; then
  AZP_AGENT_VERSION=2.187.2
fi

# Verify Azure Pipelines token is set
if [ -z "$AZP_TOKEN" ]; then
  echo 1>&2 "error: missing AZP_TOKEN environment variable"
  exit 1
fi

# Verify Azure DevOps URL is set
if [ -z "$AZP_URL" ]; then
  echo 1>&2 "error: missing AZP_URL environment variable"
  exit 1
fi

# If a working directory was specified, create that directory
if [ -n "$AZP_WORK" ]; then
  mkdir -p "$AZP_WORK"
fi

# Create the Downloads directory under the user's home directory
if [ -n "$HOME/Downloads" ]; then
  mkdir -p "$HOME/Downloads"
fi

# Download the agent package
curl https://vstsagentpackage.azureedge.net/agent/$AZP_AGENT_VERSION/vsts-agent-linux-x64-$AZP_AGENT_VERSION.tar.gz > $HOME/Downloads/vsts-agent-linux-x64-$AZP_AGENT_VERSION.tar.gz

# Create the working directory for the agent service to run jobs under
if [ -n "$AZP_WORK" ]; then
  mkdir -p "$AZP_WORK"
fi

# Create a working directory to extract the agent package to
mkdir -p $HOME/azp/agent

# Move to the working directory
cd $HOME/azp/agent

# Extract the agent package to the working directory
tar zxvf $HOME/Downloads/vsts-agent-linux-x64-$AZP_AGENT_VERSION.tar.gz

# Install the agent software
./bin/installdependencies.sh

# Configure the agent as the sudo (non-root) user
chown $SUDO_USER $HOME/azp/agent
sudo -u $SUDO_USER ./config.sh --unattended \
  --agent "${AZP_AGENT_NAME:-$(hostname)}" \
  --url "$AZP_URL" \
  --auth PAT \
  --token "$AZP_TOKEN" \
  --pool "${AZP_POOL:-Default}" \
  --work "${AZP_WORK:-_work}" \
  --replace \
  --acceptTeeEula

# Install and start the agent service
./svc.sh install
./svc.sh start

    Você não precisa entender o funcionamento de cada linha, mas aqui está um breve resumo do que esse script faz:

    • Baixa o pacote do agente como um arquivo .tar.gz e extrai o conteúdo dele.
    • Nos arquivos extraídos, o script:
      • Executa um script de shell chamado installdependencies.sh para instalar o software do agente.
      • Executa um script de shell chamado config.sh para configurar o agente e registrá-lo como Azure Pipelines.
      • Executa um script de shell chamado svc.sh para instalar e iniciar o serviço do agente.

    O script usa variáveis de ambiente para que você possa fornecer detalhes sobre a sua organização do Azure DevOps. Segue um resumo:

    Variável de bash Descrição Padrão
    AZP_AGENT_VERSION A versão do software o agente a ser instalada A versão que usamos por último nesse módulo
    AZP_URL A URL da sua organização do Azure DevOps (Nenhuma)
    AZP_TOKEN Seu token de acesso pessoal (Nenhuma)
    AZP_AGENT_NAME Nome do seu agente conforme ele aparece no Azure DevOps Nome de host do sistema
    AZP_POOL Nome do seu pool de agentes Padrão
    AZP_WORK O diretório de trabalho para o agente realizar tarefas de build _work

    Se o script não fornecer um valor padrão para uma variável que não está definida, o script imprimirá uma mensagem de erro e fechará imediatamente.

    Nas seguintes etapas, você definirá essas variáveis de ambiente:

    • AZP_AGENT_VERSION
    • AZP_URL
    • AZP_TOKEN
    • AZP_AGENT_NAME
    • AZP_POOL

    Por enquanto, é recomendável que você deixe as outras variáveis indefinidas.

  3. Defina a variável de ambiente AZP_AGENT_NAME para especificar o nome do seu agente. Recomendamos MyLinuxAgent.

    export AZP_AGENT_NAME=MyLinuxAgent

  4. Defina a variável de ambiente AZP_URL para especificar a URL para sua organização do Azure DevOps.

    Substitua <organization> pela sua organização. Você pode obter o nome da guia do navegador que está mostrando o Azure DevOps.

    export AZP_URL=https://dev.azure.com/organization

  5. Defina a variável de ambiente AZP_TOKEN para especificar seu token de acesso pessoal (o valor de token longo copiado anteriormente nesta unidade).

    Substitua <token> pelo seu token.

    export AZP_TOKEN=token

  6. Defina a variável de ambiente AZP_POOL para especificar o nome do seu pool de agentes. Anteriormente, você criou um pool chamado MyAgentPool.

    export AZP_POOL=MyAgentPool

  7. Defina a variável de ambiente AZP_AGENT_VERSION para especificar a versão mais recente do agente.

    export AZP_AGENT_VERSION=$(curl -s https://api.github.com/repos/microsoft/azure-pipelines-agent/releases | jq -r '.[0].tag_name' | cut -d "v" -f 2)

    Um pipeline YAML em um computador Linux precisa estar usando a versão mais recente do agente, mesmo que seja de pré-lançamento. O software do agente é atualizado constantemente, de modo que você curl as informações de versão do repositório GitHub. O comando usa jq para ler a versão mais recente da cadeia de caracteres JSON retornada.

  8. Imprima a versão do agente no console. Opcionalmente, verifique se essa é a versão mais recente.

    echo $AZP_AGENT_VERSION

  9. Torne o script executável e execute-o:

    chmod u+x build-agent.sh
sudo -E ./build-agent.sh

    sudo permite que o script seja executado como o usuário raiz. O argumento -E preserva as variáveis de ambiente atuais, incluindo as que você definir, para que fiquem disponíveis para o script.

    Conforme o script é executado, você vê o agente se conectar ao Azure DevOps, vê o agente adicionado ao pool de agentes e vê a conexão do agente ser testada.

Verificar se o agente está em execução

Você instalou com êxito as ferramentas de build e o software do agente em sua VM. Como uma etapa de verificação, acesse o Azure DevOps e veja o agente no pool de agentes.

  1. No Azure DevOps, navegue até o projeto Space Game – Web – Agente.

  2. Selecione Project settings.

  3. Em Pipelines, selecione Pools de agente.

  4. Selecione MyAgentPool.

  5. Selecione a guia Agentes.

    Você vê que o agente está online e pronto para aceitar trabalhos de build.

    A screenshot of Azure DevOps showing the status of the private agent. The agent shows as online, idle, and enabled.

    Dica

    Se o agente de build aparecer como Offline, experimente aguardar um pouco e, depois, atualize a página.

  6. Selecione seu agente, MyLinuxAgent.

  7. Selecione a guia Funcionalidades.

    Durante a instalação, o processo de configuração examinou seu agente de build quanto às funcionalidades da ferramenta. Você verá que npm está listado como uma delas. Lembre-se de que sua configuração de build original especificava que npm deve ser instalado no agente.

    A screenshot of Azure DevOps showing a few of the agent's capabilities. The npm capability is highlighted.

    Ao especificar qual pool de agentes usar, você pode incluir qualquer uma dessas entradas na seção demands. A inclusão delas garante que o Azure Pipelines escolha um agente de build que tem o software necessário para compilar o aplicativo. Ele também permite que você crie pools de agentes com várias configurações de software. O Azure Pipelines selecionará a configuração correta com base em seus requisitos.