Exercice : Créer un agent de build s’exécutant sur Azure

  • 20 minutes

Dans cette unité, pour configurer un agent de build que vous pouvez utiliser dans Microsoft Azure Pipelines, vous utiliserez une machine virtuelle qui s’exécute sur Microsoft Azure. Nous vous fournissons une machine virtuelle que vous allez pouvoir utiliser pendant toute la durée de ce module.

Dans cette unité, vous allez :

  • Créez une machine virtuelle Ubuntu sur Azure pour servir d’agent de build.
  • Créez un pool d’agents dans Microsoft Azure DevOps.
  • Créez un jeton d’accès pour authentifier votre agent auprès d’Azure DevOps.
  • Configurez votre agent avec le logiciel nécessaire pour générer le site web Space Game.
  • Configurez votre agent pour qu’il se connecte à Azure DevOps et qu’il puisse recevoir des tâches de build.
  • Vérifiez que l’agent est connecté à Azure DevOps et prêt à recevoir des tâches de build.

Il existe de nombreuses façons de créer une machine virtuelle sur Azure. Dans cette unité, vous créerez une machine virtuelle Ubuntu à l’aide d’un terminal interactif appelé Cloud Shell.

Pour configurer votre machine virtuelle, vous avez plusieurs choix :

  • Pour une machine virtuelle Linux, vous pouvez vous connecter directement via SSH et configurer votre système de manière interactive.
  • Vous pouvez automatiser le déploiement avec un modèle ARM, Bicep ou un autre outil de provisionnement automatique.
  • Si vous devez déployer de nombreux agents de build, vous pouvez créer une image de machine virtuelle sur laquelle tous les logiciels sont préinstallés.

La configuration interactive d’un système est un bon point de départ, car cela vous aide à comprendre le processus et les éléments nécessaires. Pour simplifier le processus, connectez-vous à votre machine virtuelle Ubuntu via SSH et exécutez des scripts d’interpréteur de commandes pour configurer votre agent de build.

Notes

Si vous ne savez pas comment vous connecter à des systèmes Linux ou comment les configurer, suivez simplement la procédure. Vous pouvez appliquer les mêmes concepts aux agents de build Windows.

Créer une machine virtuelle Linux

Dans cette section, vous créez une machine virtuelle qui exécute Ubuntu 20.04 et sert d’agent de build. La machine virtuelle n’est pas encore configurée en tant qu’agent de build et elle ne dispose pas des outils nécessaires pour générer l’application web Space Game. Vous allez vous en occuper d’ici peu.

Afficher Cloud Shell via le portail Azure

Important

Vous devez disposer de votre propre abonnement Azure pour effectuer les exercices de ce module.

  1. Accédez au portail Azure et connectez-vous.

  2. Dans le menu, sélectionnez Cloud Shell. Quand vous y êtes invité, sélectionnez l’expérience Bash.

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

    Remarque

    Pour conserver les fichiers que vous créez dans Cloud Shell, vous devez disposer d’une ressource de stockage Azure. Quand vous ouvrez Cloud Shell pour la première fois, vous êtes invité à créer un groupe de ressources, un compte de stockage et un partage Azure Files. Cette configuration est automatiquement utilisée pour toutes les futures sessions Cloud Shell.

Sélectionner une région Azure

Une région représente un ou plusieurs centres de données Azure dans une localisation géographique. USA Est, USA Ouest et Europe Nord sont des exemples de régions. Chaque ressource Azure, y compris les machines virtuelles, est affectée à une région.

Pour faciliter l’exécution des commandes, commencez par sélectionner une région par défaut. Une fois la région par défaut spécifiée, les commandes utilisent par la suite cette région tant que vous n’en spécifiez pas une autre.

  1. Dans Cloud Shell, exécutez la commande az account list-locations suivante pour lister les régions disponibles à partir de votre abonnement Azure :

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

  2. Dans la colonne Name de la sortie, choisissez une région proche de vous. Par exemple, choisissez eastasia ou westus2.

  3. Exécutez az configure pour définir votre région par défaut. Remplacez <REGION> par le nom de la région que vous avez choisie :

    az configure --defaults location=<REGION>

    Dans cet exemple, westus2 est défini comme région par défaut :

    az configure --defaults location=westus2

Créer un groupe de ressources

Créez un groupe de ressources pour contenir les ressources utilisées dans ce module de formation.

  • Exécutez la commande az group create suivante pour créer un groupe de ressources nommé tailspin-space-game-rg :

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

Création de la machine virtuelle

Exécutez la commande az vm create suivante pour créer votre machine virtuelle :

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

