Add documentation about molecule and Gitlab CI to the README

parent bb2b3199
......@@ -143,6 +143,101 @@ $ pip2 install --user ansible-roles-graph
$ ansible-roles-graph -o doc/ansible-role-dependencies.png roles/
```
## Automatisation des tests avec molecule
molecule est un outil qui permet de vérifier et tester des rôles et playbooks
Ansible.
* Voir la documentation officielle (un peu brute pour débuter cependant) :
https://molecule.readthedocs.io/en/latest/
* Un très bon article (à peu près à jour) pour bien démarrer :
https://www.jeffgeerling.com/blog/2018/testing-your-ansible-roles-molecule
On utilise molecule pour vérifier la conformité des fichiers YAML (yamllint
puis ansible-lint) et exécuter le rôle dans un conteneur Docker vierge (2 fois,
pour le test d'idempotence). molecule permet également de mener des tests
croisés avec différentes version de Ansible, Python et de distributions cibles,
ainsi que de faire appel à des outils de vérification tel que Goss, Inspec et
Testinfra, mais on ne les utilise pas (encore).
Il n'est pas indispensable de l'installer mais fortement recommandé pour aider
au développement. Il est également conseillé de tester ses modifications en
local avant de les pousser sur Gitlab.
### Installation
```
$ pip install --user molecule docker
```
Vous devez également avoir Docker installé sur votre système.
### Utilisation
`molecule` doit toujours être exécuter en étant dans le répertoire du rôle
(contenant le répertoire _molecule/_ :
```
$ cd roles/<rôle>/
```
* Vérifier la syntaxe avec yamllint et ansible-lint :
```
$ molecule lint
```
* Tester le rôle dans un conteneur :
```
$ molecule converge
```
molecule va partir un nouveau conteneur ou réutiliser le précédent s'il n'a pas
été supprimé. On peut se connecter au conteneur pour vérifier manuellement ce
qui a été fait :
```
$ molecule login
```
molecule exécute le playbook *molecule/default/playbook.yml* qui, par défaut,
applique le rôle en question, mais on peut le modifier pour rajouter des
dépendances ou définir des variables.
* Tester uniquement un tag (on peut passer n'importe quelle option de
`ansible-playbooks`) :
```
$ molecule converge -- --tags foo
```
* Rouler toute la suite de tests :
```
$ molecule test
```
La sous-commande `test` va faire appel aux autres sous-commandes de molecule
pour vérifier la syntaxe du rôle, démarrer un conteneur, exécuter le rôle,
vérifier l'idempotence, vérifier la conformité du système après exécution, puis
détruire le conteneur.
## Automatisation avec Gitlab CI
Tous les rôles n'ont pas encore leurs tests molecule, mais ceux qui les ont un
job Gitlab CI pour les exécuter automatiquement.
Ils sont définit dans le fichier *.gitlab-ci.yml* à la racine du dépôt.
Pour tester le .gitlab-ci.yml en local :
```
$ gitlab-runner exec docker <nom du job>
```
(le paquet _gitlab-runner_ doit bien sûr être installé au préalable sur sa machine).
## Licence
Les rôles et playbooks Ansible de ce dépôt sont publiés sont la licence GPL v3.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment