Premiers pas avec AWX : lancer son premier job

Votre plateforme tourne, l'interface est vide, et rien n'indique par où commencer. Ce guide vous fait exécuter un vrai playbook sur un vrai serveur, en assemblant les quatre objets qui constituent tout job AWX : un identifiant, un inventaire, un projet et un job template.

Comptez une vingtaine de minutes. À la fin, vous saurez lire un PLAY RECAP depuis l'interface et comprendrez pourquoi AWX a besoin de ces quatre briques, et pas d'une de moins.

Ce que vous allez apprendre

• Assembler les quatre objets indispensables à toute exécution
• Créer un identifiant machine à partir d'une clé SSH
• Déclarer un hôte dans un inventaire
• Rattacher un projet Git contenant vos playbooks
• Lancer un job et interpréter sa sortie
• Diagnostiquer les deux échecs les plus fréquents du premier job

Prérequis

• Une plateforme AWX ou Ascender fonctionnelle. Voir Installer Ascender sur k3s.
• Un compte sur cette plateforme, et le droit d'y créer des objets. Un utilisateur neuf ne voit rien tant qu'un administrateur ne lui a rien accordé : voir Les premières actions d'administration.
• Un serveur cible joignable en SSH depuis la plateforme, sur lequel vous disposez d'un compte avec sudo.
• Des notions d'Ansible : playbook, inventaire, variable. Sans elles, l'interface reste opaque. Voir la formation Ansible.

Les quatre objets d'un job

Avant de cliquer, comprenez le modèle. Un job template n'exécute rien par lui-même : il assemble trois ressources, et c'est cet assemblage qui devient lançable.

Objet	Répond à la question	Exemple
Projet	Quel playbook ?	un dépôt Git contenant gather_facts.yml
Inventaire	Sur quelles machines ?	un hôte serveur-lab
Identifiant	Avec quelle authentification ?	un utilisateur et une clé SSH
Job template	Comment les combiner ?	les trois précédents, plus des options

Glissez pour voir

Cette séparation est le cœur de la gouvernance d'AWX : une équipe peut recevoir le droit de lancer un job template sans jamais voir la clé SSH qu'il utilise, ni pouvoir modifier le playbook qu'il exécute.

L'interface est traduite, la documentation officielle ne l'est pas

L'interface d'AWX et d'Ascender suit la langue de votre navigateur. Un lecteur francophone voit donc « Ressources », « Informations d'identification », « Modèles ». Ce guide donne le libellé français, suivi du terme anglais entre parenthèses : c'est celui de l'API, de la documentation officielle et des messages d'erreur, donc celui à taper dans un moteur de recherche. Quelques valeurs restent en anglais dans l'interface, comme Machine, SSH Private Key ou Source Control : elles viennent de l'API et ne sont pas traduites.

Étape 1 - Se connecter

Ouvrez https://ascender.lab.local/ et connectez-vous avec votre compte nominatif, celui créé lors des premières actions d'administration. Les objets que vous allez créer porteront ainsi votre nom dans le journal d'activité, ce qui n'arriverait pas derrière un compte admin partagé.

Si vous montez un lab jetable et que le compte admin d'origine vous suffit, son mot de passe est stocké dans un secret Kubernetes, qui fait foi :

kubectl -n ascender get secret ascender-app-admin-password \
  -o jsonpath="{.data.password}" | base64 -d ; echo

Étape 2 - Créer l'identifiant machine

L'identifiant, appelé credential, contient le compte et la clé privée qu'Ansible utilisera pour se connecter à vos serveurs. Il est chiffré en base dès l'enregistrement.

1. Préparez une clé dédiée sur votre poste, plutôt que de réutiliser votre clé personnelle. Une plateforme d'automatisation mérite sa propre identité, révocable indépendamment :

   ssh-keygen -t ed25519 -C "ascender-lab" -f ~/.ssh/ascender-lab

   Autorisez la clé publique sur le serveur cible :

   ssh-copy-id -i ~/.ssh/ascender-lab.pub ubuntu@192.168.10.208