La création de la machine virtuelle prendra quelques minutes.

Standard_DS2_v2 indique la taille de la machine virtuelle. La taille d’une machine virtuelle permet de définir la vitesse de son processeur, la quantité de mémoire, la taille initiale de son espace de stockage et la bande passante réseau attendue. Il s’agit de la même taille que celle fournie par les agents hébergés par Microsoft. Dans la pratique, vous pouvez choisir une taille offrant davantage de puissance de calcul ou des fonctionnalités supplémentaires, par exemple le traitement des graphismes.

L’argument --resource-group spécifie le groupe de ressources qui contient tout ce que nous devons créer. Un groupe de ressources vous permet d’administrer l’ensemble des machines virtuelles, disques, interfaces réseau et autres éléments qui composent notre solution.

Créer le pool d’agents

Rappelez-vous qu’un pool d’agents organise les agents de build. Dans cette section, vous créerez le pool d’agents dans Azure DevOps. Plus tard, vous spécifierez le nom du pool d’agents durant la configuration de votre agent pour qu’il puisse s’inscrire auprès du pool approprié.

  1. Dans Azure DevOps, accédez au projet Space Game - web - Agent.

  2. Sélectionnez Paramètres du projet.

  3. Sous Pipelines, sélectionnez Pools d’agents.

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

  4. Sélectionnez Ajouter un pool.

  5. Dans la fenêtre Ajouter un pool :

    1. Sous Pool à lier, sélectionnez Nouveau.
    2. Sous Type de pool, sélectionnez Auto-hébergé.
    3. Sous Nom, entrez MyAgentPool.

    Dans la pratique, vous devez choisir un nom qui décrit précisément votre pool.

  6. Sélectionnez Créer. Le nouveau pool d’agents apparaît dans la liste.

Créer un jeton d’accès personnel

Pour que votre agent de build puisse s’inscrire auprès d’Azure DevOps, il doit disposer d’un moyen de s’authentifier.

Pour ce faire, vous pouvez créer un jeton d’accès personnel. Un jeton d’accès personnel (PAT) est une alternative au mot de passe. Vous pouvez utiliser le PAT pour vous authentifier auprès de services comme Azure DevOps.

Important

Comme vous le feriez avec un mot de passe, veillez à conserver votre jeton d’accès dans un endroit sûr. Dans cette section, vous stockerez votre jeton d’accès sous forme de variable d’environnement afin qu’il n’apparaisse pas dans votre script d’interpréteur de commandes.

  1. Dans Azure DevOps, ouvrez les paramètres de votre profil, puis sélectionnez Jetons d’accès personnels.

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

  2. Sélectionnez Nouveau jeton.

  3. Entrez le nom de votre jeton, par exemple Agent de build.

  4. Sous Étendues, sélectionnez le lien Afficher toutes les étendues en bas.

  5. Recherchez Pools d’agents, puis sélectionnez Lire et gérer.

  6. Sélectionnez Créer.

  7. Copiez le jeton dans un endroit sûr.

    D’ici peu, vous allez utiliser votre jeton pour permettre à votre agent de build d’authentifier l’accès à Azure Pipelines.

Connexion à votre machine virtuelle

Dans cette section, vous vous connecterez à votre machine virtuelle Linux via SSH pour pouvoir la configurer.

Rappelez-vous que vous ne pouvez pas vous connecter de manière interactive à un agent hébergé par Microsoft. Dans la mesure où un agent de build privé vous appartient, vous pouvez vous connecter et le configurer comme vous le souhaitez.

La connexion à votre agent de build vous permet de le configurer avec les outils dont vous avez besoin pour générer votre logiciel. Elle vous permet également de résoudre les problèmes de configuration de votre pipeline.

  1. Pour récupérer l’adresse IP de votre machine virtuelle, exécutez az vm show dans Cloud Shell :

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

    Cette commande stocke l’adresse IP dans une variable Bash nommée IPADDRESS.

  2. Affichez l’adresse IP de votre machine virtuelle sur la console :

    echo $IPADDRESS

  3. Créez une connexion SSH à votre machine virtuelle. À la place de $IPADDRESS, entrez l’adresse IP que vous avez reçue à l’étape précédente. À l’invite, entrez yes pour poursuivre la connexion.

    ssh azureuser@$IPADDRESS

    Vous êtes désormais connecté à votre machine virtuelle via SSH.

    Cette commande fonctionne, car vous avez fourni l’option --generate-ssh-keys quand vous avez exécuté az vm create. Cette option crée une paire de clés SSH, qui vous permet de vous connecter à la machine virtuelle.

