Si ansible_hostname est undefined, la cause la plus fréquente est simple : les facts ne sont pas collectés. ansible_hostname vient de la machine distante, alors que inventory_hostname vient de l’inventaire Ansible. En production, la bonne pratique consiste à choisir explicitement quelle identité pilote le ciblage, les templates, les sauvegardes et les alertes.

Pourquoi ansible_hostname est parfois undefined

Le cas classique est un playbook avec gather_facts: false ou une collecte de facts qui n’a pas encore eu lieu. Dans ce contexte, ansible_hostname n’existe pas encore, alors que inventory_hostname reste toujours disponible.

Dans Ansible, plusieurs noms peuvent désigner le même serveur. C’est pratique pour l’automatisation, mais dangereux si les rôles ne sont pas cohérents.

inventory_hostname correspond à la clé déclarée dans l’inventaire. Elle peut être un FQDN, une IP, un alias métier ou un nom court choisi par l’équipe.

ansible_hostname correspond au hostname court remonté par les facts du système distant. Il dépend donc de la configuration réelle de la machine.

ansible_fqdn contient généralement le nom pleinement qualifié, quand la résolution DNS et la configuration locale sont correctes.

Comprendre la différence entre ansible_hostname, inventory_hostname et ansible_fqdn

Sur un parc de quelques serveurs, une confusion reste souvent invisible. Sur un environnement multi-clients, multi-sites ou cloud, elle crée des erreurs difficiles à diagnostiquer.

Un alias d’inventaire peut pointer vers une instance remplacée. Le hostname local peut garder une ancienne valeur. Le FQDN peut dépendre d’un DNS interne incomplet.

Les problèmes apparaissent surtout dans les templates de configuration, les certificats TLS, les noms de jobs de sauvegarde et les labels de monitoring.

Choisir une stratégie de nommage fiable

La bonne stratégie consiste à documenter une variable de référence par usage. Cela évite les décisions implicites dans chaque rôle.

Pour le ciblage Ansible, gardez inventory_hostname. Pour les fichiers générés localement sur le serveur, utilisez souvent ansible_hostname.

Pour les certificats, les URLs et les endpoints exposés, préférez un FQDN explicite porté par une variable métier, par exemple service_fqdn.

Décider quelle variable utiliser selon le cas

Le choix dépend moins d’Ansible que du risque opérationnel. Une variable peut être parfaite pour un log local et mauvaise pour un service exposé.

Pour un fichier local, le hostname système est souvent acceptable. Pour un nom visible par un client, un FQDN déclaré reste préférable.

Pour un label de monitoring, privilégiez la stabilité. Un changement de label peut créer une nouvelle série de métriques et masquer l’historique. Sur ce point, la logique est la même que pour une supervision serveur Linux bien structurée.

Pour un chemin de sauvegarde, évitez les valeurs qui changent après migration. Un alias d’inventaire stable est souvent plus lisible.

Dans une équipe d’exploitation, formalisez cette décision dans une petite table de référence. Elle doit être simple, relue et appliquée partout.

Mini-lab : tester ansible_hostname variable en 20 minutes

Ce test se fait sur une VM ou un serveur non critique. Il ne modifie pas la configuration distante.

Préparez un poste avec Ansible installé, un accès SSH et un compte capable d’exécuter des commandes de lecture.

[lab]
web-prod-01 ansible_host=192.0.2.10

Créez ensuite un playbook qui affiche les principales identités Ansible.

---
- name: Comparer les identités Ansible
  hosts: lab
  gather_facts: true
  tasks:
    - name: Afficher les noms utiles
      ansible.builtin.debug:
        msg:
          inventory_hostname: "{{ inventory_hostname }}"
          ansible_hostname: "{{ ansible_hostname }}"
          ansible_fqdn: "{{ ansible_fqdn | default('non défini') }}"

Lancez le test depuis un environnement isolé.

ansible-playbook -i inventory.ini compare-hostnames.yml --check

