Exercício - Criar um agente de compilação que é executado no Azure

  • 20 minutos

Nesta unidade, para configurar um agente de compilação que você pode usar no Microsoft Azure Pipelines, você usará uma máquina virtual que é executada no Microsoft Azure. Nós fornecemos uma máquina virtual que você pode usar durante a duração deste módulo.

Nesta unidade, irá:

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

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

Para configurar sua VM, você tem várias opções:

  • Para uma VM Linux, você pode se conectar diretamente por SSH e configurar interativamente seu sistema.
  • Você pode automatizar a implantação usando um modelo ARM, Bíceps ou outra ferramenta de provisionamento automatizado.
  • Se você precisar implantar muitos agentes de compilação, poderá criar uma imagem de VM com todo o software pré-instalado.

Configurar um sistema de forma interativa é uma boa maneira de começar, pois ajuda você a entender o processo e o que é necessário. Para simplificar o processo, conecte-se à sua VM Ubuntu por SSH e execute shell scripts para configurar seu agente de compilação.

Observação

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

Criar uma máquina virtual Linux

Nesta seção, você cria uma VM que está executando o Ubuntu 20.04, que servirá como seu agente de compilação. A VM ainda não está configurada para ser um agente de compilação ou ter qualquer uma das ferramentas necessárias para criar o Space Game aplicativo Web. Você vai configurar isso em breve.

Abrir o Cloud Shell através do portal do Azure

Importante

Para concluir os exercícios neste módulo, você precisa de sua própria assinatura do Azure.

  1. Vá para o Azure portal e entre.

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

    Uma captura de tela do portal do Azure mostrando o local do item de menu do Cloud Shell.

    Observação

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

Selecione uma região do Azure

Uma região é um ou mais datacenters do Azure dentro de uma localização geográfica. O Leste dos EUA, o Oeste dos EUA e o Norte da Europa são exemplos de regiões. Cada recurso do Azure, incluindo uma VM do Azure, recebe uma região.

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

  1. No Cloud Shell, para listar as regiões disponíveis na 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 próxima a você. Por exemplo, escolha eastasia ou westus2.

  3. Execute az configure para definir sua 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

Sua VM levará alguns minutos para aparecer.

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 de rede esperada. Este é o mesmo tamanho que é fornecido por agentes hospedados pela Microsoft. Na prática, você pode escolher um tamanho que forneça mais poder de computação ou recursos adicionais, como processamento gráfico.

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

Criar o pool de agentes

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

  1. No Azure DevOps, vá para o projeto Space Game - Web - Agent.

  2. Selecione Configurações do projeto.

  3. Em Pipelines, selecione Grupos de agentes.

    Uma captura de tela das configurações do projeto no Azure DevOps mostrando o local do item de menu Pools de agentes.

  4. Selecione Adicionar pool.

  5. Na janela Adicionar pool:

    1. Em Pool para vincular, selecione Novo.
    2. Em Tipo de pool, selecione Auto-hospedada.
    3. Em Nome, introduza MyAgentPool.

    Na prática, você escolheria um nome mais descritivo para sua piscina.

  6. Selecione Criar. O novo pool de agentes aparece na lista.

Criar um token de acesso pessoal

Para que seu agente de compilação se registre no Azure DevOps, você precisa de uma maneira de se autenticar.

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 a PAT para autenticar com serviços como o Azure DevOps.

Importante

Tal como faria com uma palavra-passe, certifique-se de que mantém o seu token de acesso num local seguro. Nesta seção, você armazenará seu token de acesso como uma variável de ambiente para que ele não apareça em seu shell script.

  1. No Azure DevOps, abra as suas definições de perfil e, em seguida, selecione tokens de acesso pessoal.

    Uma captura de tela do Azure DevOps mostrando o local do item de menu Tokens de acesso pessoal.

  2. Selecione Novo Token.

  3. Insira um nome para seu token, como agente Build.

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

  5. Procure por Agent Poolse depois selecione Ler & gerir.

  6. Selecione Criar.

  7. Copie o token para um local seguro.

    Em breve, você usará seu token para permitir que seu agente de compilação autentique o acesso ao Azure Pipelines.

Conectar-se à sua VM

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

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

A capacidade de se conectar ao seu agente de compilação permite configurá-lo com as ferramentas necessárias para criar seu software. Ele também permite que você solucione problemas à medida que constrói sua configuração de pipeline.

  1. Para obter o endereço IP da sua 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 Bash chamada IPADDRESS.

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

    echo $IPADDRESS

  3. Crie uma conexão SSH com sua VM. Em vez de $IPADDRESS, digite o endereço IP que você recebeu na etapa anterior. No prompt, digite sim para continuar se conectando.

    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, que permite que você entre na VM.

Instalar ferramentas de compilação em sua VM

Nesta seção, irá configurar a sua Máquina Virtual (VM) com as ferramentas necessárias para construir o site Space Game.