2. Dans l'interface, ouvrez Ressources > Informations d'identification (Resources > Credentials), puis Ajouter (Add). Renseignez :

   • Nom (Name) : Lab SSH
   • Type d'informations d'identification (Credential Type) : Machine
   • Nom d'utilisateur (Username) : ubuntu
   • Clé privée SSH (SSH Private Key) : collez le contenu de ~/.ssh/ascender-lab (la clé privée, sans l'extension .pub)

3. Enregistrez (Save). Rouvrez la fiche : le champ de la clé affiche Crypté, et son contenu n'est plus jamais relisible, y compris par un administrateur.

Un secret entré dans AWX ne ressort pas

Le chiffrement est à sens unique du point de vue de l'interface : AWX peut utiliser la clé, personne ne peut la relire. C'est ce qu'indique la mention Crypté à la place de sa valeur. Si vous perdez l'original, il faudra en générer une nouvelle et la redéployer. Ce n'est pas un défaut, c'est la propriété qui rend le coffre utile.

Étape 3 - Déclarer l'hôte dans un inventaire

L'inventaire décrit le parc. Une installation neuve en fournit un vide, nommé Default Inventory.

1. Ouvrez Ressources > Inventaires (Resources > Inventories), puis Default Inventory, onglet Hôtes (Hosts), et Ajouter (Add).

2. Renseignez le nom (Name) serveur-lab. Ce nom est une étiquette, pas une adresse : c'est lui qui apparaîtra dans les sorties de job.

3. Dans Variables, donnez l'adresse réelle :

   ansible_host: 192.168.10.208

Pourquoi séparer le nom et l'adresse

Nommer l'hôte serveur-lab plutôt que 192.168.10.208 rend les sorties lisibles et permet de changer l'adresse sans toucher aux playbooks ni aux job templates. C'est la même logique qu'un inventaire Ansible en fichier plat.

Étape 4 - Rattacher un projet Git

Le projet relie un dépôt Git à la plateforme. AWX le clone, puis met le contenu à disposition des jobs.

Une installation d'Ascender arrive avec un projet déjà synchronisé, Ascender Playbooks, qui contient trois playbooks utilisables immédiatement : gather_facts.yml, patching.yml et selinux.yml. Nous utiliserons le premier.

Pour rattacher votre dépôt, ouvrez Ressources > Projets (Resources > Projects), puis Ajouter (Add), et renseignez le type de source Git, l'URL du dépôt, et la branche. Un dépôt privé nécessite en plus un identifiant de type Source Control, libellé qui reste en anglais dans l'interface.

Vérifiez la synchronisation avant d'aller plus loin

Un projet dont la dernière synchronisation a échoué produira un job template incapable de trouver le playbook, avec un message peu explicite. L'onglet Jobs du projet affiche le journal de la synchronisation : lisez-le avant de continuer.

Étape 5 - Créer le job template

Le job template est l'objet qui assemble les trois précédents.

1. Ouvrez Ressources > Modèles (Resources > Templates), puis Ajouter (Add), et Ajouter un modèle de job (Add job template).

2. Renseignez :

   • Nom (Name) : Collecter les faits
   • Type de Job (Job Type) : Exécuter (Run)
   • Inventaire (Inventory) : Default Inventory
   • Projet (Project) : Ascender Playbooks
   • Playbook : gather_facts.yml
   • Informations d'identification (Credentials) : Lab SSH

3. Enregistrez (Save). La liste des playbooks proposés provient du dépôt cloné : si elle est vide, la synchronisation du projet a échoué.

Étape 6 - Lancer le job et lire sa sortie

Cliquez sur la fusée à côté du template. L'interface bascule sur la sortie, qui défile en temps réel.

Identity added: /runner/artifacts/7/ssh_key_data (ascender-lab)

PLAY [Gather System Facts] *****************************************************

TASK [Gathering Facts] *********************************************************
ok: [serveur-lab]

TASK [Gather package facts] ****************************************************
ok: [serveur-lab]

TASK [Gather service facts] ****************************************************
ok: [serveur-lab]

TASK [Gather Windows Disk Facts] ***********************************************
skipping: [serveur-lab]

PLAY RECAP *********************************************************************
serveur-lab   : ok=3  changed=0  unreachable=0  failed=0  skipped=1  rescued=0  ignored=0

Trois lignes méritent votre attention.

La première, Identity added, montre AWX injectant la clé privée du credential dans l'agent SSH du conteneur d'exécution, au moment du lancement. La clé n'existe que le temps du job.

Le nom serveur-lab apparaît partout, jamais l'adresse IP : c'est l'étiquette de l'inventaire qui prime.

Enfin le PLAY RECAP est le même que celui d'ansible-playbook en ligne de commande, parce que c'est le même programme. AWX ne réimplémente pas Ansible, il l'exécute dans un conteneur appelé Execution Environment, puis capture sa sortie.

Dépannage du premier job

Symptôme	Cause	Correctif
UNREACHABLE, Permission denied (publickey)	la clé publique n'est pas autorisée sur la cible	ssh-copy-id vers le serveur, puis relancer
UNREACHABLE, délai dépassé	le conteneur d'exécution ne joint pas le port 22 de la cible	vérifier le routage et le pare-feu depuis le cluster
La liste des playbooks est vide	la synchronisation du projet a échoué	lire le journal dans l'onglet Jobs du projet
sudo: a password is required	l'escalade de privilèges n'a pas de mot de passe	cocher Élévation des privilèges (Privilege Escalation) et renseigner le mot de passe become dans le credential
Le job réussit mais ne fait rien	l'inventaire ne contient aucun hôte correspondant	vérifier que le playbook cible bien le groupe où se trouve l'hôte

Glissez pour voir

Le job de démonstration réussit sans rien faire

L'installeur d'Ascender crée un Demo Job Template dont l'exécution se solde par provided hosts list is empty puis skipping: no hosts matched. Le job est marqué réussi, alors qu'aucune tâche n'a tourné. C'est un piège classique pour un débutant : un PLAY RECAP sans ligne d'hôte signifie que rien n'a été fait.

À retenir

• Un job template n'exécute rien seul : il assemble un projet, un inventaire et un identifiant.
• Cette séparation permet de déléguer l'exécution sans déléguer les secrets ni le code.
• Un secret entré dans AWX est chiffré et non relisible : conservez l'original ailleurs.
• Le nom d'un hôte est une étiquette ; son adresse vit dans la variable ansible_host.
• AWX n'exécute pas Ansible différemment : il lance ansible-playbook dans un Execution Environment et capture sa sortie. Le PLAY RECAP est identique.
• Un PLAY RECAP sans ligne d'hôte signifie que le job n'a rien fait, même s'il est marqué réussi.
• Les deux échecs les plus fréquents du premier job sont une clé non autorisée sur la cible et un projet mal synchronisé.

Prochaines étapes

AWX : concepts et avenir du projet Le pivot du hub : ce qu'est AWX, face à Ansible Tower et AAP.

Installer Ascender sur k3s Monter la plateforme de zéro, en HTTPS, avec les pièges du terrain.

Maîtriser les workflows Enchaîner plusieurs job templates conditionnellement.

Execution Environments L'image OCI qui exécute réellement vos playbooks.

×

📖 Voir la documentation →