Agents Linux autohébergés (2.x)

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019

Important

Cet article fournit une aide sur l’utilisation du logiciel agent version 2.x avec Azure DevOps Server et TFS. Si vous utilisez Azure DevOps Services, consultez Agents Linux autohébergés.

Attention

Cet article fait référence à CentOS, une distribution Linux proche de l’état EOL (End Of Life). Faites le point sur votre utilisation afin de vous organiser en conséquence. Pour plus d’informations, consultez les conseils d’aide relatifs à la fin de vie de CentOS.

Pour exécuter vos travaux, vous aurez besoin d’au moins un agent. Un agent Linux peut générer et déployer différents types d’applications, notamment les applications Java et Android. Nous prenons en charge Ubuntu, Red Hat et CentOS.

Avant de commencer :

• Si vos pipelines se trouvent dans Azure Pipelines et qu’un agent hébergé par Microsoft répond à vos besoins, vous pouvez ignorer la configuration d’un agent Linux privé.
• Sinon, vous êtes au bon endroit pour configurer un agent sur Linux. Passez à la section suivante.

Découvrir les agents

Si vous savez déjà ce qu’est un agent et comment il fonctionne, n’hésitez pas à passer directement aux sections suivantes. Toutefois, si vous souhaitez en savoir plus sur ce qu’ils font et sur leur fonctionnement, consultez Agents Azure Pipelines.

Vérifier les conditions préalables

L’agent est basé sur .NET Core 3.1. Vous pouvez exécuter cet agent sur plusieurs distributions Linux. Nous prenons en charge le sous-ensemble suivant de distributions prises en charge par .NET Core :

• X64
  • CentOS 7, 6 (voir note 1)
  • Debian 9
  • Fedora 30, 29
  • Linux Mint 18, 17
  • openSUSE 42.3 ou version ultérieure
  • Oracle Linux 8, 7
  • Serveur Red Hat Enterprise Linux 8, 7, 6 (voir note 1)
  • SUSE Enterprise Linux 12 SP2 ou version ultérieure
  • Ubuntu 20.04, 18.04, 16.04
  • Azure Linux 1.0 (consultez la note 3)
• ARM32 (consultez la note 2)
  • Debian 9
  • Ubuntu 18.04
• ARM64
  • Debian 9
  • Ubuntu 21.04, 20.04, 18.04

Notes

Note 1 : RHEL 6 et CentOS 6 nécessitent l’installation de la version rhel.6-x64 spécialisée de l’agent.

Important

À compter de février 2023, plus aucune version d’agent ne prend en charge RHEL 6. Pour plus d’informations, consultez Customers using Red Hat Enterprise Linux (RHEL) 6 should upgrade the OS on Self-hosted agents (Les clients qui utilisent RHEL (Red Hat Enterprise Linux) 6 doivent mettre à niveau le système d’exploitation sur les agents autohébergés).

Notes

Note 2 : L’ensemble d’instructions ARM ARMv7 ou version ultérieure est requis. Exécutez uname -a pour afficher l’ensemble d’instructions de votre distribution Linux.

Notes

Actuellement, l’agent Azure DevOps prend partiellement en charge la distribution de système d’exploitation Azure Linux. Nous fournissons un mécanisme pour la détection de cette distribution de système d’exploitation dans le script installdependencies.sh, mais en raison du manque de prise en charge côté .Net Core, nous n’avons pas pu garantir l’opérabilité totale de toutes les fonctions de l’agent quand il est exécuté sur cette distribution de système d’exploitation.

Quelle que soit votre plateforme, vous devez installer Git 2.9.0 ou une version ultérieure. Nous vous recommandons vivement d’installer la dernière version de Git.

Notes

Le programme d’installation de l’agent sait comment rechercher d’autres dépendances. Vous pouvez installer ces dépendances sur les plateformes Linux prises en charge en exécutant ./bin/installdependencies.sh dans le répertoire de l’agent.

Sachez que certaines de ces dépendances requises par .NET Core sont extraites de sites tiers, comme packages.efficios.com. Passez en revue le script installdependencies.sh et vérifiez que tous les sites tiers référencés sont accessibles à partir de votre ordinateur Linux avant d’exécuter le script.

Vérifiez également que tous les référentiels requis sont connectés au gestionnaire de package approprié utilisé dans installdependencies.sh (par exemple, apt ou zypper).

Pour les problèmes liés à l’installation des dépendances (comme « dépendance introuvable dans le référentiel » ou « problème de récupération du fichier d’index du référentiel »), vous pouvez contacter le propriétaire de distribution pour obtenir une prise en charge supplémentaire.

Subversion

Si vous générez à partir d’un référentiel Subversion, vous devez installer le client Subversion sur l’ordinateur.

La première fois, vous devez exécuter la configuration de l’agent manuellement. Une fois que vous avez une idée du fonctionnement des agents ou si vous souhaitez automatiser la configuration de nombreux agents, envisagez d’utiliser la configuration sans assistance.

TFVC

