Introduction aux modèles Jinja2

1. Théorie

Modèles

  • Ansible intègre nativement le “template engine” Jinja2 (un logiciel qui met en forme des données)
  • Les modèles de données sont transformés en configuration de périphériques
  • Les sorties des périphériques peuvent être transformées en documentation

Jinja2 permet aux utilisateurs de manipuler des variables, d’y appliquer une logique conditionnelle et répétitive et donc d’étendre la programmabilté dans l’automation du réseau.

schéma illustrant un template engine

Source de l’image : TempEngGen015.svg

Utiliser des modèles pour générer une configuration

Un modèle de données en YAML :

vlans:
  - id: 10
    name: WEB
  - id: 20
    name: APP
  - id: 30
    name: DB

Un modèle Jinja2 :

vlan {{ vlan.id }}
  name {{ vlan.name }}

On lie les deux dans une tâche :

- name: RENDER THE VLAN CONFIGURATION
  template:
    src: vlans.j2
    dest: "vlan_configs/{{ inventory_hostname }}.conf"

Voici le résultat venant pour l’hôte “leaf1” dans un fichier leaf1.conf :

vlan 10
  name WEB
vlan 20
  name APP
vlan 30
  name DB

Utiliser des modèles pour la documentation dynamique

Un modèle Jinja2 qui fabrique un fichier Markdown ou HTML :

{{ inventory_hostname.upper() }}
---
{{ ansible_net_serialnum }} : {{ ansible_net_version }}

Le rendu HTML :

RTR1
---
9YJXS2VD3Q7 : 16.08.01a
RTR2
---
9QHUCH0VZI9 : 16.08.01a
RTR3
---
9ZGJ5B1DL14 : 16.08.01a
RTR4
---
9TCM27U9TQG : 16.08.01a
  • Générer un documentation toujours à jour
  • Construire des rapports de diagnostic
  • Utiliser les mêmes données pour générer des rapports exécutif et techniques

Assembler les données

Le module Ansible assemble permet de fabriquer un fichier consolidé à partir de fragments combinés. C’est une stratégie habituelle pour concaténer des blocs de texte dans un document final.

    - name: CONSOLIDATE THE IOS DATA
      assemble:
        src: reports/
        dest: network_os_report.md
      delegate_to: localhost
      run_once: yes
RTR1
---
9YJXS2VD3Q7 : 16.08.01a

RTR2
---
9QHUCH0VZI9 : 16.08.01a

RTR3
---
9ZGJ5B1DL14 : 16.08.01a
RTR4
---
9TCM27U9TQG : 16.08.01a

2. Lab Introduction aux modèles Jinja2

De manière générale, quand on pense à l’automation du réseau, on pense à la gestion des configurations (“configuration management”) des périphériques. Dans ce lab, vous apprendrez comment utiliser Ansible comme outil de génération en temps réel et dynamique de votre documentation.

Le principe est de créer des rapports et des documents à partir des mêmes sources de données pour des publics distinct comme les ingénieurs ou le Management.

Jinja2 est un puissant “templating engine”, un processeur de modèles, pour Python. Jinja2 permet de manipuler des variables et d’implémenter des constructions logiques. Avec le module Ansible template, l’“admin” dispose d’un outil puissant pour créer des rapports dynamiques.

Dans ce lab, vous apprendrez à utiliser le module Ansible template pour passer des données collectées auprès des périphériques dans un modèle Jinja2. Le fichier rendu est un fichier Markdown (à convertir, à afficher sur une page GitHub, pour nourrir un générateur de site statique comme Jekyll ou Hugo, …)

Étape 1

Veuillez créer un nouveau livre de jeu router_report.yml avec une définition de jeu comme celle-ci :

---
- name: GENERATE OS REPORT FROM ROUTERS
  hosts: cisco
  connection: network_cli
  gather_facts: no

Étape 2

Veuillez ajouter une tâche que nous avons déjà précédemment utilisée qui invoque le module Ansible ios_facts.

---
- name: GENERATE OS REPORT FROM ROUTERS
  hosts: cisco
  connection: network_cli
  gather_facts: no

  tasks:
    - name: GATHER ROUTER FACTS
      ios_facts:

Veuillez vous souvenir que le module ios_facts peuple les variables ansible_net_version et ansible_net_serial_number dans le jeu. Vous pouvez le constater en lançant le livre de jeu en mode verbeux.

Étape 3

Plutôt que d’utiliser debug ou la verbosité pour afficher les informations voulues, ajoutons une tâche qui utilise le module Ansible template.

---
- name: GENERATE OS REPORT FROM ROUTERS
  hosts: cisco
  connection: network_cli
  gather_facts: no

  tasks:
    - name: GATHER ROUTER FACTS
      ios_facts:

    - name: RENDER FACTS AS A REPORT
      template:
        src: os_report.j2
        dest: reports/{{ inventory_hostname }}.md

Le module Ansible template trouve ici deux arguments : src: qui indique le modèle Jinja2 qui sera créé dans une étape suivante et dest: qui indique l’emplacement des fichiers générés à parir du modèle.

Étape 4

Des l’étape précédente, nous avons indiquer qu’il fallait générer le rapports dans un dossier reports/. Voici la commande pour créer ce dossier.

mkdir reports

Étape 5

La prochaine étape consiste à créer le modèle Jinja2. Ansible lira le fichier de modèle Jinja2 qui est situé à l’emplacement du dossier de travail courant ou dans un dossier templates/ par convention. La bonne pratique “par convention” demanderait que l’on place le modèle dans un dossier templates/.

Veuillez maintenant créer un fichier nommé os_report.j2 dans le dossier templates.

mkdir templates
vi templates/os_report.j2

Son contenu devrait ressembler à ceci.

{{ inventory_hostname.upper() }}
---

{{ ansible_net_serialnum }} : {{ ansible_net_version }}

Ce fichier désigne simplement quelques unes des variables des livres des jeu précédents.

Note: les méthodes intégrées en Python pour les types de données sont disponibles nativement dans Jinja2, ce qui permet de manipuler très facilement le formatage …

Étape 6

Dès que tout est en place, nous pouvons lancer notre livre de jeu.

ansible-playbook router_report.yml
PLAY [GENERATE OS REPORT FROM ROUTERS] ******************************************************************************************************************************************************

TASK [GATHER ROUTER FACTS] ******************************************************************************************************************************************************************
ok: [rtr4]
ok: [rtr3]
ok: [rtr2]
ok: [rtr1]

TASK [RENDER FACTS AS A REPORT] *************************************************************************************************************************************************************
changed: [rtr4]
changed: [rtr2]
changed: [rtr3]
changed: [rtr1]

PLAY RECAP **********************************************************************************************************************************************************************************
rtr1                       : ok=2    changed=1    unreachable=0    failed=0
rtr2                       : ok=2    changed=1    unreachable=0    failed=0
rtr3                       : ok=2    changed=1    unreachable=0    failed=0
rtr4                       : ok=2    changed=1    unreachable=0    failed=0

Étape 7

Après avoir exécuté ce livre de jeu, on devrait trouver des fichiers dans le dossier reports/.

reports/
├── rtr1.md
├── rtr2.md
├── rtr3.md
└── rtr4.md

0 directories, 4 files

Voyons le contenu de l’un d’eux :

cat reports/rtr4.md
RTR4
---
9TCM27U9TQG : 16.08.01a

Étape 8

La suite est de disposer d’une vue unifiée des informations collectées pour chaque routeur.

Veuillez ajouter une tâche qui utilise le module Ansible assemble.

---
- name: GENERATE OS REPORT FROM ROUTERS
  hosts: cisco
  connection: network_cli
  gather_facts: no

  tasks:
    - name: GATHER ROUTER FACTS
      ios_facts:

    - name: RENDER FACTS AS A REPORT
      template:
        src: os_report.j2
        dest: reports/{{ inventory_hostname }}.md

    - name: CONSOLIDATE THE IOS DATA
      assemble:
        src: reports/
        dest: network_os_report.md
      delegate_to: localhost
      run_once: yes

Le module Ansible assemble dispose de deux paramètres : src qui indique le dossier dans lequel se situent les fichiers à assembler et dest qui indique le nom du fichier assemblé.

Note: La directive de tâche delegate_to: localhost indique que la tâche sera exécutée localement pour l’hôte à gérer.

Note : La directive de tâche run_once fera en sorte que la tâche ne soit exécutée qu’une seule fois.

Étape 9

Veuillez exécuter le livre de jeu.

ansible-playbook router_report.yml
PLAY [GENERATE OS REPORT FROM ROUTERS] ******************************************************************************************************************************************************

TASK [GATHER ROUTER FACTS] ******************************************************************************************************************************************************************
ok: [rtr2]
ok: [rtr4]
ok: [rtr1]
ok: [rtr3]

TASK [RENDER FACTS AS A REPORT] *************************************************************************************************************************************************************
ok: [rtr3]
ok: [rtr2]
ok: [rtr1]
ok: [rtr4]

TASK [CONSOLIDATE THE IOS DATA] *************************************************************************************************************************************************************
changed: [rtr1 -> localhost]

PLAY RECAP **********************************************************************************************************************************************************************************
rtr1                       : ok=3    changed=1    unreachable=0    failed=0
rtr2                       : ok=2    changed=0    unreachable=0    failed=0
rtr3                       : ok=2    changed=0    unreachable=0    failed=0
rtr4                       : ok=2    changed=0    unreachable=0    failed=0

Étape 10

Un nouveau fichier nommé network_os_report.md est désormais disponible à l’emplacement du livre de jeu. La commande cat permet de vérifier son contenu.

cat network_os_report.md


RTR1
---
9YJXS2VD3Q7 : 16.08.01a



RTR2
---
9QHUCH0VZI9 : 16.08.01a



RTR3
---
9ZGJ5B1DL14 : 16.08.01a



RTR4
---
9TCM27U9TQG : 16.08.01a

Étape 11

Les fichiers Markdown peuvent être rendu en HTML avec python-markdown. Par exemple :

yum -y install python-markdown
python -m markdown network_os_report.md > index.html

Et ils peuvent être servis facilement en HTTP.

python -m SimpleHTTPServer

Conclusion

Avec seulement trois petites tâches, vous pouvez disposer d’un rapport sur les OS de vos périphériques du réseau. Ceci est un simple exemple qui mériterait d’être exploité. Par exemple, on pourrait imaginer un tableau de bord qui rapporte le résultat de commandes show exécutées sur les périphériques.

Ansible fournit les outils et les méthodes permettant d’étendre l’automatisation du réseau au-delà de la gestion de la configuration vers des fonctionnalités telles que la génération de documentation et/ou de rapports.

Licence

License MIT github.com/network-automation/linklight