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 de agente de compilação.
  • Crie um pool de agentes no Microsoft Azure DevOps.
  • Crie um token de acesso para autenticar o agente com o Azure DevOps.
  • Configure seu agente com o software necessário para criar o site do Space Game .
  • Configure o agente para ligar ao Azure DevOps, para que este possa receber tarefas de compilação.
  • Verifique se o agente está conectado ao Azure DevOps e pronto para receber trabalhos de compilação.

Existem várias formas 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 do Linux, pode estabelecer ligação diretamente por SSH e configurar o seu sistema de modo interativo.
  • Você pode automatizar a implantação usando um modelo ARM, Bíceps ou outra ferramenta de provisionamento automatizado.
  • Se precisar de implementar muitos agentes de compilação, pode criar uma imagem de VM que tenha todo o software pré-instalado.

Configurar um sistema de forma interativa é uma boa maneira de começar, porque o ajuda a compreender 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.

Nota

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

Criar uma máquina virtual do 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 aplicativo Web Space Game . Irá configurá-la 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. Aceda ao Portal do Azure e inicie sessão.

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

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

    Nota

    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. E.U.A. Leste, E.U.A. Oeste e Europa do Norte são alguns 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 az account list-locations comando:

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

  2. Name Na coluna 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 az group create comando:

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

Criar a VM

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

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 respetivo 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 tudo o que temos de criar. Um grupo de recursos permite-lhe administrar todas as VMs, discos, interfaces de rede e outros elementos que constituem a nossa solução como uma unidade.

Criar o conjunto de agentes

Lembre-se de que um conjunto de agentes organiza os agentes de compilação. Nesta seção, você criará o pool de agentes no Azure DevOps. Mais tarde, irá especificar o nome do conjunto de agentes ao configurar o seu agente para que este se possa registar a si próprio no conjunto correto.

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

  2. Selecione Configurações do projeto.

  3. Em Pipelines, selecione Agent pools (Conjuntos de agentes).

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

  4. Selecione Adicionar pool.

  5. Na janela Adicionar pool:

    1. Em Pool para vincular, selecione Novo.
    2. Em Tipo de piscina, selecione Auto-hospedado.
    3. Em Nome, digite 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 suas 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 Novo token.

  3. Introduza um nome para o seu token, tal como Agente de compilação.

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

  5. Procure Pools de agentes e, em seguida, selecione Ler & gerenciar.

  6. Selecione Criar.

  7. Copie o token para um local seguro.

    Em breve, irá utilizar o token para permitir que o agente de compilação autentique o acesso ao Azure Pipelines.

Ligar à 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 guarda o endereço IP numa variável Bash chamada IPADDRESS.

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

    echo $IPADDRESS

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

    ssh azureuser@$IPADDRESS

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

    Este comando funciona porque 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 na VM

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

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

  • SDK do .NET, que é usado para criar o aplicativo
  • Node.js, que é utilizado para executar tarefas de compilação
  • npm, o gestor de pacotes para Node.js
  • gulp, um pacote Node.js que é usado para minar 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.

Nota

O processo de compilação usa outras ferramentas, como node-sass, para converter arquivos Sass (.scss) em arquivos CSS (.css). No entanto, o Node.js instala estas 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 curl comando:

    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, você pode especificar a versão do .NET a DOTNET_VERSION 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

    A execução do script demora alguns minutos.

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

Instalar software de agente na VM

Agora chegou a altura de instalar o software de agente na VM. Este software permite que a VM atue como um agente de compilação e receba as tarefas de compilação do Azure Pipelines.

O processo de registo verifica a existência de software instalado antes de registar o agente com o Azure Pipelines. Portanto, é importante configurar o agente depois de instalar todos os outros softwares. Na prática, pode registar o agente uma segunda vez se precisar de 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 curl comando:

    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 de Bash Description Predefinido
    AZP_AGENT_VERSION A versão do software de agente a instalar A versão que utilizámos da última vez para testar este módulo
    AZP_URL A URL da sua organização do Azure DevOps (Nenhum)
    AZP_TOKEN O token de acesso pessoal (Nenhum)
    AZP_AGENT_NAME Nome do agente como aparece no Azure DevOps O nome do anfitrião do sistema
    AZP_POOL O nome do conjunto de agentes Predefinição
    AZP_WORK O diretório de trabalho para o agente executar as tarefas de compilação _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 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 agora, recomendamos que deixe as outras variáveis por definir.

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

    export AZP_AGENT_NAME=MyLinuxAgent

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

    Substitua <organização> pela sua. Você pode obter o nome na guia do navegador que exibe o Azure DevOps.

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

  5. Defina a AZP_TOKEN variável de ambiente 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 conjunto de agentes. Anteriormente, criou um conjunto com o nome OMeuConjuntoDeAgentes.

    export AZP_POOL=MyAgentPool

  7. Defina a AZP_AGENT_VERSION variável de ambiente 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 uma máquina Linux deve estar usando a versão mais recente do agente, mesmo que seja pré-lançamento. O software do agente é atualizado constantemente, portanto, as curl 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 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 execute como utilizador raiz. O -E argumento 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 Agent pools (Conjuntos de agentes).

  4. Selecione OMeuConjuntoDeAgentes.

  5. Selecione o separador Agents (Agentes).

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

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

    Gorjeta

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

  6. Selecione o agente OMeuAgenteLinux.

  7. Selecione o separador Capabilities (Funcionalidades).

    Durante a configuração, o processo de configuração analisou o agente de compilação para funcionalidades da ferramenta. Verá que npm está listado como uma delas. Lembre-se de que a configuração de compilação original especificou que npm tem de estar instalado no agente.

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

    Quando especificar o conjunto de agentes a utilizar, pode incluir qualquer uma destas entradas na secçã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.