Foxency
Administration Système et Infrastructure

Documentation technique et automatisation de l'administration réseau

Un réseau bien documenté se dépanne plus vite et s'automatise plus facilement. Schémas, plan d'adressage, source de vérité, modèles de configuration et Ansible : une démarche progressive et réaliste.

Par Rédaction Foxency Publié le 5 min de lecture

Source de vérité alimentant des modèles de configuration déployés automatiquement sur les équipements réseau

La documentation réseau est souvent perçue comme une corvée qui vieillit dès sa rédaction. L'automatisation, de son côté, paraît réservée aux grandes équipes. Les deux sont pourtant intimement liées : on ne peut automatiser de façon fiable que ce que l'on a décrit, et une documentation générée ou vérifiée automatiquement reste à jour.

Objectif : définir le contenu minimal d'une documentation réseau utile, introduire la notion de source de vérité et montrer comment automatiser des tâches courantes avec Ansible. La programmation en Python est traitée dans Automatisation réseau avec Python.

Le contenu minimal d'une documentation réseau

1. Les schémas

  • Schéma physique : équipements, ports, câblage, baies, liens entre sites.
  • Schéma logique : VLAN, sous-réseaux, routage, zones de sécurité, flux principaux.

Un schéma doit indiquer sa date et sa version. Mieux vaut deux schémas simples et justes qu'un seul schéma complet et faux.

2. Le plan d'adressage

Tableau VLAN / nom / sous-réseau / passerelle / plage DHCP / usage, ainsi que la liste des adresses statiques. C'est le document le plus consulté.

3. L'inventaire

Pour chaque équipement : nom, rôle, modèle, numéro de série, version logicielle, emplacement, adresse de gestion, date de fin de support. L'inventaire permet de planifier les mises à jour et les renouvellements.

