Types collections Ansible : listes, dictionnaires, structures imbriquées

Au-delà des types simples (string, int, bool), les playbooks Ansible manipulent essentiellement deux structures complexes : les listes et les dictionnaires. Et le plus souvent, des listes de dictionnaires ou des dicts imbriqués, par exemple une liste de services avec chacun son nom, son port, ses tags. Cette page couvre la déclaration YAML de ces structures, les deux notations d'accès (var.key vs var['key']), et les boucles avec filtrage via selectattr: et map(attribute=...).

Maîtriser ces structures permet d'écrire des playbooks paramétrés : un seul play qui déploie 3 services en bouclant sur une liste de dicts, plutôt que 3 plays quasi-identiques.

# Liste simple
packages:
  - vim-enhanced
  - htop
  - tree

# Liste de dictionnaires (très utilisé)
services:
  - { name: nginx,    port: 80,   enabled: true }
  - { name: mariadb,  port: 3306, enabled: true }
  - { name: telegraf, port: 9273, enabled: false }

# Dict imbriqué
app_config:
  database:
    host: db1.lab
    port: 3306
    user: myapp
  cache:
    host: redis1.lab
    port: 6379

# Boucler sur une liste de dicts (filtrage avec selectattr)
- name: Démarrer les services activés
  ansible.builtin.systemd_service:
    name: "{{ item.name }}"
    state: started
    enabled: true
  loop: "{{ services | selectattr('enabled') | list }}"
  loop_control:
    label: "{{ item.name }}"
  become: true

Sécurité non négociable :

Notation .key préférée (app_config.database.host) à ['key'] quand les clés sont des identifiants Python valides, plus lisible. La forme ['key'] reste obligatoire pour les clés avec espaces ou caractères spéciaux.
loop_control.label: mandatory sur les boucles complexes, sinon la sortie Ansible affiche le dict complet (illisible, leak de secrets potentiel si on boucle sur des credentials).
selectattr('enabled') + list, pattern idiomatique pour filtrer une liste de dicts. Attention : sur des dicts hétérogènes (toutes les clés ne sont pas définies partout), utiliser selectattr('enabled', 'defined') pour éviter les erreurs.
Ne jamais inliner un secret dans un dict de variables versionné, toujours via Vault ou un lookup.

Ce que vous allez apprendre

Déclarer une liste de dicts en YAML (deux formats équivalents)
Accéder aux clés : var.key (notation pointée) et var['key'] (bracket)
Boucler sur une liste de dicts avec loop: et loop_control: label:
Filtrer une liste sur la valeur d'une clé avec selectattr('attr', 'equalto', 'value')
Extraire un champ avec map(attribute='name') + join

Prérequis

Avoir lu Variables, déclaration et portées ;
Connaître les bases YAML (cf. YAML pour Ansible).

Listes : deux formats YAML équivalents

# Format multi-ligne avec tirets (lisible, recommandé)
webservers:
  - web1.lab
  - web2.lab
  - web3.lab

# Format compact (flow style)
webservers: [web1.lab, web2.lab, web3.lab]

Les deux représentations sont strictement équivalentes. Le format multi-ligne est préféré pour la lisibilité dès que la liste dépasse 3-4 éléments ou contient des dicts.

Dictionnaires

# Format multi-ligne (recommandé)
nginx:
  port: 80
  workers: 4
  enabled: true

# Format compact
nginx: { port: 80, workers: 4, enabled: true }

Idem : équivalents, mais le multi-ligne s'impose dès qu'une valeur est elle-même complexe.

Structures imbriquées : listes de dicts

C'est la structure la plus courante en Ansible. Une variable services qui décrit une liste de services, chacun étant un dict :

services:
  - name: api
    port: 8080
    tier: production
  - name: web
    port: 80
    tier: staging
  - name: cache
    port: 6379
    tier: production
  - name: dev-db
    port: 5432
    tier: dev

Format compact équivalent :

services:
  - { name: api, port: 8080, tier: production }
  - { name: web, port: 80, tier: staging }
  - { name: cache, port: 6379, tier: production }
  - { name: dev-db, port: 5432, tier: dev }

Ce format compact est utile pour les listes courtes où on veut voir tous les éléments rapidement. Au-delà de ~10 dicts, repassez en multi-ligne.

Accès aux clés : `var.key` vs `var['key']`

Deux syntaxes équivalentes pour accéder à une clé :

{{ nginx.port }}        ← notation pointée (recommandée si lisible)
{{ nginx['port'] }}     ← notation bracket (Python-style)

Quand préférer l'une ou l'autre ?