Lembre-se de que seu processo de compilação existente usa estas ferramentas:

  • SDK do .NET, que é usado para criar o aplicativo
  • Node.js, que é usado para executar tarefas de compilação
  • npm, o gerenciador de pacotes para 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 compilação exige. Para instalá-los, você baixará e executará um shell script do GitHub.

Observação

O processo de compilação usa outras ferramentas, como node-sass, para converter arquivos Sass (.scss) em arquivos CSS (.css). No entanto, Node.js instala essas ferramentas quando a compilação é executada.

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

  1. Na 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 root.

  2. Para baixar um shell script chamado build-tools.sh do GitHub, execute o seguinte comando curl:

    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 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 Node.js, npm, gulp e .NET Core.

    Definindo 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 usada pela configuração de compilação existente. Para fins de aprendizagem, 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, em seguida, execute o script:

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

    O script leva alguns minutos para ser executado.

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

Instale o software do agente em sua VM

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

O processo de registro verifica se há software instalado antes de registrar o agente no Azure Pipelines. Portanto, é importante configurar o agente depois de instalar todos os outros softwares. Na prática, você pode registrar o agente uma segunda vez se precisar instalar software adicional.

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

Importante

O script que você executa aqui é para fins de aprendizagem. Na prática, você deve primeiro entender como cada comando nos scripts que você cria afeta o sistema geral. No final do módulo, apontaremos para a documentação que descreve mais completamente as suas opções.

  1. Para baixar um shell script 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 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 como cada linha funciona, mas aqui está um breve resumo do que esse script faz:

    • Ele baixa o pacote do agente como um arquivo .tar.gz e extrai seu conteúdo.
    • Nos arquivos extraídos, o script:
      • Executa um shell script chamado installdependencies.sh para instalar o software do agente.
      • Executa um shell script chamado config.sh para configurar o agente e registrar o agente no Azure Pipelines.
      • Executa um shell script chamado svc.sh para instalar e iniciar o serviço do agente.

    O script usa variáveis de ambiente para permitir que você forneça detalhes sobre sua organização do Azure DevOps. Aqui está um resumo:

    Variável Bash Descrição Padrão
    AZP_AGENT_VERSION A versão do software do agente a instalar A última versão que usamos para testar este módulo
    AZP_URL A URL da sua organização do Azure DevOps (Nenhum)
    AZP_TOKEN O seu token de acesso pessoal (Nenhum)
    AZP_AGENT_NAME O nome do seu agente tal como aparece no Azure DevOps O nome do host do sistema
    AZP_POOL O nome do seu pool de agentes Padrão
    AZP_WORK O diretório de trabalho para o agente executar tarefas de compilação _trabalho

    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 será encerrado imediatamente.

    Nas etapas a seguir, defina estas variáveis de ambiente:

    • AZP_AGENT_VERSION
    • AZP_URL
    • AZP_TOKEN
    • AZP_AGENT_NAME
    • AZP_POOL

    Por enquanto, recomendamos que você deixe as outras variáveis desdefinidas.

  3. Defina a variável de ambiente AZP_AGENT_NAME para especificar o nome do 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 <organização> pela sua. Você pode obter o nome no separador do navegador que exibe 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 que você copiou 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 numa máquina Linux deverá usar a versão mais recente do agente, mesmo que seja pré-lançada. O software do agente é atualizado constantemente, então você curl as informações de versão do o 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 na consola. Opcionalmente, verifique para se certificar de que esta é a versão mais recente.

    echo $AZP_AGENT_VERSION

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

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

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

    À medida que o script é executado, você pode ver o agente se conectar ao Azure DevOps, vê-lo adicionado ao pool de agentes e ver a conexão do agente ser testada.

Verifique se o agente está em execução

Você instalou com êxito as ferramentas de compilação e o software do agente em sua VM. Como etapa de verificação, vá para Azure DevOps e veja seu agente no pool de agentes.

  1. No Azure DevOps, vá para o projeto Space Game - Web - Agent.

  2. Selecione Configurações do projeto.

  3. Em Pipelines, selecione Grupos de Agentes.

  4. Selecione MyAgentPool.

  5. Selecione o separador Agentes.

    Você pode ver que seu agente está on-line e pronto para aceitar trabalhos de construção.

    Uma captura de tela do Azure DevOps mostrando o status do agente privado. O agente aparece como online, ocioso e habilitado.

    Dica

    Se o agente de compilação aparecer como Offline, tente aguardar alguns momentos e, em seguida, recarregar a página.

  6. Selecione seu agente MyLinuxAgent.

  7. Selecione a guia Capacidades.

    Durante a configuração, o processo de configuração examinou o agente de compilação em busca de capacidades da ferramenta. Você vê que npm está listado como um deles. Lembre-se de que sua configuração de compilação original especificou que npm deve ser instalado no agente.

    Uma captura de tela do Azure DevOps mostrando alguns dos recursos do agente. A capacidade npm é realçada.

    Ao especificar qual pool de agentes usar, você pode incluir qualquer uma dessas entradas na seção demands. Incluí-los garante que o Azure Pipelines escolha um agente de compilação que tenha o software necessário para criar seu 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.