Agents Linux autohébergés

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

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. Consultez Vérifier les prérequis pour obtenir la liste des distributions Linux prises en charge.

En savoir plus sur les agents

Si vous connaissez 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 leur fonctionnement, consultez les agents Azure Pipelines.

Vérifier les prérequis

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.

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 à autant d’utilisateurs que possible, car ils 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. Il peut s’agir par nature d’une cible pour les attaques RCE (Remote Code Execution).

Par conséquent, il est important de prendre en compte le modèle de menace entourant chaque utilisation individuelle des agents de pipelines pour effectuer le travail, et de décider quelles sont les autorisations minimales qui peuvent être accordées à l’utilisateur exécutant l’agent, à l’ordinateur sur lequel l’agent s’exécute, aux utilisateurs qui ont accès en écriture à la définition de pipeline, les dépôts git où le yaml est stocké, ou le groupe d’utilisateurs qui contrôlent l’accès au pool pour les nouveaux pipelines.

Il est préférable que l'identité sous laquelle l'agent s'exécute soit distincte de celle ayant les autorisations pour relier 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 conséquent, il est plus sûr d’envisager soigneusement l’accès accordé à l’ordinateur de l’agent lui-même, ainsi que les dossiers de l’agent qui contiennent des fichiers sensibles, tels que les journaux et les 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’examiner le système de fichiers pour comprendre les échecs de build ou obtenir des fichiers journaux pour pouvoir signaler des échecs Azure DevOps.

Déterminer l’utilisateur que vous allez utiliser

À titre d’étape unique, vous devez inscrire l’agent. Une personne disposant de l’autorisation d’administrer la file d’attente de l’agent doit effectuer ces étapes. 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.

Confirmer que l’utilisateur dispose d’une autorisation

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

L’utilisateur est-il propriétaire de l’organisation Azure DevOps ou TFS ou administrateur du serveur Azure DevOps ? Arrêtez-vous ici, vous avez l’autorisation.

Autrement:

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. Sélectionnezles paramètres de l’organisation>.

      

   3. Sélectionnez Pools d’agents.

      

   1. Connectez-vous à votre collection de projets (http://your-server/DefaultCollection).

   2. Sélectionnezles paramètres de collection>.

      

   3. Sélectionnez Pools d’agents.

      

   

2. Sélectionnez le pool sur le côté droit 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 DevOpsou 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.

Télécharger et configurer l’agent

URL du serveur

Type d’authentification

Lorsque vous enregistrez un agent, choisissez parmi les types d'authentification suivants et la configuration de l'agent vous invite à fournir les informations supplémentaires spécifiques requises pour chaque type d'authentification. Pour plus d'informations, consultez Options d'authentification de l'agent auto-hébergé.

Exécuter de manière interactive

Pour obtenir de l’aide sur le choix entre l’exécution de l’agent en mode interactif ou en tant que service, consultez Agents : Interactif ou 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 une tâche en utilisant le pool de l’agent. Si vous n'avez pas choisi un autre pool, votre agent est placé dans le pool par défaut.

Exécuter une fois

Si les agents sont configurés pour fonctionner de manière interactive, vous pouvez choisir de les configurer pour qu’ils puissent n’accepter qu’une seule tâche. Pour s’exécuter dans cette configuration :

./run.sh --once

Les agents de ce mode n’acceptent qu’un seul travail, puis s’exécutent correctement (utile pour l’exécution 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.

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$

Installez

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 username le paramètre 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êtez

sudo ./svc.sh stop

Désinstaller

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 systemd fichier de service 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 en utilisant cgroups et d'un plus faible oom_score_adj. 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. Apprenez à configurer le score cgroups 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.

Lorsque vous configurez un agent avec le même nom qu’un agent qui existe déjà, 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é dans la section précédente.

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.

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

Diagnostiques

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

./run.sh --diagnostics

Cette opération s’exécute via une suite de diagnostics 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 en savoir plus sur d’autres options :

./config.sh --help

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

Capacité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 les fonctionnalités de build et de mise en production de l’agent.

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 ordinateur de développement.

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

Questions fréquentes (FAQ)

Où puis-je en savoir plus sur le nouveau logiciel d’agent v3 ?

Pour plus d’informations et des questions fréquentes sur le logiciel de l’agent v3, consultez La version 3 du logiciel agent.

Comment vérifier que je dispose de 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. Sélectionnezles paramètres de l’organisation>.

      

   3. Sélectionnez Pools d’agents.

      

   1. Connectez-vous à votre collection de projets (http://your-server/DefaultCollection).

   2. Sélectionnezles paramètres de collection>.

      

   3. Sélectionnez 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.

      

      Remarque

      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.

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

      

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

      

   3. Choisissez l’onglet Fonctionnalités.

      

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

6. Chaque agent se met automatiquement à jour lorsqu’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

13.107.6.0/24
13.107.9.0/24
13.107.42.0/24
13.107.43.0/24
150.171.22.0/24 
150.171.23.0/24 
150.171.73.0/24 
150.171.74.0/24 
150.171.75.0/24 
150.171.76.0/24

2620:1ec:4::/48
2620:1ec:a92::/48
2620:1ec:21::/48
2620:1ec:22::/48
2620:1ec:50::/48 
2620:1ec:51::/48 
2603:1061:10::/48

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.

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

https://dev.azure.com
https://*.dev.azure.com
https://login.microsoftonline.com
https://management.core.windows.net
https://download.agent.dev.azure.com
https://vssps.dev.azure.com

13.107.6.0/24
13.107.9.0/24
13.107.42.0/24
13.107.43.0/24
150.171.22.0/24 
150.171.23.0/24 
150.171.73.0/24 
150.171.74.0/24 
150.171.75.0/24 
150.171.76.0/24

2620:1ec:4::/48
2620:1ec:a92::/48
2620:1ec:21::/48
2620:1ec:22::/48
2620:1ec:50::/48 
2620:1ec:51::/48 
2603:1061:10::/48

Prérequis pour l’interface 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.

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 auto-hé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 la version 14.135.0 de TEE-CLC depuis les réleases GitHub de Team Explorer Everywhere.
3. Extrayez le contenu du dossier TEE-CLC-14.135.0 vers <agent_directory>/externals/tee.