Le résultat attendu est une sortie qui montre clairement l’alias d’inventaire et le nom réel remonté par le serveur. Si tu veux replacer ce choix dans une approche plus large d’automatisation, regarde aussi Terraform vs Ansible : que choisir en entreprise ?.

Si les deux valeurs diffèrent, ce n’est pas forcément une erreur. C’est un signal pour verrouiller les conventions dans vos rôles.

Pour nettoyer, supprimez simplement les fichiers de test locaux. Aucune modification distante n’est réalisée avec ce playbook.

Checklist avant d’utiliser ces variables dans un rôle

Erreurs courantes et dépannage rapide

Gouvernance : rendre la convention visible dans le dépôt

Une convention de nommage n’aide l’équipe que si elle est visible dans le dépôt. Placez-la près de l’inventaire, pas seulement dans une documentation externe.

Le plus efficace est d’ajouter un court fichier README dans le dossier inventory/. Il doit expliquer les variables utilisées pour le ciblage, l’affichage et les endpoints.

Ajoutez aussi des exemples dans group_vars/all.yml. Les nouveaux rôles auront ainsi une source stable pour choisir le bon nom.

# group_vars/all.yml
# Identité Ansible
# - inventory_hostname : cible Ansible stable
# - ansible_hostname : nom court du système distant
# - service_fqdn : nom exposé aux utilisateurs et certificats
hostname_policy:
  target_name: "{{ inventory_hostname }}"
  local_name: "{{ ansible_hostname | default(inventory_hostname) }}"
  public_name: "{{ service_fqdn | default(ansible_fqdn | default(inventory_hostname)) }}"

Cette approche réduit les décisions dispersées. Elle rend aussi les revues de code plus rapides, car chaque rôle réutilise la même politique.

Contrôle CI : détecter les usages risqués avant production

Un contrôle simple dans la CI évite qu’un rôle introduise une variable de nommage au mauvais endroit. Il ne remplace pas une revue humaine, mais il attrape les erreurs évidentes.

Commencez par chercher les usages directs de ansible_hostname dans les templates et les rôles sensibles. Vérifiez ensuite si le contexte justifie son emploi.

grep -R "ansible_hostname" roles/ templates/ group_vars/ host_vars/

Pour aller plus loin, ajoutez une tâche de lint interne. Elle peut échouer si un rôle utilise ansible_hostname dans un chemin de sauvegarde ou un nom de certificat.

#!/usr/bin/env bash
set -euo pipefail
if grep -R "cert.*ansible_hostname\|backup.*ansible_hostname" roles/ templates/; then
  echo "Usage risqué de ansible_hostname détecté"
  exit 1
fi

Le résultat attendu est une CI qui bloque uniquement les usages dangereux. Les cas légitimes restent possibles avec une variable intermédiaire documentée.

À relier avec vos autres pratiques Ansible

La question du nommage rejoint la collecte des facts, la structure des playbooks et la gestion des secrets. Elle ne doit pas rester isolée.

Si vos rôles dépendent fortement des facts, relisez aussi le guide sur Ansible gather facts et l’inventaire Linux.

Pour fiabiliser les variables et les fichiers sensibles, complétez avec le guide Ansible lookup pour variables, fichiers et secrets.

Ces deux sujets forment un socle utile : connaître l’état réel des machines, puis injecter les bonnes valeurs dans les bons contextes.

FAQ sur ansible_hostname variable

La variable ansible_hostname est utile quand elle est employée volontairement. Elle devient vraiment fiable quand son rôle est écrit, testé et compris par toute l’équipe. Le vrai risque vient des rôles qui l’utilisent comme une évidence.

En standardisant vos conventions, vous réduisez les surprises lors des migrations cloud, des changements DNS et des remplacements de serveurs. Si tu veux aller plus loin sur la sécurisation opérationnelle, tu peux aussi lire Infogérance Linux : quoi mettre en place pour sécuriser et maintenir ses serveurs.