Installer Ascender (fork AWX) sur k3s, en HTTPS

Ce guide installe Ascender 25.4.0, le fork maintenu d'AWX, sur un cluster k3s mono-nœud, servi en HTTPS. L'installeur officiel monte le cluster lui-même : vous n'avez pas besoin d'un Kubernetes préexistant. Le tout tient sur une machine virtuelle.

Le chemin est balisé, mais cinq pièges bloquent l'installation, dont un dont le message d'erreur ne désigne pas la cause. Chacun est documenté ici avec son symptôme exact et son correctif. Public visé : administrateurs à l'aise avec Kubernetes et Ansible.

Pourquoi Ascender et pas AWX

AWX ne publie plus de version depuis le 2 juillet 2024, le temps d'une refonte. Ascender est son fork maintenu par Ctrl IQ, l'éditeur de Rocky Linux, avec des versions patchées régulières. Le modèle objet, l'API et l'interface sont ceux d'AWX. Le contexte complet est expliqué dans le pivot du hub.

Vous avez déjà un cluster Kubernetes ? Passez votre chemin

Ce guide s'adresse à qui part d'une machine virtuelle nue. L'installeur monte k3s lui-même, ce qui rend service quand on n'a rien, et devient un problème quand un cluster existe déjà : le script en déploierait un second à côté du vôtre.

L'installeur n'est d'ailleurs pas une alternative à l'operator, c'est un enrobage autour de lui. La configuration écrite plus bas porte une ligne ASCENDER_OPERATOR_VERSION, et la plateforme obtenue fait tourner le même contrôleur ascender-operator. Ce que le script apporte en plus, c'est le cluster, le secret TLS, l'entrée dans /etc/hosts et Ledger. Ce qu'il vous retire, c'est le choix des versions d'images et toute possibilité de rejouer l'installation depuis un dépôt Git.

Si votre cluster existe déjà, allez directement à Installer AWX sur Kubernetes avec l'operator : la même plateforme y est déployée en trois manifestes que vous maîtrisez.

Ce que vous allez apprendre

• Dimensionner la machine et éviter le piège du processeur virtuel
• Configurer l'installeur sans passer par son script interactif
• Installer Ascender, PostgreSQL et Ledger sur un k3s monté à la volée
• Servir l'interface en HTTPS et forcer la redirection depuis HTTP
• Diagnostiquer les cinq erreurs qui font perdre le plus de temps

Prérequis

• Une machine virtuelle dédiée, avec un accès sudo.
• Système supporté : Enterprise Linux 8 ou 9 (Rocky, Alma, RHEL, CentOS Stream, Fedora), ou Ubuntu 24. Les autres versions ne sont pas prises en charge par l'installeur.
• 4 vCPU, 12 Go de RAM, 60 Go de disque. La documentation annonce 8 Go minimum pour Ascender et Ledger : c'est un plancher réel, pas une suggestion.
• Un accès Internet sortant (une installation hors ligne existe, avec un bundle d'images).

Le processeur virtuel doit exposer x86-64-v2

C'est le piège le plus coûteux, et le message d'erreur ne mentionne jamais la machine virtuelle. Les images PostgreSQL d'Ascender sont bâties sur CentOS Stream 9, dont la glibc exige le niveau de microarchitecture x86-64-v2 (SSE4.2, POPCNT, SSSE3, CX16).

Or Proxmox propose par défaut un processeur virtuel kvm64, qui n'expose pas ces jeux d'instructions. Le pod PostgreSQL meurt alors en boucle avec Fatal glibc error: CPU does not support x86-64-v2. Sur Proxmox, avant toute chose :

qm set <vmid> --cpu host

Vérifiez ensuite depuis la machine virtuelle que la glibc voit bien le niveau requis :

/usr/lib/x86_64-linux-gnu/ld-linux-x86-64.so.2 --help | grep x86-64-v2

La sortie doit contenir x86-64-v2 (supported, searched).

Étape 1 - Récupérer l'installeur

L'installeur est un dépôt Git contenant des playbooks Ansible. Il installera ansible-core lui-même s'il est absent.

1. Installez Git et clonez le dépôt :

   sudo apt-get update && sudo apt-get install -y git
   git clone https://github.com/ctrliq/ascender-install.git
   cd ascender-install

2. Rendez le script exécutable. Il ne l'est pas dans le dépôt, et l'oubli produit une erreur déroutante :

   chmod +x setup.sh config_vars.sh

   Sans cela, le lancement échoue sur nohup: failed to run command './setup.sh': Permission denied.

Étape 2 - Générer le certificat TLS

Le protocole HTTPS exige un certificat et sa clé privée. Un certificat auto-signé convient pour une maquette ; en production, utilisez une autorité de certification reconnue.

Générez-le avec un SubjectAltName couvrant les deux noms d'hôte et l'adresse IP, sans quoi les navigateurs et curl refuseront le certificat même en ignorant l'autorité :

openssl req -x509 -newkey rsa:2048 -nodes -days 365 \
  -keyout /home/ubuntu/ascender.key -out /home/ubuntu/ascender.crt \
  -subj "/C=FR/O=Lab/CN=ascender.lab.local" \
  -addext "subjectAltName=DNS:ascender.lab.local,DNS:ledger.lab.local,IP:192.168.10.208"
chmod 600 /home/ubuntu/ascender.key

Chemins absolus obligatoires

La documentation officielle donne l'exemple tls_crt_path: "~/ascender.crt". Ce tilde ne fonctionne pas. Le script setup.sh s'exécute sous sudo, donc Ansible résout ~ en /root, où le certificat n'existe pas. L'installation échoue sur :

AnsibleLookupError: The 'file' lookup had an issue accessing
the file '~/ascender.crt'. file not found

Renseignez toujours des chemins absolus.

Étape 3 - Écrire la configuration

Le dépôt fournit config_vars.sh, un script interactif qui pose une série de questions. Pratique pour découvrir, inutilisable pour un lab reproductible ou une chaîne d'intégration. Écrivez directement custom.config.yml, qui est le fichier réellement consommé.

---
k8s_platform: k3s
k8s_lb_protocol: https
kubeapi_server_ip: "192.168.10.208"
kube_install: true
k8s_offline: false
download_kubeconfig: true
k3s_master_node_ip: "192.168.10.208"

tls_crt_path: "/home/ubuntu/ascender.crt"
tls_key_path: "/home/ubuntu/ascender.key"

use_etc_hosts: true

ASCENDER_HOSTNAME: ascender.lab.local
ASCENDER_NAMESPACE: ascender
ASCENDER_ADMIN_USER: admin
ASCENDER_ADMIN_PASSWORD: "RemplacezCeMotDePasse"
ASCENDER_IMAGE: ghcr.io/ctrliq/ascender
ASCENDER_VERSION: 25.4.0
ASCENDER_OPERATOR_VERSION: 2.19.6
ascender_garbage_collect_secrets: true

LEDGER_INSTALL: true
LEDGER_HOSTNAME: ledger.lab.local
LEDGER_NAMESPACE: ledger
LEDGER_ADMIN_PASSWORD: "RemplacezAussiCeluiCi"
LEDGER_DB_PASSWORD: "EtCeluiDeLaBase"

Quelques variables méritent une explication. kube_install: true demande à l'installeur de monter k3s lui-même sur l'hôte. use_etc_hosts: true ajoute les deux noms d'hôte dans /etc/hosts, ce qui évite de configurer un DNS pour une maquette. ascender_garbage_collect_secrets conserve les secrets de chiffrement, ce qui devient indispensable au moment des sauvegardes.

L'inventaire par défaut convient tel quel pour une installation mono-machine : il pointe déjà sur localhost en connexion locale.

Ledger, le composant de reporting

Ledger reçoit le flux de logs d'Ascender et permet de construire des rapports sur les faits collectés et sur les changements produits par les playbooks. Il est optionnel, mais c'est lui qui justifie les 8 Go de mémoire. Passez LEDGER_INSTALL: false pour vous en passer.

Étape 4 - Lancer l'installation

sudo ./setup.sh

Le script installe ansible-core, monte k3s avec Traefik, déploie l'ascender-operator, puis l'objet AWX qui provoque la création de PostgreSQL, du pod web et du pod de tâches. Comptez vingt à trente minutes, l'essentiel étant le téléchargement des images.

La réussite se lit dans le récapitulatif final :

PLAY RECAP *********************************************************
ascender_host   : ok=15  changed=3  unreachable=0  failed=0
localhost       : ok=79  changed=21 unreachable=0  failed=0

ASCENDER SUCCESSFULLY SETUP

Étape 5 - Vérifier l'installation

Les pods doivent tous être en état Running, sur trois espaces de noms :

sudo kubectl get pods -A

NAMESPACE   NAME                                READY   STATUS    RESTARTS
ascender    ascender-app-postgres-15-0          1/1     Running   0
ascender    ascender-app-task-84d7748647-zff6q  4/4     Running   0
ascender    ascender-app-web-5c589b6587-46mg2   3/3     Running   0
ascender    awx-operator-controller-manager-... 2/2     Running   0
ledger      db-7f9cd59455-2w57c                 1/1     Running   0
ledger      parser-b4d9dccc8-fgjmr              1/1     Running   0
ledger      web-7c669dc99b-lf668                1/1     Running   0

L'API répond ensuite sur son point d'entrée de diagnostic. Le drapeau -k est nécessaire tant que le certificat est auto-signé :

curl -sk https://ascender.lab.local/api/v2/ping/

{
  "ha": false,
  "version": "25.4.0",
  "active_node": "ascender-app-web-5c589b6587-46mg2",
  "instances": [{ "node_type": "control", "capacity": 119 }]
}

Une authentification complète se vérifie en demandant un jeton, puis en lisant la configuration :

curl -sk -u "admin:VotreMotDePasse" -X POST \
  https://ascender.lab.local/api/v2/tokens/ -H "Content-Type: application/json" -d '{}'

Étape 6 - Accéder à l'interface depuis votre poste

C'est ici que beaucoup se retrouvent bloqués. L'installeur a bien inscrit ascender.lab.local dans le /etc/hosts de la machine virtuelle, grâce à use_etc_hosts: true. Mais votre poste de travail, lui, ne connaît pas ce nom.

Pointer le navigateur sur l'adresse IP ne fonctionne pas

Traefik ne route pas sur l'adresse IP, il route sur l'en-tête Host de la requête, parce que la règle d'ingress déclare host: ascender.lab.local. Une requête arrivant sur l'IP nue ne correspond à aucun routeur, et vous obtenez un 404 parfaitement déroutant :

curl -sk -o /dev/null -w "%{http_code}\n" https://192.168.10.208/api/v2/ping/
# 404

La même requête, avec le bon nom, répond 200. Le service fonctionne : c'est le nom qui manque.

1. Déclarez les deux noms sur votre poste, en remplaçant l'adresse par celle de votre machine virtuelle.

   Linux et macOS

   echo "192.168.10.208 ascender.lab.local ledger.lab.local" | sudo tee -a /etc/hosts

   Windows

   Le fichier est C:\Windows\System32\drivers\etc\hosts, sans extension. Ne touchez pas à hosts.ics, qui appartient au partage de connexion Internet et n'a aucun effet sur la résolution de noms.

   Ouvrez le Bloc-notes en tant qu'administrateur, puis ouvrez ce fichier depuis lui : un double-clic direct provoquerait un refus d'écriture à l'enregistrement. Ajoutez la ligne :

   192.168.10.208 ascender.lab.local ledger.lab.local

   À l'enregistrement, choisissez le type Tous les fichiers, sinon le Bloc-notes ajoute silencieusement une extension .txt. Videz enfin le cache de résolution :

   ipconfig /flushdns

   Vérifiez immédiatement, sans quitter le terminal :

   curl -sk https://ascender.lab.local/api/v2/ping/

   La réponse doit contenir "version": "25.4.0".

2. Récupérez le mot de passe administrateur. Il vaut ce que vous avez mis dans ASCENDER_ADMIN_PASSWORD, mais il est aussi stocké dans un secret Kubernetes, ce qui est la source de vérité :

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

3. Ouvrez https://ascender.lab.local/ dans un navigateur. Le certificat étant auto-signé, le navigateur affiche un avertissement : acceptez l'exception. Connectez-vous avec l'utilisateur admin et le mot de passe récupéré.

4. Ledger est accessible de la même manière, sur https://ledger.lab.local/.

Votre première action : changer le mot de passe administrateur

L'installation est terminée, et elle vous laisse avec un problème immédiat. Le mot de passe d'admin a été écrit en clair dans custom.config.yml, il vit dans l'historique de votre shell, et il est peut-être passé par un dépôt Git. Ce compte peut tout faire sur la plateforme : lire les identifiants, modifier les playbooks exécutés, lancer n'importe quel job sur n'importe quelle machine.

Changez-le avant toute autre chose, depuis Accès > Utilisateurs (Access > Users), puis admin, onglet Détails (Details), Modifier (Edit). L'interface suit la langue de votre navigateur : les guides de ce hub donnent le libellé français, puis le terme anglais entre parenthèses. Créez dans la foulée votre propre compte administrateur nominatif, et cessez d'utiliser le compte partagé : un journal d'activité qui n'affiche que admin n'identifie personne et n'a aucune valeur d'audit.

La marche à suivre complète, avec les organisations, les équipes et la délégation des droits, est dans Les premières actions d'administration. C'est la page à ouvrir juste après celle-ci.

Une fois la plateforme sécurisée, vous pourrez lancer votre premier playbook en suivant Premiers pas avec AWX.

Sans modifier son fichier hosts

Pour un test ponctuel, curl sait forcer la résolution le temps d'une requête, sans toucher à /etc/hosts :

curl -sk --resolve ascender.lab.local:443:192.168.10.208 \
  https://ascender.lab.local/api/v2/ping/

Sécurité : forcer HTTPS

Positionner k8s_lb_protocol: https ne suffit pas. L'installeur crée bien le secret TLS et l'attache à l'ingress d'Ascender, mais deux trous subsistent, vérifiables immédiatement :

curl -s -o /dev/null -w "%{http_code}\n" http://ascender.lab.local/   # 200, en clair
kubectl -n ledger get ingress ledger-web-ingress -o jsonpath='{.spec.tls}'  # vide

Autrement dit, HTTP continue d'être servi sans redirection, et l'ingress de Ledger n'a aucun TLS, alors même que l'installeur a déjà copié le secret ascender-tls-secret dans son espace de noms. Voici le correctif, en deux temps.

1. Créez un middleware Traefik de redirection dans chaque espace de noms :

   apiVersion: traefik.io/v1alpha1
   kind: Middleware
   metadata:
     name: redirect-https
     namespace: ascender
   spec:
     redirectScheme:
       scheme: https
       permanent: true

   Répétez l'opération avec namespace: ledger.

2. Branchez-le sur Ascender via le CR, et non sur l'ingress. L'ingress d'Ascender est réconcilié par l'operator : un kubectl patch direct serait écrasé à la prochaine boucle.

   kubectl -n ascender patch awx ascender-app --type=merge -p \
     '{"spec":{"ingress_annotations":"traefik.ingress.kubernetes.io/router.middlewares: ascender-redirect-https@kubernetescrd"}}'

3. Corrigez l'ingress de Ledger directement, puisqu'aucun operator ne le gère. On ajoute au passage le spec.tls manquant :

   kubectl -n ledger patch ingress ledger-web-ingress --type=merge -p \
     '{"metadata":{"annotations":{"traefik.ingress.kubernetes.io/router.middlewares":"ledger-redirect-https@kubernetescrd"}},
       "spec":{"tls":[{"hosts":["ledger.lab.local"],"secretName":"ascender-tls-secret"}]}}'

Le résultat se contrôle par le comportement, seul juge fiable :

curl -s -o /dev/null -w "%{http_code} -> %{redirect_url}\n" http://ascender.lab.local/
# 301 -> https://ascender.lab.local/
curl -s -o /dev/null -w "%{http_code} -> %{redirect_url}\n" http://ledger.lab.local/
# 301 -> https://ledger.lab.local/

Dépannage

Symptôme	Cause	Correctif
Permission denied sur ./setup.sh	script non exécutable dans le dépôt	chmod +x setup.sh
AnsibleLookupError: file '~/ascender.crt' not found	setup.sh tourne sous sudo, ~ vaut /root	chemins absolus dans tls_crt_path et tls_key_path
Fatal glibc error: CPU does not support x86-64-v2, pod PostgreSQL en Init:Error	processeur virtuel kvm64 par défaut	qm set <vmid> --cpu host puis redémarrer
Le pod de tâches reste en Pending ou est tué	mémoire insuffisante	8 Go minimum avec Ledger, 12 Go confortable
https://<adresse-ip>/ répond 404	Traefik route sur l'en-tête Host, pas sur l'IP	déclarer ascender.lab.local dans le /etc/hosts du poste client
http:// répond 200 en clair	l'installeur n'active aucune redirection	middleware Traefik, voir la section Sécurité
L'interface de Ledger n'est pas chiffrée	spec.tls absent de son ingress	patch de l'ingress, voir la section Sécurité

