Inventaires et cache de facts
Le format d'inventaire que Volant lit, d'où viennent les variables de groupe et d'hôte, la grammaire des motifs d'hôtes, et comment les facts sont conservés entre deux exécutions.
Cette page répond à ces questions : d’où viennent vos hôtes, comment un motif en choisit certains, et comment conserver leurs facts d’une exécution à l’autre. Vos fichiers d’inventaire, group_vars et host_vars existants sont lus tels quels.
Volant lit les inventaires comme ansible-core : une ou plusieurs sources, chacune analysée par le premier plugin activé qui l’accepte. Une exécution statique (INI, YAML, TOML, liste d’hôtes) ne démarre pas Python.
-i (aussi --inventory et --inventory-file) prend une source et peut être répété. Sans -i, Volant lit ANSIBLE_INVENTORY, puis inventory dans ansible.cfg. Les deux acceptent une liste séparée par des virgules. Sans aucun des deux, Volant lit /etc/ansible/hosts comme ansible-core, et l’ignore sans message si le fichier n’existe pas. Sur une machine sans ce fichier, seul le localhost implicite existe.
Une source est l’un des éléments suivants :
| Source | Notes |
|---|---|
| Un fichier INI | Hôtes, [group], [group:children], [group:vars] et plages. Une plage compte des chiffres (web[01:03], zéros de remplissage conservés), des lettres (db[a:c]) et peut prendre un pas (n[1:10:3]). |
| Un fichier YAML ou TOML | Les formats yaml et toml d’Ansible. |
| Un répertoire | Chaque fichier qu’il contient est une source, parcourue dans l’ordre alphabétique. Les fichiers dont l’extension est ignorée ou qui correspondent à un motif d’exclusion, ainsi que les répertoires group_vars et host_vars, sont ignorés. |
| Une liste séparée par des virgules | -i web1,web2, est une liste d’hôtes (host_list). Un hôte seul demande une virgule finale. advanced_host_list est lu quand vous l’activez. |
| Un fichier exécutable | Lancé comme script d’inventaire dynamique : --list une fois, puis --host <name> pour les hôtes auxquels la liste n’a donné aucune variable. |
| Un fichier de plugin | Un fichier YAML avec plugin: qui nomme constructed, generator ou un plugin d’inventaire de collection (le plugin auto). |
Plusieurs sources sont fusionnées dans l’ordre donné. Une source plus tardive l’emporte clé par clé, les membres de groupe sont réunis, et les hôtes et groupes gardent l’ordre de leur première apparition.
La chaîne de plugins
Section intitulée « La chaîne de plugins »La section [inventory] de ansible.cfg contrôle la façon dont une source est reconnue :
enable_pluginsliste les plugins à essayer, dans l’ordre. La valeur par défaut esthost_list, script, auto, yaml, ini, toml.ignore_extensionsetignore_patternsignorent des fichiers dans les répertoires.unparsed_is_failedfait échouer l’exécution quand aucune source n’a pu être lue.any_unparsed_is_failedfait échouer l’exécution dès la première source qu’aucun plugin n’a pu lire.exportfait garder àvolant inventorychaque variable là où elle est définie, comme le fait--export.
Une source qu’aucun plugin ne lit est ignorée avec un avertissement, comme dans Ansible. -vvv affiche quel plugin a pris chaque source, et lesquels l’ont refusée.
Sources dynamiques
Section intitulée « Sources dynamiques »Un script affiche son inventaire en JSON, dans le format qu’écrit ansible-inventory --list. constructed et generator construisent des groupes et des hôtes à partir de modèles. Avec use_vars_plugins: true, constructed lit aussi ce que les plugins de vars renvoient pour les répertoires des sources lues avant lui : les fichiers group_vars et host_vars, et tout autre plugin de vars, qui passe par ansible-core. Comme dans ansible-core, un hôte d’un fichier INI n’est pas encore dans all à ce moment, donc group_vars/all.yml n’atteint pas ses expressions.
Le plugin d’inventaire d’une collection (un fournisseur cloud, par exemple) s’exécute dans ansible-core, via un processus Python que Volant ne démarre que lorsqu’une telle source est présente, voir le chemin Python préchauffé.
Réglez always_show_stderr dans [inventory_plugin_script] pour contrôler ce que devient la sortie d’erreur d’un script. Il est activé par défaut : ce qu’un script y écrit apparaît sous la forme d’une ligne [ERROR]:, même quand le script réussit.
Un inventaire INI
Section intitulée « Un inventaire INI »bastion ansible_host=198.51.100.7
[web]web1 ansible_host=192.0.2.11web2 ansible_host=192.0.2.12
[db]db1 ansible_host=192.0.2.21 ansible_user=postgres
[prod:children]webdb
[prod:vars]ansible_user=deployansible_ssh_common_args=-o ProxyJump=bastionLes commentaires commencent par # ou ;.
Le localhost implicite
Section intitulée « Le localhost implicite »Le contrôleur est un hôte sous trois noms : localhost, 127.0.0.1 et ::1. Quand l’inventaire n’en définit aucun, Volant crée un hôte implicite. Il a une connexion locale et l’interpréteur Python du contrôleur comme ansible_python_interpreter, il n’est dans aucun groupe, et all ne le désigne pas. Un play qui le nomme (hosts: localhost), un delegate_to: localhost et hostvars['localhost'] l’atteignent tous. Une boucle sur hostvars ne le liste pas.
Quand l’inventaire définit l’un des trois noms, cet hôte répond aussi aux deux autres : hosts: 127.0.0.1 s’exécute donc sur le localhost de l’inventaire, avec ses variables. Le premier défini l’emporte. Quand l’inventaire ne contient aucun hôte, Volant avertit que seul localhost est disponible. Réglez localhost_warning sur false pour le faire taire.
Variables de groupe et d’hôte
Section intitulée « Variables de groupe et d’hôte »Volant lit group_vars/ et host_vars/ à côté de chaque source, puis à côté du playbook, sous forme de fichiers (group_vars/web.yml) ou de répertoires (group_vars/web/*.yml). Priorité et facts montre où se place chaque couche.
Quand un hôte appartient à plusieurs groupes, le groupe le plus profond l’emporte. Entre groupes de même profondeur, ansible_group_priority décide (la valeur la plus haute l’emporte), puis le nom du groupe.
Un nom qui est à la fois un hôte et un groupe désigne l’hôte. Volant avertit une fois par exécution quand un inventaire contient un tel nom, quel que soit le motif utilisé, car Ansible le détecte au chargement de l’inventaire. Les variables qu’une source donne à cet hôte vont au groupe dès que le groupe existe, comme dans Ansible : chaque membre du groupe les lit donc.
Afficher un inventaire
Section intitulée « Afficher un inventaire »volant inventory --list affiche en JSON ce que Volant a lu dans les sources, et volant inventory --host NAME affiche les variables d’un hôte, les deux octet pour octet comme ansible-inventory. volant inventory --graph [GROUP] affiche l’arbre des groupes, et --vars ajoute les variables. Voir la commande inventory.
Rechargement
Section intitulée « Rechargement »meta: refresh_inventory relit toutes les sources, voir Délégation, tâches meta et environment.
Motifs d’hôtes
Section intitulée « Motifs d’hôtes »Un motif dans le hosts: d’un play ou dans --limit suit la grammaire d’Ansible :
| Motif | Sélectionne |
|---|---|
all ou * |
tous les hôtes |
web:db ou web,db |
les hôtes de l’un ou l’autre groupe |
web*, db?, host[abc], host[a-z] |
jokers de type shell sur les noms d’hôtes et de groupes |
web:&prod |
les hôtes de web qui sont aussi dans prod |
web:!web2 |
les hôtes de web sauf web2 |
~web\d+ |
les hôtes et groupes dont le nom correspond à l’expression régulière, dès son premier caractère |
web[0], web[0:2], web[1:] |
un indice ou une tranche des hôtes qu’un terme a produits |
::1, fe80::1, [::1]:22 |
un seul hôte : une adresse n’est pas coupée à ses deux-points |
Les tranches incluent leur borne de fin, comme dans Ansible : web[0:2] désigne trois hôtes. name[N-M] est accepté comme ancienne écriture de name[N:M]. Un terme ~ qui n’est pas une expression régulière valide arrête l’exécution, comme dans ansible-core.
Comment un motif est découpé en termes :
| Motif | Termes |
|---|---|
Contient une virgule, comme web:db,cache |
Coupé aux virgules seulement : web:db et cache. |
| Pas de virgule, et une adresse valide, un nom d’hôte avec un port, ou une plage | Un seul terme. |
| Pas de virgule, tout autre cas | Coupé aux deux-points. |
Les termes ne sont pas appliqués dans l’ordre où vous les écrivez. Les termes simples viennent d’abord, puis les termes &, puis les termes !, comme le fait Ansible. Un motif composé uniquement de termes ! ou & part de all.
--limit suit la même grammaire. Chaque terme qui ne correspond à aucun hôte affiche Could not match supplied host pattern, ignoring: <term> et l’exécution garde les hôtes que les autres termes ont trouvés. Une limite qui ne correspond à aucun hôte fait échouer l’exécution avec Specified inventory, host pattern and/or --limit leaves us with no hosts to target. et le code de sortie 1.
Le cache de facts
Section intitulée « Le cache de facts »Par défaut, les facts vivent en mémoire et disparaissent à la fin de l’exécution. Avec fact_caching = jsonfile, Volant écrit les facts de chaque hôte dans un fichier et les relit à l’exécution suivante, dans le format de fichier qu’utilise ansible-core 2.19. Un cache écrit par un outil est lu par l’autre.
[defaults]gathering = smartfact_caching = jsonfilefact_caching_connection = /var/cache/volant/factsfact_caching_timeout = 3600Paramètres du cache de facts
Section intitulée « Paramètres du cache de facts »| Paramètre | Variable d’environnement | Signification |
|---|---|---|
fact_caching |
ANSIBLE_CACHE_PLUGIN |
memory (la valeur par défaut, par exécution), jsonfile ou un plugin Python. ansible.builtin.memory et ansible.builtin.jsonfile fonctionnent aussi. |
fact_caching_connection |
ANSIBLE_CACHE_PLUGIN_CONNECTION |
Le répertoire qui contient les fichiers. jsonfile en a besoin ; sans lui, l’exécution garde les facts en mémoire. |
fact_caching_timeout |
ANSIBLE_CACHE_PLUGIN_TIMEOUT |
Nombre de secondes pendant lesquelles un fichier reste frais. 86400 par défaut. 0 n’expire jamais. |
fact_caching_prefix |
ANSIBLE_CACHE_PLUGIN_PREFIX |
Placé devant le nom de chaque fichier. Vide par défaut. |
gathering |
ANSIBLE_GATHERING |
implicit (par défaut), explicit ou smart. |
Chaque hôte a un fichier, nommé <prefix>s1_<host>.
Tout autre nom, comme un plugin dans cache_plugins/ ou d’une collection, se charge par l’ansible-core du contrôleur, qui lit les options du plugin lui-même. Un plugin qu’il ne peut pas charger affiche un avertissement comme [WARNING]: Unable to load the cache plugin '<name>'. et l’exécution garde les facts en mémoire.
Collecte
Section intitulée « Collecte »implicitcollecte les facts dans chaque play qui ne la désactive pas.explicitne collecte que dans les plays qui définissentgather_facts: true.smartne collecte que pour les hôtes qui n’ont aucune entrée fraîche dans le cache.
Les facts en cache sont chargés au début de l’exécution : les tâches les voient donc même quand un play ne collecte pas.
set_fact
Section intitulée « set_fact »set_fact avec cacheable: true écrit aussi la valeur dans l’entrée de cache de l’hôte, et l’exécution suivante la relit.
--flush-cache supprime les entrées des hôtes de l’inventaire avant l’exécution. Les fichiers des autres hôtes restent.
Erreurs du cache de facts
Section intitulée « Erreurs du cache de facts »Un répertoire de cache qui ne peut pas être créé, ou un fact_caching_connection manquant (Required config '_uri' for 'jsonfile' cache plugin not provided.), produit un avertissement et l’exécution continue avec le cache en mémoire. Un fichier qui n’est pas du JSON valide est supprimé et arrête l’exécution, avec le message d’ansible-core : The cache file <path> was corrupt, or did not otherwise contain valid data. It has been removed, so you can re-run your command now.