Si vous utilisez TFVC, vous avez également besoin du Oracle Java JDK 1.6 ou version ultérieure. (Oracle JRE et OpenJDK ne sont pas suffisants à cet effet.)

Le plug-in TEE est utilisé pour les fonctionnalités TFVC. Il dispose d’un CLUF, que vous devez accepter pendant la configuration si vous envisagez d’utiliser TFVC.

Étant donné que le plug-in TEE n’est plus tenu à jour et contient certaines dépendances Java obsolètes, à partir de l’Agent 2.198.0, il n’est plus inclus dans la distribution de l’agent. Toutefois, le plug-in TEE est téléchargé pendant l’exécution de la tâche d’extraction si vous extrayez un référentiel TFVC. Le plug-in TEE est supprimé après l’exécution du travail.

Remarque

Remarque : vous remarquerez peut-être que votre tâche d’extraction prend beaucoup de temps pour commencer à fonctionner en raison de ce mécanisme de téléchargement.

Si l’agent s’exécute derrière un proxy ou un pare-feu, vous devez garantir l’accès au site suivant : https://vstsagenttools.blob.core.windows.net/ Le plug-in TEE sera téléchargé à partir de cette adresse.

Si vous utilisez un agent autohébergé et que vous rencontrez des problèmes avec le téléchargement de TEE, vous pouvez installer TEE manuellement :

1. Définissez DISABLE_TEE_PLUGIN_REMOVALl’environnement ou la variable de pipeline sur true. Cette variable empêche l’agent de supprimer le plug-in TEE après l’extraction du référentiel TFVC.
2. Téléchargez manuellement TEE-CLC version 14.135.0 à partir des versions de GitHub Team Explorer Everywhere.
3. Extrayez le contenu du dossier TEE-CLC-14.135.0 vers <agent_directory>/externals/tee.

Préparer les autorisations

Sécurité des informations pour les agents autohébergés

L’utilisateur qui configure l’agent a besoin d’autorisations d’administrateur de pool, mais pas l’utilisateur qui exécute l’agent.

Les dossiers contrôlés par l’agent doivent être limités à un minimum d’utilisateurs et contiennent des secrets qui peuvent être déchiffrés ou exfiltrés.

L’agent Azure Pipelines est un produit logiciel conçu pour exécuter le code qu’il télécharge à partir de sources externes. Par nature, il peut être la cible d’attaques par exécution de code à distance.

Il est donc important de prendre en compte le modèle de menace spécifique à chaque utilisation d’agents Pipelines pour effectuer le travail. Il est également essentiel de décider des autorisations minimales qui peuvent être accordées à l’utilisateur exécutant l’agent, à la machine sur laquelle l’agent s’exécute, aux utilisateurs qui ont accès en écriture à la définition de pipeline, aux dépôts Git dans lesquels le code YAML est stocké ou au groupe d’utilisateurs contrôlant l’accès au pool pour les nouveaux pipelines.

L’identité qui exécute l’agent doit, dans la mesure du possible, être différente de l’identité possédant des autorisations pour connecter l’agent au pool. L’utilisateur qui génère les informations d’identification (et d’autres fichiers liés à l’agent) est différent de celui qui doit les lire. Par sécurité, il convient donc de réfléchir scrupuleusement à l’accès accordé à l’ordinateur agent lui-même et aux dossiers d’agent contenant des fichiers sensibles tels que des journaux et des artefacts.

Il est judicieux d’accorder l’accès au dossier de l’agent uniquement aux administrateurs DevOps et à l’identité utilisateur exécutant le processus de l’agent. Les administrateurs peuvent avoir besoin d’investiguer le système de fichiers pour comprendre les échecs de build ou obtenir des fichiers journaux afin de signaler les échecs Azure DevOps.

Déterminer l’utilisateur à utiliser

Vous devez inscrire l’agent (une seule fois). Ces étapes doivent être effectuées par une personne disposant de l’autorisation d’administration de la file d’attente d’agents. L’agent n’utilisera pas les informations d’identification de cette personne pour les opérations quotidiennes, mais ces informations sont nécessaires pour effectuer l’inscription. Apprenez-en davantage sur le mode de communication des agents.

S’authentifier avec un jeton d’accès personnel