Installer les outils de build sur votre machine virtuelle

Dans cette section, vous configurerez votre machine virtuelle avec les outils nécessaires pour créer le site web Space Game.

Rappelez-vous que votre processus de génération existant utilise les outils suivants :

  • SDK .NET, qui est utilisé pour générer l’application
  • Node.js, qui permet d’effectuer les tâches de build
  • npm, le gestionnaire de package pour Node.js
  • gulp, un package Node.js qui permet de minifier les fichiers JavaScript et CSS

Il s’agit des principaux outils nécessaires au processus de génération. Pour les installer, vous téléchargerez et exécuterez un script d’interpréteur de commandes à partir de GitHub.

Remarque

Le processus de génération utilise d’autres outils, par exemple node-sass pour convertir les fichiers Sass (.scss) en fichiers CSS (.css). Toutefois, Node.js installe ces outils durant l’exécution de la build.

Commençons par mettre à jour le gestionnaire de package Ubuntu, nommé apt. Cette action permet de récupérer les informations les plus récentes des dépôts de packages. Il s’agit généralement de la première chose que vous faites quand vous configurez un nouveau système Ubuntu.

  1. Dans votre connexion SSH, mettez à jour le cache du gestionnaire de package apt :

    sudo apt-get update

    sudo exécute la commande avec des privilèges Administrateur ou racine.

  2. Pour télécharger un script d’interpréteur de commandes appelé build-tools.sh à partir de GitHub, exécutez la commande curl suivante :

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

  3. Affichez le script sur le terminal pour pouvoir en examiner le contenu :

    cat build-tools.sh

    Le résultat suivant s’affiche :

    #!/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

    Le script installe Node.js, npm, gulp et .NET Core.

    La définition de la variable d’environnement DOTNET_VERSION vous permet de spécifier la version de .NET à installer. Si vous ne définissez pas cette variable, le script installe la version utilisée par votre configuration de build. À des fins pédagogiques, vous ne définissez pas cette variable. Vous autorisez le script à utiliser la version par défaut.

  4. Rendez le script exécutable, puis exécutez-le :

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

    L’exécution du script prend quelques minutes.

    Dans la pratique, vous pouvez maintenant exécuter des commandes pour vérifier que chaque composant logiciel a été installé correctement.

Installer le logiciel agent sur votre machine virtuelle

Il est temps à présent d’installer le logiciel agent sur votre machine virtuelle. Ce logiciel permet à la machine virtuelle d’agir en tant qu’agent de build et de recevoir les tâches de build en provenance d’Azure Pipelines.

Le processus d’inscription recherche les logiciels installés avant d’inscrire l’agent auprès d’Azure Pipelines. Il est donc important de configurer l’agent après avoir installé tous les autres logiciels. Dans la pratique, vous pouvez inscrire l’agent une deuxième fois, si vous devez installer un logiciel supplémentaire.

La documentation explique comment configurer manuellement les agents Linux autohébergés ainsi que des agents macOS et Windows. Vous exécutez un script d’interpréteur de commandes pour configurer votre agent, de la même façon que vous avez configuré les outils de génération dans la section précédente.

Important