Situation	Préférer
Clé simple, identifiant Python valide (`port`, `name`)	`var.port` (lisible)
Clé contenant un caractère spécial (`my-key`, `1.0`)	`var['my-key']`
Clé issue d'une variable (`{{ vars[my_key_name] }}`)	`var[my_key_name]`
Clé qui peut être absente	`var.get('key', default)` ou `var.key

Piège : var.items est ambigu, items est aussi une méthode Python sur les dicts. Pour itérer sur les paires clé/valeur d'un dict, utilisez var.items() ou, plus propre en Ansible, le filtre dict2items (voir plus bas).

Boucler sur une liste

Le mot-clé loop: itère sur une liste. Chaque itération expose la variable item :

- name: Poser un marqueur pour chaque service activé
  ansible.builtin.copy:
    dest: "/tmp/service-{{ item.name }}.txt"
    content: "service {{ item.name }} sur le port {{ item.port }}\n"
    mode: "0644"
  loop: "{{ services }}"
  loop_control:
    label: "{{ item.name }}"      # affiche "api" plutôt que tout le dict
  when: item.tier == "production" # filtre par tier

Le loop_control.label: rend la sortie console lisible, sans lui, vous voyez le dict complet répété. Le when: filtre les itérations.

Filtrer une liste avec `selectattr`

Quand vous voulez filtrer côté Jinja2 (sans when: au niveau task), le filtre selectattr est l'outil :

- name: Liste filtrée des services production
  ansible.builtin.debug:
    msg: "{{ services | selectattr('tier', 'equalto', 'production') | list }}"

Sortie :

[
  {"name": "api", "port": 8080, "tier": "production"},
  {"name": "cache", "port": 6379, "tier": "production"}
]

Combiné avec map(attribute='name') pour extraire un champ :

{{ services
   | selectattr('tier', 'equalto', 'production')
   | map(attribute='name')
   | list }}

Sortie : ['api', 'cache'].

Et avec join pour concaténer :

{{ services | map(attribute='name') | join(',') }}

Sortie : 'api,web,cache,dev-db'.

Cas pratique, fichier filtré (lab `ecrire-code/types-collections`)

Voici l'exemple validé sur le lab 13-ecrire-code-types-collections qui combine tout :

---
- name: Challenge types-collections selectattr
  hosts: db1.lab
  become: true

  vars:
    services:
      - { name: api, port: 8080, tier: production }
      - { name: web, port: 80, tier: staging }
      - { name: cache, port: 6379, tier: production }
      - { name: dev-db, port: 5432, tier: dev }

  tasks:
    - name: Poser un fichier filtré sur tier=production
      ansible.builtin.copy:
        dest: /tmp/services-production.txt
        content: |
          {% for s in services | selectattr('tier', 'equalto', 'production') %}
          {{ s.name }}:{{ s.port }}
          {% endfor %}
        mode: "0644"

Le contenu posé sur db1.lab est :

api:8080
cache:6379

Les services web (staging) et dev-db (dev) sont exclus, c'est le rôle de selectattr.

Boucler sur un dict (clé/valeur) avec `dict2items`

Pour itérer sur les paires clé/valeur d'un dict, le filtre dict2items transforme un dict en liste de {key, value} :

vars:
  ports_by_service:
    nginx: 80
    redis: 6379
    postgres: 5432

tasks:
  - name: Lister les ports
    ansible.builtin.debug:
      msg: "{{ item.key }} sur le port {{ item.value }}"
    loop: "{{ ports_by_service | dict2items }}"

Sortie :

"msg": "nginx sur le port 80"
"msg": "redis sur le port 6379"
"msg": "postgres sur le port 5432"

Le filtre inverse (items2dict) reconstruit un dict depuis une liste de {key, value}.

Pièges fréquents

Symptôme	Cause	Fix
`'dict object' has no attribute 'name'`	La clé n'existe pas dans certains items	Utiliser `item.name
`selectattr('tier', 'equalto', 'production')` ne filtre rien	`equalto` est sensible au type (string vs int)	Vérifier que `tier` est bien une string en YAML, pas une enum
Loop affiche le dict complet à chaque itération	`loop_control.label:` manquant	Ajouter `label: "{{ item.name }}"`
`var.items` retourne la méthode Python	Conflit avec `items` méthode dict	Utiliser `var['items']` (bracket) ou renommer la clé
Tableau imbriqué difficile à parcourir (e.g. `services[].tags[]`)	Boucle imbriquée requise	Utiliser `with_subelements:` ou aplatir avec `flatten`

À retenir

Le YAML accepte deux formats pour listes/dicts (multi-ligne et compact), préférer le multi-ligne dès 3-4 éléments.
var.key et var['key'] sont équivalents ; utiliser bracket pour les clés contenant des caractères spéciaux ou variables.
loop: est la forme moderne (RHCE 2026) ; with_items: est legacy.
loop_control.label: rend la sortie console lisible quand on boucle sur des dicts.
selectattr('attr', 'equalto', 'value') filtre une liste de dicts ; map(attribute='name') extrait un champ.
dict2items transforme un dict en liste de {key, value} pour itérer sur les paires.

Pratiquer dans le lab

Cette page a un lab d'accompagnement : labs/ecrire-code/types-collections/ dans stephrobert/ansible-training. Il contient un README.md guidé, un Makefile (make verify lance les tests), et un challenge final auto-évalué : filtrer une liste de dicts avec selectattr('tier', 'equalto', 'production').

Une fois le lab provisionné :

cd ~/Projets/ansible-training/labs/ecrire-code/types-collections/

cat README.md           # tuto pas à pas
cat challenge/README.md # consigne du challenge final
pytest -v challenge/tests/   # lancer les tests testinfra

Si les tests passent, vous maîtrisez les concepts couverts dans ce guide. En cas de blocage, docs/troubleshooting.md à la racine du repo couvre les pièges fréquents (rate-limit SSH, clé absente, collection manquante).

Prochaines étapes

Facts et magic vars ansible_facts.*, gather_facts, gather_subset, magic vars (inventory_hostname, groups, hostvars)

Précédence des variables (RHCE) Les 22 niveaux officiels Ansible, objectif explicite RHCE EX294

Filtres Jinja2 essentiels default, regex_replace, dict2items, combine, selectattr, map, unique en profondeur