1. Connectez-vous avec le compte d’utilisateur que vous envisagez d’utiliser dans votre organisation Azure DevOps (https://dev.azure.com/{your_organization}).

2. À partir de votre page d’hébergement, ouvrez vos paramètres utilisateur, puis sélectionnez Jetons d’accès personnels.

   

3. Créez un jeton d’accès personnel.

   

4. Pour l’étendue, sélectionnez Pools d’agents (lire, gérer) et vérifiez que toutes les autres cases sont désactivées. S’il s’agit d’un agent de groupe de déploiement, pour l’étendue, sélectionnez Groupe de déploiement (lire, gérer) et vérifiez que toutes les autres cases sont désactivées.

   Sélectionnez Afficher toutes les étendues en bas de la fenêtre Créer un jeton d’accès personnel pour voir la liste complète des étendues.

5. Copiez le jeton. Vous utiliserez ce jeton quand vous configurerez l’agent.

Vérifier que l’utilisateur dispose d’une autorisation

Vérifiez que le compte d’utilisateur que vous allez utiliser est autorisé à inscrire l’agent.

Si l’utilisateur est propriétaire d’organisation Azure DevOps ou administrateur TFS ou Azure DevOps Server, arrêtez-vous ici. Vous avez l’autorisation.

Sinon :

1. Ouvrez un navigateur et accédez à l’onglet Pools d’agents pour votre organisation Azure Pipelines ou votre serveur Azure DevOps Server ou TFS :

   1. Connectez-vous à votre organisation (https://dev.azure.com/{yourorganization}).

   2. Choisissez Azure DevOps, Paramètres de l’organisation.

      

   3. Choisissez Pools d’agents.

      

2. Sélectionnez le pool à droite de la page, puis cliquez sur Sécurité.

3. Si le compte d’utilisateur que vous envisagez d’utiliser n’est pas affiché, demandez à un administrateur de l’ajouter. L’administrateur peut être un administrateur de pool d’agents, un propriétaire d’organisation Azure DevOps ou un administrateur TFS ou Azure DevOps Server.

   S’il s’agit d’un agent de groupe de déploiement, l’administrateur peut être un administrateur de groupe de déploiement, un propriétaire d’organisation Azure DevOps ou un administrateur TFS ou Azure DevOps Server.

   Vous pouvez ajouter un utilisateur au rôle d’administrateur de groupe de déploiement dans l’onglet Sécurité de la page Groupes de déploiement dans Azure Pipelines.

Notes

Si vous voyez un message du type Nous n’avons pas pu ajouter l’identité. Essayez une autre identité., vous avez probablement suivi les étapes plus haut pour un propriétaire d’organisation ou un administrateur TFS ou Azure DevOps Server. Vous n’avez rien à faire : vous disposez déjà de l’autorisation d’administrer la file d’attente d’agents.

Télécharger et configurer l’agent

Azure Pipelines

1. Connectez-vous à la machine avec le compte pour lequel vous avez préparé les autorisations, comme expliqué plus haut.

2. Dans votre navigateur web, connectez-vous à Azure Pipelines et accédez à l’onglet Pools d’agents :

   1. Connectez-vous à votre organisation (https://dev.azure.com/{yourorganization}).

   2. Choisissez Azure DevOps, Paramètres de l’organisation.

      

   3. Choisissez Pools d’agents.

      

3. Sélectionnez le pool Par défaut, sélectionnez l’onglet Agents, puis choisissez Nouvel agent.

4. Dans la boîte de dialogue Obtenir l’agent, cliquez sur Linux.

5. Dans le volet gauche, sélectionnez la saveur spécifique. Nous proposons x64 ou ARM pour la plupart des distributions Linux.

6. Dans le volet de droite, cliquez sur le bouton Télécharger.

7. Suivez les instructions sur la page.
   

8. Décompressez l’agent dans le répertoire de votre choix. cd vers ce répertoire et exécutez ./config.sh.

URL du serveur

Azure Pipelines : https://dev.azure.com/{your-organization}

Type d'authentification

Azure Pipelines

Choisissez PAT, puis collez le jeton PAT que vous avez créé dans la fenêtre d’invite de commandes.

Notes

Lorsque vous utilisez PAT comme méthode d’authentification, le jeton PAT est utilisé uniquement pour la configuration initiale de l’agent. En savoir plus sur Communication avec Azure Pipelines ou TFS.

TFS ou Azure DevOps Server

Important

Vérifiez que votre serveur est configuré pour prendre en charge la méthode d’authentification que vous souhaitez utiliser.

Lorsque vous configurez votre agent pour vous connecter à TFS, vous disposez des options suivantes :

• Alterner Connectez-vous à TFS ou Azure DevOps Server à l’aide de l’authentification de base. Une fois que vous avez sélectionné Alterner, vous êtes invité à entrer vos informations d’identification.

• Intégré Non pris en charge sur macOS ou Linux.

• Négocier (par défaut) Se connecter à TFS ou Azure DevOps Server en tant qu’utilisateur autre que l’utilisateur connecté via un schéma d’authentification Windows tel que NTLM ou Kerberos. Une fois que vous avez sélectionné Négocier, vous êtes invité à entrer vos informations d’identification.

• PAT Pris en charge uniquement sur Azure Pipelines et TFS 2017 et versions ultérieures. Après avoir choisi PAT, collez le jeton PAT que vous avez créé dans la fenêtre d’invite de commandes. Utilisez un jeton d’accès personnel (PAT) si votre instance Azure DevOps Server ou TFS et l’ordinateur de l’agent ne se trouvent pas dans un domaine approuvé. L’authentification PAT est gérée par votre instance Azure DevOps Server ou TFS au lieu du contrôleur de domaine.

Notes

Lorsque vous utilisez PAT comme méthode d’authentification, le jeton PAT est utilisé uniquement pour la configuration initiale de l’agent sur Azure DevOps Server et les versions plus récentes de TFS. En savoir plus sur Communication avec Azure Pipelines ou TFS.

Effectuer l'exécution de manière interactive

Pour obtenir de l’aide sur l’exécution de l’agent en mode interactif ou en tant que service, consultez Agents : Interactif contre service.

Pour exécuter l’agent de manière interactive :

1. Si vous avez exécuté l’agent en tant que service, désinstallez le service.

2. Exécutez l'agent.

   ./run.sh
   

Pour redémarrer l’agent, appuyez sur Ctrl+C, puis exécutez run.sh pour le redémarrer.

Pour utiliser votre agent, exécutez un travail à l’aide du pool de l’agent. Si vous n’avez pas choisi un autre pool, votre agent se trouve dans le pool Par défaut.

Exécuter une fois

Pour que les agents configurés s’exécutent de manière interactive, vous pouvez choisir qu’ils n’acceptent qu’un seul travail. Pour une exécution dans cette configuration :

./run.sh --once

Les agents dans ce mode n’acceptent qu’un seul travail, puis effectuent une rotation automatique (utile pour s’exécuter dans Docker sur un service comme Azure Container Instances).

Exécuter en tant que service systemd

Si votre agent s’exécute sur ces systèmes d’exploitation, vous pouvez exécuter l’agent en tant que service systemd :

• Ubuntu 16 LTS ou version ultérieure
• Red Hat 7.1 ou version ultérieure

Nous fournissons un exemple de script ./svc.sh pour vous permettre d’exécuter et de gérer votre agent en tant que service systemd. Ce script sera généré après la configuration de l’agent. Nous vous encourageons à évaluer et, si nécessaire, à mettre à jour le script avant de l’exécuter.

Quelques mises en garde importantes :

• Si vous exécutez votre agent en tant que service, vous ne pouvez pas exécuter le service de l’agent en tant qu’utilisateur root.
• Les utilisateurs exécutant SELinux ont signalé des difficultés avec le script svc.sh fourni. Reportez-vous à ce problème d’agent comme point de départ. SELinux n’est pas une configuration officiellement prise en charge.

Notes

Si vous avez une distribution différente ou si vous préférez d’autres approches, vous pouvez utiliser le type de mécanisme de service que vous préférez. Consultez Fichiers de service.

Commandes

Passer au répertoire de l’agent

Par exemple, si vous l’avez installé dans le sous-dossier myagent de votre répertoire de base :

cd ~/myagent$

Installer

Commande :

sudo ./svc.sh install [username]

Cette commande crée un fichier de service qui pointe vers ./runsvc.sh. Ce script configure l’environnement (plus de détails ci-dessous) et démarre l’hôte de l’agent. Si le paramètre username n’est pas spécifié, le nom d’utilisateur est extrait de la variable d’environnement $SUDO_USER définie par la commande sudo. Cette variable est toujours égale au nom de l’utilisateur qui a appelé la commande sudo.

Démarrer

sudo ./svc.sh start

Statut

sudo ./svc.sh status

Arrêter

sudo ./svc.sh stop

Désinstaller l’interface

Vous devez arrêter avant de désinstaller.

sudo ./svc.sh uninstall

Mettre à jour les variables d’environnement

Lorsque vous configurez le service, il prend un instantané de certaines variables d’environnement utiles pour votre utilisateur d’ouverture de session actuel, tel que PATH, LANG, JAVA_HOME, ANT_HOME et MYSQL_PATH. Si vous devez mettre à jour les variables (par exemple, après avoir installé un nouveau logiciel) :

./env.sh
sudo ./svc.sh stop
sudo ./svc.sh start

L’instantané des variables d’environnement est stocké dans le fichier .env (PATH est stocké dans .path) sous le répertoire racine de l’agent. Vous pouvez également modifier ces fichiers directement pour appliquer des modifications de variables d’environnement.

Exécuter des instructions avant le démarrage du service

Vous pouvez également exécuter vos propres instructions et commandes pour qu’elles s’exécutent au démarrage du service. Par exemple, vous pouvez configurer l’environnement ou appeler des scripts.

1. Modifier runsvc.sh.

2. Remplacez la ligne suivante par vos instructions :

   # insert anything to setup env when running as a service
   

Fichiers de service

Lorsque vous installez le service, certains fichiers de service sont mis en place.

Fichier de service systemd

Un fichier de service systemd est créé :

/etc/systemd/system/vsts.agent.{tfs-name}.{agent-name}.service

Par exemple, vous avez configuré un agent (voir ci-dessus) avec le nom our-linux-agent. Le fichier de service sera soit :

• Azure Pipelines : nom de votre organisation. Par exemple, si vous vous connectez à https://dev.azure.com/fabrikam, le nom du service serait /etc/systemd/system/vsts.agent.fabrikam.our-linux-agent.service

• TFS ou Azure DevOps Server : nom de votre serveur local. Par exemple, si vous vous connectez à http://our-server:8080/tfs, le nom du service serait /etc/systemd/system/vsts.agent.our-server.our-linux-agent.service

sudo ./svc.sh install génère ce fichier à partir de ce modèle : ./bin/vsts.agent.service.template

Fichier .service

sudo ./svc.sh start recherche le service en lisant le fichier .service, qui contient le nom du fichier de service systemd décrit ci-dessus.

Autres mécanismes de service

Nous fournissons le script ./svc.sh comme moyen pratique d’exécuter et de gérer votre agent en tant que service systemd. Mais vous pouvez utiliser le type de mécanisme de service que vous préférez (par exemple : initd ou upstart).

Vous pouvez utiliser le modèle décrit ci-dessus pour faciliter la génération d’autres types de fichiers de service.

Utiliser un cgroup pour éviter l’échec de l’agent

Il est important d’éviter les situations dans lesquelles l’agent échoue ou devient inutilisable, car sinon l’agent ne peut pas diffuser en continu les journaux de pipeline ou renvoyer l’état du pipeline au serveur. Vous pouvez atténuer le risque que ce type de problème soit causé par une forte sollicitation de la mémoire à l’aide de cgroups et d’un oom_score_adj plus faible. Une fois cette opération effectuée, Linux récupère la mémoire système des processus de travail de pipeline avant de récupérer la mémoire du processus de l’agent. Découvrez comment configurer les cgroup et le score OOM.

Remplacer un agent

Pour remplacer un agent, suivez à nouveau les étapes décrites dans la section Télécharger et configurer l’agent.

Quand vous configurez un agent avec le même nom qu’un agent existant, vous êtes invité à remplacer l’agent existant. Si vous répondez Y, veillez à supprimer l’agent (voir ci-dessous) que vous remplacez. Sinon, après quelques minutes de conflits, l’un des agents s’arrêtera.

Supprimer et reconfigurer un agent

Pour supprimer l’agent :

1. Arrêtez et désinstallez le service comme expliqué ci-dessus.

2. Supprimez l’agent.

   ./config.sh remove
   

3. Entrez vos informations d’identification.

Une fois que vous avez supprimé l’agent, vous pouvez le configurer à nouveau.

Configuration sans assistance

L’agent peut être configuré à partir d’un script sans intervention humaine. Vous devez transférer --unattended et les réponses à toutes les questions.

Pour configurer un agent, il doit connaître l’URL de votre organisation ou collection et les informations d’identification d’une personne autorisée à configurer des agents. Toutes les autres réponses sont facultatives. Tout paramètre de ligne de commande peut être spécifié avec une variable d’environnement à la place : spécifiez son nom en majuscules et faites-le précéder de VSTS_AGENT_INPUT_. Par exemple, VSTS_AGENT_INPUT_PASSWORD au lieu de spécifier --password.

Options obligatoires

• --unattended : La configuration de l’agent ne demande pas d’informations et tous les paramètres doivent être spécifiés sur la ligne de commande
• --url <url> : URL du serveur. Par exemple : https://dev.azure.com/myorganization ou http://my-azure-devops-server:8080/tfs
• --auth <type> : Type d’authentification. Les valeurs valides sont les suivantes :
  • pat (Jeton d’accès personnel) : Le schéma PAT est le seul qui fonctionne avec Azure DevOps Services.
  • negotiate (Kerberos ou NTLM)
  • alt (Authentification de base)
  • integrated (Informations d’identification Windows par défaut)

Options d’authentification

• Si vous avez choisi --auth pat :
  • --token <token> : Spécifie votre jeton d’accès personnel
  • Le schéma PAT est le seul qui fonctionne avec Azure DevOps Services.
• Si vous avez choisi --auth negotiate ou --auth alt :
  • --userName <userName> : Spécifie un nom d’utilisateur Windows au format domain\userName ou userName@domain.com
  • --password <password> : Spécifie un mot de passe

Noms de pool et d’agent

• --pool <pool> : Nom du pool que l’agent doit joindre
• --agent <agent> : Nom de l’agent
• --replace : Remplacer l’agent dans un pool. Si un autre agent écoute sous le même nom, il commence à échouer avec un conflit

Configuration de l’agent

• --work <workDirectory> : Répertoire de travail dans lequel les données de travail sont stockées. Le répertoire par défaut est _work à la racine du répertoire de l’agent. Le répertoire de travail appartient à un agent donné et ne doit pas être partagé entre plusieurs agents.
• --acceptTeeEula : Accepter le Contrat de licence d’utilisateur final Team Explorer Everywhere (macOS et Linux uniquement)
• --disableloguploads : Ne pas envoyer (en streaming ou non) la sortie de journal de la console au serveur. Vous pouvez, dans ce cas, la récupérer à partir du système de fichiers de l’hôte de l’agent quand le travail est terminé.

Démarrage Windows uniquement

• --runAsService : Configure l’agent pour qu’il s’exécute comme service Windows (nécessite une autorisation d’administrateur)
• --runAsAutoLogon : Configure l’ouverture de session automatique et exécute l’agent au démarrage (nécessite une autorisation d’administrateur)
• --windowsLogonAccount <account> : Utilisé avec --runAsService ou --runAsAutoLogon pour spécifier le nom d’utilisateur Windows au format domain\userName ou userName@domain.com
• --windowsLogonPassword <password> : Utilisé avec --runAsService ou --runAsAutoLogon pour spécifier le mot de passe d’ouverture de session Windows (non requis pour les comptes de service géré de groupe et les comptes Windows intégrés tels que 'NT AUTHORITY\NETWORK SERVICE')
• --overwriteAutoLogon : Utilisé avec --runAsAutoLogon pour remplacer l’ouverture de session automatique existante sur la machine
• --noRestart : Utilisé avec --runAsAutoLogon pour empêcher l’hôte de redémarrer à la fin de la configuration de l’agent

Résolution des problèmes de configuration de l’agent avec l’option runAsAutoLogon

La configuration de l’agent avec l’option runAsAutoLogon exécute l’agent après chaque redémarrage de la machine. Effectuez les étapes suivantes si l’agent n’est pas exécuté après le redémarrage de la machine.

Si l’agent était déjà configuré sur la machine

Avant de reconfigurer l’agent, il est nécessaire de supprimer l’ancienne configuration de l’agent. Pour cela, essayez d’exécuter cette commande dans le dossier de l’agent :

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

Vérifiez si l’agent a été supprimé de votre pool d’agents après l’exécution de la commande :

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

Supprimez manuellement l’agent de votre pool d’agents s’il n’a pas été supprimé par l’exécution de la commande.

Essayez ensuite de reconfigurer l’agent en exécutant cette commande dans le dossier de l’agent :

.\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>'

Spécifiez le nom de l’agent (n’importe quel nom unique spécifique) et vérifiez si cet agent apparaît dans votre pool d’agents après la reconfiguration.

Il est largement préférable de décompresser une archive d’agent (qui peut être téléchargée ici) et d’exécuter cette commande dans le dossier du nouvel agent décompressé.

Vérifier si la clé de Registre Windows est enregistrée et sauvegardée correctement

Exécutez la commande whoami /user pour obtenir le <sid>. Ouvrez Registry Editor et suivez le chemin :

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

Vérifiez la présence de la clé VSTSAgent. Supprimez cette clé si elle existe, puis fermez Registry Editor et configurez l’agent en exécutant la commande .\config.cmd (sans arguments) dans le dossier de l’agent. Avant de répondre à la question Enter Restart the machine at a later time?, ouvrez de nouveau Registry Editor et vérifiez si la clé VSTSAgent est apparue. Appuyez sur Enter pour répondre à la question et vérifiez si la clé VSTSAgent reste à sa place après le redémarrage de la machine.

Vérifier si les clés de Registre Windows fonctionnent correctement sur votre machine

Créez un fichier autorun.cmd contenant la ligne suivante : echo "Hello from AutoRun!". Ouvrez Registry Editor et créez, dans le chemin plus haut, une nouvelle paire clé-valeur avec la clé AutoRun et la valeur

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

Redémarrez votre machine. Si vous ne voyez pas de fenêtre de console avec le message Hello from AutoRun!, cela indique un problème avec les clés de Registre Windows.

Groupe de déploiement uniquement

• --deploymentGroup : Configure l’agent comme agent de groupe de déploiement
• --deploymentGroupName <name> : Utilisé avec --deploymentGroup pour spécifier le groupe de déploiement que l’agent doit joindre
• --projectName <name> : Utilisé avec --deploymentGroup pour définir le nom du projet
• --addDeploymentGroupTags : Utilisé avec --deploymentGroup pour indiquer que des étiquettes de groupe de déploiement doivent être ajoutées
• --deploymentGroupTags <tags> : Utilisé avec --addDeploymentGroupTags pour spécifier la liste d’étiquettes séparées par des virgules pour l’agent de groupe de déploiement, par exemple « web, db »

Environnements uniquement

• --addvirtualmachineresourcetags : Utilisé pour indiquer que des étiquettes de ressource d’environnement doivent être ajoutées
• --virtualmachineresourcetags <tags> : Utilisé avec --addvirtualmachineresourcetags pour spécifier la liste d’étiquettes séparées par des virgules pour l’agent de ressource d’environnement, par exemple, « web, db »

./config.sh --help liste toujours les réponses obligatoires et facultatives les plus récentes.

Diagnostics

Si vous rencontrez des problèmes avec votre agent auto-hébergé, vous pouvez essayer d’exécuter des diagnostics. Après la configuration de l’agent :

./run.sh --diagnostics

Cela s’exécute au travers d’une suite de diagnostic qui peut vous aider à résoudre le problème. La fonctionnalité de diagnostic est disponible à partir de la version 2.165.0 de l’agent.

Aide sur d’autres options

Pour obtenir des informations sur les autres options :

./config.sh --help

L’aide fournit des informations sur les alternatives d’authentification et la configuration sans assistance.

Fonctionnalités

Les capacités de votre agent sont cataloguées et publiées dans le pool pour que seules les builds et les mises en production qu’il peut gérer lui soient attribuées. Consultez Capacités des agents de build et de mise en production.

Dans de nombreux cas, après avoir déployé un agent, vous devez installer des logiciels ou des utilitaires. En règle générale, vous devez installer sur vos agents les logiciels et outils que vous utilisez sur votre machine de développement.

Par exemple, si votre build inclut la tâche npm, la build ne s’exécute pas, sauf si le pool inclut un agent de build sur lequel npm est installé.

Important

Les fonctionnalités incluent toutes les variables d’environnement et les valeurs définies à l’exécution de l’agent. Si l’une de ces valeurs change pendant l’exécution de l’agent, celui-ci doit être redémarré pour récupérer les nouvelles valeurs. Après avoir installé de nouveaux logiciels sur un agent, vous devez le redémarrer pour que la nouvelle capacité s’affiche dans le pool et que la build puisse s’exécuter.

Si vous souhaitez exclure des variables d’environnement en tant que capacités, vous pouvez les désigner en définissant une variable d’environnement VSO_AGENT_IGNORE avec une liste des variables à ignorer séparées par des virgules.

Questions fréquentes (FAQ)

Comment vérifier que j’ai la dernière version de l’agent ?

1. Accédez à l’onglet Pools d’agents :

   1. Connectez-vous à votre organisation (https://dev.azure.com/{yourorganization}).

   2. Choisissez Azure DevOps, Paramètres de l’organisation.

      

   3. Choisissez Pools d’agents.

      

2. Cliquez sur le pool qui contient l’agent.

3. Vérifiez que l’agent est activé.

4. Accédez à l’onglet Capacités :

   1. Sous l’onglet Pools d’agents, sélectionnez le pool d’agents souhaité.

      

   2. Sélectionnez Agents et choisissez l’agent souhaité.

      

   3. Choisissez l’onglet Fonctionnalités.

      

      Notes

      Les agents hébergés par Microsoft n’affichent pas de fonctionnalités système. Pour obtenir la liste des logiciels installés sur des agents hébergés par Microsoft, consultez Utiliser un agent hébergé par Microsoft.

5. Recherchez la capacité Agent.Version. Vous pouvez vérifier cette valeur en la comparant à la dernière version publiée de l’agent. Consultez Agent Azure Pipelines et recherchez le numéro de version le plus élevé dans la page.

6. Chaque agent est mis à jour automatiquement quand il exécute une tâche nécessitant une version plus récente de l’agent. Si vous souhaitez mettre à jour manuellement certains agents, cliquez avec le bouton droit sur le pool, puis sélectionnez Mettre à jour tous les agents.

Comment m’assurer que j’ai la dernière version de l’agent v2 ?

1. Accédez à l’onglet Pools d’agents :

   1. Connectez-vous à votre organisation (https://dev.azure.com/{yourorganization}).

   2. Choisissez Azure DevOps, Paramètres de l’organisation.

      

   3. Choisissez Pools d’agents.

      

2. Cliquez sur le pool qui contient l’agent.

3. Vérifiez que l’agent est activé.

4. Accédez à l’onglet Capacités :

   1. Sous l’onglet Pools d’agents, sélectionnez le pool d’agents souhaité.

      

   2. Sélectionnez Agents et choisissez l’agent souhaité.

      

   3. Choisissez l’onglet Fonctionnalités.

      

      Notes

      Les agents hébergés par Microsoft n’affichent pas de fonctionnalités système. Pour obtenir la liste des logiciels installés sur des agents hébergés par Microsoft, consultez Utiliser un agent hébergé par Microsoft.

5. Recherchez la capacité Agent.Version. Vous pouvez vérifier cette valeur en la comparant à la dernière version publiée de l’agent. Consultez Agent Azure Pipelines et recherchez le numéro de version le plus élevé dans la page.

6. Chaque agent est mis à jour automatiquement quand il exécute une tâche nécessitant une version plus récente de l’agent. Si vous souhaitez mettre à jour manuellement certains agents, cliquez avec le bouton droit sur le pool, puis sélectionnez Mettre à jour tous les agents.

Pourquoi sudo est-il nécessaire pour exécuter les commandes de service ?

./svc.sh utilise systemctl, qui nécessite sudo.

Code source : systemd.svc.sh.template sur GitHub

J’exécute un pare-feu et mon code se trouve dans Azure Repos. Avec quelles URL l’agent doit-il communiquer ?

Si vous exécutez un agent dans un réseau sécurisé derrière un pare-feu, vérifiez qu’il peut démarrer une communication avec les URL et adresses IP suivantes.

URL du domaine	Description
https://{organization_name}.pkgs.visualstudio.com	API d’empaquetage Azure DevOps pour les organisations utilisant le domaine {organization_name}.visualstudio.com
https://{organization_name}.visualstudio.com	Pour les organisations utilisant le domaine {organization_name}.visualstudio.com
https://{organization_name}.vsblob.visualstudio.com	Télémétrie Azure DevOps pour les organisations utilisant le domaine {organization_name}.visualstudio.com
https://{organization_name}.vsrm.visualstudio.com	Services Release Management pour les organisations utilisant le domaine {organization_name}.visualstudio.com
https://{organization_name}.vssps.visualstudio.com	Services de plateforme Azure DevOps pour les organisations utilisant le domaine {organization_name}.visualstudio.com
https://{organization_name}.vstmr.visualstudio.com	Services de gestion des tests Azure DevOps pour les organisations utilisant le domaine {organization_name}.visualstudio.com
https://*.blob.core.windows.net	Azure Artifacts
https://*.dev.azure.com	Pour les organisations utilisant le domaine dev.azure.com
https://*.vsassets.io	Azure Artifacts avec CDN
https://*.vsblob.visualstudio.com	Télémétrie Azure DevOps pour les organisations utilisant le domaine dev.azure.com
https://*.vssps.visualstudio.com	Services de plateforme Azure DevOps pour les organisations utilisant le domaine dev.azure.com
https://*.vstmr.visualstudio.com	Services de gestion des tests Azure DevOps pour les organisations utilisant le domaine dev.azure.com
https://app.vssps.visualstudio.com	Pour les organisations utilisant le domaine {organization_name}.visualstudio.com
https://dev.azure.com	Pour les organisations utilisant le domaine dev.azure.com
https://login.microsoftonline.com	Connexion Microsoft Entra
https://management.core.windows.net	API de gestion Azure
https://vstsagentpackage.azureedge.net	Package d’agent

Pour garantir que votre organisation fonctionne avec les restrictions de pare-feu ou d’IP existantes, vérifiez que dev.azure.com et *dev.azure.com sont ouverts et mettez à jour vos IP sur liste verte pour y inclure les adresses IP suivantes, en fonction de votre version IP. Si les adresses IP 13.107.6.183 et 13.107.9.183 sont déjà sur votre liste verte, conservez-les, car vous n’avez pas besoin de les supprimer.

Plages IPv4

• 13.107.6.0/24
• 13.107.9.0/24
• 13.107.42.0/24
• 13.107.43.0/24

Plages IPv6

• 2620:1ec:4::/48
• 2620:1ec:a92::/48
• 2620:1ec:21::/48
• 2620:1ec:22::/48

Notes

Pour plus d’informations sur les adresses autorisées, consultez Connexions réseau et listes d’adresses autorisées.

Comment exécuter l’agent avec un certificat auto-signé ?

Exécuter l’agent avec un certificat auto-signé

Comment exécuter l’agent derrière un proxy web ?

Exécuter l’agent derrière un proxy web

Comment redémarrer l’agent ?

Si vous exécutez l’agent de manière interactive, consultez les instructions de redémarrage dans Exécuter de manière interactive. Si vous exécutez l’agent en tant que service systemd, suivez les étapes pour Arrêter, puis Démarrer l’agent.

Comment configurer l’agent pour contourner un proxy web et me connecter à Azure Pipelines ?

Si vous souhaitez que l’agent contourne votre proxy et se connecte directement à Azure Pipelines, vous devez configurer votre proxy web pour permettre à l’agent d’accéder aux URL suivantes.

Pour les organisations qui utilisent le domaine *.visualstudio.com :

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

Pour les organisations qui utilisent le domaine dev.azure.com :

https://dev.azure.com
https://*.dev.azure.com
https://login.microsoftonline.com
https://management.core.windows.net
https://vstsagentpackage.azureedge.net
https://vssps.dev.azure.com

Pour garantir que votre organisation fonctionne avec les restrictions de pare-feu ou d’IP existantes, vérifiez que dev.azure.com et *dev.azure.com sont ouverts et mettez à jour vos IP sur liste verte pour y inclure les adresses IP suivantes, en fonction de votre version IP. Si les adresses IP 13.107.6.183 et 13.107.9.183 sont déjà sur votre liste verte, conservez-les, car vous n’avez pas besoin de les supprimer.

Plages IPv4

• 13.107.6.0/24
• 13.107.9.0/24
• 13.107.42.0/24
• 13.107.43.0/24

Plages IPv6

• 2620:1ec:4::/48
• 2620:1ec:a92::/48
• 2620:1ec:21::/48
• 2620:1ec:22::/48

Notes

Cette procédure permet à l’agent de contourner un proxy web. Votre pipeline et vos scripts de build doivent toujours gérer le contournement de votre proxy web pour chaque tâche et outil que vous exécutez dans votre build.

Par exemple, si vous utilisez une tâche NuGet, vous devez configurer votre proxy web pour prendre en charge le contournement de l’URL pour le serveur qui héberge le flux NuGet que vous utilisez.

J’utilise TFS et les URL dans les sections plus haut ne fonctionnent pas pour moi. Où puis-je obtenir de l’aide ?

Paramètres et sécurité des sites web