Le script que vous allez exécuter ici est utilisé à des fins pédagogiques. Dans la pratique, vous devez d’abord comprendre comment chaque commande des scripts que vous générez impacte l’ensemble du système. À la fin du module, nous allons vous orienter vers la documentation qui décrit plus en détail vos options.

  1. Pour télécharger un script d’interpréteur de commandes nommé build-agent.sh à partir de GitHub, exécutez la commande curl suivante :

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

  2. Affichez le script sur le terminal pour pouvoir en examiner le contenu :

    cat build-agent.sh

    Le résultat suivant s’affiche :

    #!/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

    Vous n’avez pas besoin de comprendre le fonctionnement de chaque ligne, mais voici un bref récapitulatif de ce que fait ce script :

    • Il télécharge le package d’agent sous forme de fichier .tar.gz, puis extrait son contenu.
    • Dans les fichiers extraits, le script :
      • Exécute un script d’interpréteur de commandes nommé installdependencies.sh pour installer le logiciel agent.
      • Exécute un script d’interpréteur de commandes nommé config.sh pour configurer l’agent et l’inscrire auprès d’Azure Pipelines.
      • Exécute un script d’interpréteur de commandes nommé svc.sh pour installer et démarrer le service de l’agent.

    Le script utilise des variables d’environnement pour vous permettre de fournir des détails sur votre organisation Azure DevOps. Voici un résumé :

    Variable Bash Description Default
    AZP_AGENT_VERSION Version du logiciel agent à installer Dernière version que nous avons utilisée pour tester ce module
    AZP_URL URL de votre organisation Azure DevOps (aucune)
    AZP_TOKEN Votre jeton d’accès personnel (aucune)
    AZP_AGENT_NAME Nom de votre agent tel qu’il apparaît dans Azure DevOps Nom d’hôte du système
    AZP_POOL Nom de votre pool d’agents Par défaut
    AZP_WORK Répertoire de travail de l’agent pour effectuer les tâches de build _work

    Si le script ne fournit pas de valeur par défaut pour une variable qui n’est pas définie, il affiche un message d’erreur et se ferme immédiatement.

    Au cours des étapes qui suivent, définissez ces variables d’environnement :

    • AZP_AGENT_VERSION
    • AZP_URL
    • AZP_TOKEN
    • AZP_AGENT_NAME
    • AZP_POOL

    Pour le moment, nous vous recommandons de laisser les autres variables non définies.

  3. Définissez la variable d’environnement AZP_AGENT_NAME pour spécifier le nom de votre agent. Nous vous recommandons MyLinuxAgent.

    export AZP_AGENT_NAME=MyLinuxAgent

  4. Définissez la variable d’environnement AZP_URL pour spécifier l’URL de votre organisation Azure DevOps.

    Remplacez <organization> par votre organisation. Vous pouvez récupérer le nom à partir de l’onglet de navigateur qui présente Azure DevOps.

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

  5. Définissez la variable d’environnement AZP_TOKEN pour spécifier votre jeton d’accès personnel (valeur de jeton longue que vous avez copiée précédemment dans cette unité).

    Remplacez <token> par votre jeton.

    export AZP_TOKEN=token

  6. Définissez la variable d’environnement AZP_POOL pour spécifier le nom de votre pool d’agents. Vous avez créé un pool nommé MyAgentPool.

    export AZP_POOL=MyAgentPool

  7. Définissez la variable d’environnement AZP_AGENT_VERSION pour spécifier la version la plus récente de l’agent.

    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)

    Un pipeline YAML sur une machine Linux doit utiliser la version la plus récente de l’agent, même s’il s’agit d’une préversion. Le logiciel agent est constamment mis à jour, donc vous exécutez une commande curl sur les informations de version issues du dépôt GitHub. La commande utilise jq pour lire la version la plus récente dans la chaîne JSON retournée.

  8. Imprimez la version de l’agent dans la console. Éventuellement, vérifiez qu’il s’agit bien de la version la plus récente.

    echo $AZP_AGENT_VERSION

  9. Rendez le script exécutable, puis exécutez-le :

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

    sudo permet au script de s’exécuter en tant qu’utilisateur racine. L’argument -E permet de conserver les variables d’environnement actuelles, notamment celles que vous avez définies, afin qu’elles soient disponibles pour le script.

    Pendant l’exécution du script, l’agent se connecte à Azure DevOps, il est ajouté au pool d’agents et la connexion de l’agent est testée.

Vérifier que l’agent est en cours d’exécution

Vous avez correctement installé les outils de build et le logiciel agent sur votre machine virtuelle. En guise de vérification, accédez à Azure DevOps pour voir si votre agent se trouve dans le pool d’agents.

  1. Dans Azure DevOps, accédez au projet Space Game - web - Agent.

  2. Sélectionnez Paramètres du projet.

  3. Sous Pipelines, sélectionnez Pools d’agents.

  4. Sélectionnez MyAgentPool.

  5. Sélectionnez l’onglet Agents.

    Vous constatez que votre agent est en ligne et qu’il est prêt à accepter des tâches de build.

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

    Conseil

    Si votre agent de build indique Hors connexion, attendez quelques instants, puis actualisez la page.

  6. Sélectionnez votre agent, MyLinuxAgent.

  7. Sélectionnez l’onglet Fonctionnalités.

    Durant l’installation, le processus de configuration a analysé les fonctionnalités d’outil de votre agent de build. Vous pouvez voir que npm est listé parmi les fonctionnalités. Rappelez-vous que votre configuration de build d’origine spécifiait que npm devait être installé sur l’agent.

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

    Quand vous spécifiez le pool d’agents à utiliser, vous pouvez inclure l’une de ces entrées dans votre section demands. Leur inclusion garantit qu’Azure Pipelines choisit un agent de build doté du logiciel nécessaire à la génération de votre application. Cela vous permet aussi de créer des pools d’agents avec diverses configurations logicielles. Azure Pipelines sélectionnera la configuration appropriée en fonction de vos besoins.