4. Les standards

  • Convention de nommage (exemple : sw-acc-par-e2-01 pour un commutateur d'accès à Paris, étage 2) ;
  • gabarits de configuration par type d'équipement ;
  • règles de numérotation des VLAN et d'adressage.

5. Les procédures

Ajout d'un VLAN, remplacement d'un commutateur, création d'un accès VPN, procédure de changement et de retour arrière. Une procédure se teste comme du code : quelqu'un d'autre que son auteur doit pouvoir la suivre.

6. Les accès et contacts

Comment accéder aux équipements (bastion, console hors bande), contacts des opérateurs et numéros de contrat, escalade. Les secrets eux-mêmes ne figurent pas dans la documentation : ils sont stockés dans un coffre-fort de mots de passe avec contrôle d'accès.

Rendre la documentation vivante

  • Un emplacement unique, connu de tous (wiki, dépôt Git avec fichiers Markdown, outil dédié).
  • La mise à jour fait partie du changement : une demande de changement n'est close que lorsque la documentation est à jour.
  • Des revues périodiques, par exemple trimestrielles, comparant documentation et réalité.
  • La génération automatique de ce qui peut l'être : inventaire à partir des équipements, configurations à partir des sauvegardes (voir Sauvegarde et restauration des configurations réseau).

La source de vérité

Une source de vérité (Source of Truth) est une base de données qui décrit l'état souhaité du réseau : sites, baies, équipements, interfaces, VLAN, préfixes IP, circuits. Des outils libres comme NetBox ou Nautobot remplissent ce rôle.

La différence est fondamentale :

  • dans l'approche traditionnelle, les équipements sont la référence et la documentation tente de les décrire ;
  • dans l'approche par source de vérité, la base décrit l'intention, et les configurations des équipements en sont dérivées.

On peut alors détecter les écarts (un équipement configuré différemment de l'intention) et générer automatiquement les configurations.

Des modèles de configuration

Plutôt que d'écrire chaque configuration à la main, on combine un modèle et des données. Le langage de gabarits Jinja2 est le plus utilisé dans l'outillage réseau.

{# modele_acces.j2 #}
hostname {{ hostname }}
{% for vlan in vlans %}
vlan {{ vlan.id }}
 name {{ vlan.nom }}
{% endfor %}
{% for port in ports_acces %}
interface {{ port.nom }}
 description {{ port.description }}
 switchport mode access
 switchport access vlan {{ port.vlan }}
 spanning-tree portfast
{% endfor %}

# donnees/sw-acc-par-e2-01.yml
hostname: sw-acc-par-e2-01
vlans:
  - { id: 10, nom: UTILISATEURS }
  - { id: 30, nom: TELEPHONIE }
ports_acces:
  - { nom: GigabitEthernet1/0/1, description: "Bureau 201", vlan: 10 }
  - { nom: GigabitEthernet1/0/2, description: "Bureau 202", vlan: 10 }

Le modèle garantit la cohérence : tous les ports d'accès reçoivent les mêmes réglages de sécurité, sans oubli.

Automatiser avec Ansible

Ansible est un outil d'automatisation sans agent : il se connecte aux équipements (SSH, API) et applique des tâches décrites en YAML. Des collections maintenues fournissent des modules pour Cisco IOS (cisco.ios), NX-OS, Arista EOS, Juniper Junos et bien d'autres.

Inventaire

# inventaire.ini
[acces_paris]
sw-acc-par-e2-01 ansible_host=10.10.99.21
sw-acc-par-e3-01 ansible_host=10.10.99.22

[acces_paris:vars]
ansible_network_os=cisco.ios.ios
ansible_connection=ansible.netcommon.network_cli
ansible_user=automatisation

Collecter des informations (lecture seule)

# collecte.yml
- name: Inventaire des versions
  hosts: acces_paris
  gather_facts: false
  tasks:
    - name: Collecter les faits
      cisco.ios.ios_facts:
        gather_subset: min
    - name: Afficher la version
      ansible.builtin.debug:
        msg: "{{ inventory_hostname }} : {{ ansible_net_version }}"

Commencer par des tâches en lecture est la meilleure façon d'adopter l'automatisation sans risque : inventaires, audits de conformité, vérifications après changement.

Appliquer une configuration de façon déclarative

- name: Garantir la présence des VLAN standard
  hosts: acces_paris
  gather_facts: false
  tasks:
    - name: VLAN
      cisco.ios.ios_vlans:
        config:
          - { vlan_id: 10, name: UTILISATEURS }
          - { vlan_id: 30, name: TELEPHONIE }
        state: merged

ansible-playbook -i inventaire.ini vlans.yml --check --diff   # simulation, affiche les différences
ansible-playbook -i inventaire.ini vlans.yml

Le mode --check --diff montre ce qui serait modifié sans rien changer : utilisez-le systématiquement avant une exécution réelle. Les modules déclaratifs sont idempotents : relancer le playbook ne modifie rien si l'état souhaité est déjà atteint.

Une adoption progressive

  1. Documenter : plan d'adressage, inventaire, schémas.
  2. Sauvegarder automatiquement les configurations.
  3. Automatiser la lecture : audits, inventaires, contrôles de conformité.
  4. Standardiser avec des modèles.
  5. Automatiser les changements simples et répétitifs (VLAN, descriptions, NTP, SNMP), avec revue et mode simulation.
  6. Introduire une source de vérité lorsque le parc et l'équipe le justifient.

Erreurs courantes

  • Documenter une fois, ne jamais mettre à jour.
  • Stocker des mots de passe dans la documentation ou dans les dépôts Git.
  • Automatiser avant de standardiser : on automatise alors le désordre.
  • Exécuter des playbooks en production sans mode simulation ni revue.
  • Donner au compte d'automatisation des droits illimités sans journalisation.

Implications de sécurité

Les outils d'automatisation détiennent des accès privilégiés à tout le réseau : protégez leurs identifiants dans un coffre (Ansible Vault ou gestionnaire de secrets), limitez leurs droits, journalisez leurs actions et contrôlez les modifications des playbooks par revue de code. Voir Contrôle d'accès et principe du moindre privilège.

Conclusion

Documentation et automatisation forment un cercle vertueux : une description fiable du réseau permet d'automatiser, et l'automatisation maintient la description à jour. Commencez petit, en lecture seule, standardisez, puis étendez. Pour programmer vos propres outils, poursuivez avec Automatisation réseau avec Python.

Références