Glissez pour voir

À retenir

• L'installeur d'Ascender monte le cluster k3s lui-même : aucun Kubernetes préexistant n'est requis.
• Le processeur virtuel doit exposer x86-64-v2. Sur Proxmox, le kvm64 par défaut fait échouer PostgreSQL avec un message qui ne désigne pas la machine virtuelle.
• Le dépôt livre setup.sh non exécutable, et sa documentation propose un tls_crt_path en ~ qui ne fonctionne pas sous sudo.
• Préférez écrire custom.config.yml directement plutôt que d'utiliser le script interactif : c'est la seule façon d'obtenir une installation reproductible.
• Traefik route sur l'en-tête Host : pointer le navigateur sur l'adresse IP renvoie un 404 trompeur. Le nom doit être résolu côté poste client.
• k8s_lb_protocol: https ne désactive pas HTTP et n'applique aucun TLS à Ledger. Deux correctifs à appliquer soi-même.
• L'ingress d'Ascender est géré par l'operator : toute annotation doit passer par ingress_annotations sur le CR, sinon elle est écrasée.
• 8 Go de mémoire est un plancher réel dès que Ledger est installé.
• L'installation vous laisse un mot de passe admin écrit en clair dans custom.config.yml. Le changer est la première action d'administration, avant même le premier job.

Prochaines étapes

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

Les premières actions d'administration Changer le mot de passe admin, structurer en organisations et équipes.

Premiers pas avec AWX Créer un identifiant, un inventaire, un projet, et lancer son premier job.

Installer AWX sur Kubernetes La voie de l'operator et de kustomize, sur un cluster existant.

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

×

📖 Voir la documentation →