diff --git a/infrastructure/outils/ansible.md b/infrastructure/outils/ansible.md new file mode 100644 index 0000000..9b59e41 --- /dev/null +++ b/infrastructure/outils/ansible.md @@ -0,0 +1,219 @@ +# Ansible + +Ansible est un moyen de créer des configurations de serveur et de les déployer. +Il permet ainsi l'accélération du déploiement de certains services et de +permettre de les réinstaller en cas de problèmes. + +Cette documentation n'étant pas exhaustive, il sera nécessaire de faire des +tours dans les dossiers d'ansible et dans la +[documentation officielle](https://docs.ansible.com/ansible/latest/index.html) +d'ansible. + +## Prérequis + +La configuration d'ansible du crans nécessite un certain nombre de prérequis. + +### Installation d'Ansible + +Pour utiliser l'[Ansible du crans](https://gitlab.crans.org/nounous/ansible), +il faut installer Ansible sur votre machine personnelle. Il est possible de le +faire avec la commande : + +```bash +sudo apt install ansible +``` + +Ou équivalent pour les autres gestionnaires de paquets + +### Accès au LDAP + +Pour faciliter le déploiement, il est possible (et nécessaire) d'utiliser le +ldap pour configurer les machines. Ceci nécessite l'installation du paquet +python correspondant + +```bash +sudo apt install python3-ldap +``` + +Ou équivalent pour les autres gestionnaires de paquets. + +Ensuite, il faut donner l'accès au ldap à votre machine avec la commande : + +```bash +ssh -L 1636:wall-e.adm.crans.org:636 wall-e.adm.crans.org +``` + +### Accès au pass + +Certains fichiers de configuration contiennent des secrets. Ceux-ci sont alors +dans le pass du crans. Il est donc nécessaire d'installer le pass du crans +comme indiqué sur le git. + +## Création d'un fichier de configuration + +### Architecture + +Pour bien comprendre comment configurer ansible, il faut d'abord comprendre +l'architecture du git +[Ansible du crans](https://gitlab.crans.org/nounous/ansible) : + +- `hosts` : est un fichier qui contient les machines et qui les regroupent en + groupe. Cela permet d'exécuter les configurations correspondantes au groupe + de la machine directement. +- `all.yml` : est juste un fichier contenant tous les playbook déjà configurés. + En particulier, il permet de ré-executé toutes les configurations. +- `group_vars` : est un dossier qui contient les variables utiles pour + exécuter une configuration d'un groupe donné +- `host_vars` : est un dossier contenant les variables qui sont spécifiques à + chaque machine. Par exemple, la configuration réseau. +- `plays` : est un dossier qui contient le pont entre tout les éléments déjà + mentionnés. Il s'agit du fichier que l'on va exécuter. Il contient le (ou + les) groupe qui va être concerné par son exécution. Il va aussi dire + qu'elles seront les rôles à exécuter mais aussi définir de potentielles + variables. +- `roles` : il s'agit du dossier qui contient l'ensemble des fichiers de + configurations ainsi que les commandes à exécuter. + +:bulb: Pour utiliser des variable de groupe, il faut que la machine soit dans +le groupe correspondant dans `hosts` + +### Configuration basique + +Pour commencer, il va falloir ajouter une configuration qui ne dépend pas (ou +presque) de la machine. Il s'agit du playbook `root`. Celui-ci contient toutes +les instructions pour initialiser les éléments essentiels d'une machinei au +crans. Par exemple, les backups, le monitoring, le ssh ou encore les nounous. + +Pour ajouter cette configuration il suffit de suivre les étapes suivantes : + +- ajouter la machine dans `hosts`, dans la catégorie `crans_vm` s'il s'agit + d'une vm. +- ajouter la configuration réseau dans `host_vars` (dans un fichier du même nom + que la machine). + +Voici une configuration possible issue de la vm voyager : + +```yaml +--- +interfaces: + adm: ens18 + srv_nat: ens19 + +loc_unattended: + automatic_reboot: true + +loc_needrestart: + override: [] +``` + +C'est bon la configuration est prête ! Il faut dès lors la déployer. Pour cela, +vous devez exécuter la commande : + +```bash +plays/root.yml -l [machine à déployer].adm.crans.org --check +``` + +ATTENTION : + +- Le `--check` sert à vérifier que la configuration fonctionne et donc + n'effectue aucune modification. De manière général, il est préférable de + vérifier le fonctionnement de la configuration avant de la déployer. + Cependant, et comme on peut le constater dans le playbook root, des erreurs + peuvent avoir lieu bien que la configuration fonctionne. Cela vient du fait + que certains fichiers de configuration ont besoin d'un paquet qui doit être + installer au préalable pour être écrit. +- Si la machine que vous cherchez à déployer est fraîchement installer, la + procédure change légèrement car vous n'avez pas encore de compte sur la + machine. Il est alors nécessaire de faire un tour sur la + [documentation appropriée](https://gitlab.crans.org/nounous/documentation/howto/creer_vm_crans.md). + +### Configuration du service + +Le machine que vous déployez aura, a priori, une configuration qui lui sera +propre car lié à un service spécifique qu'elle hébergera. Pour cela, il est +nécessaire de créer votre propre configuration. Pour cela, il convient de +suivre les étapes suivantes : + +- ajoutez la machine aux groupes appropriés +- Si besoin : créer un groupe dans `hosts` contenant le machine. +- (facultatif) Si vous avez créer un nouveau groupe : créer un fichier dans + `group_vars`. contenant les variables qui seront à utiliser dans la + configuration. ATTENTION : ce fichier devra avoir le même nom que le groupe + précédemment défini. +- Si vous avez besoin de secrets : créer dans le pass un fichier dans + `crans/ansible` contenant les secrets qui seront utilisés dans la + configuration +- créer un fichier dans `plays` contenant a minima : + - une entête disant comment exécuter le fichier + (`#!/usr/bin/env ansible-playbook`) (suivi de `---`) + - le groupe sur lequel il s'exécute (`hosts:`) + - les rôles à exécuter (`roles:`) +- écrire le rôles à exécuter + +Ce dernier point mérite de s'y attarder. + +Pour créer un rôle, il faut créer un dossier (le rôle) contenant un autre +dossier minimum : `tasks`. Ce dernier contiendra les fichiers qui exécuteront +les commandes. Pour écrire ces fichiers, vous pourrez vous aidez de la +[documentation d'Ansible](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/). +Si vous avez besoin d'effectuer une tâche qui n'est pas prise en charge par le +module par défaut d'Ansible, il est possible d'utiliser d'autres collections +présentent sur cette +[documentation](https://docs.ansible.com/ansible/latest/collections/). Il sera +alors nécessaire d'installer ces paquets selon la procédure décrite dans la +documentation. + +Cependant, dans les rôles, vous serez amené⋅e à écrire des fichiers complets. +Ceci seront contenu dans le dossier `templates`. Celui-ci pourra contenir des +variables du groupe prédéfini (`{{ fichier.variable }}`) ou des secrets +(`{{ vault.fichier.variable }}`). Pour la clarté, ces fichiers auront le même +chemin dans `templates` que sur la machine une fois déployée. Il est aussi +possible de faire des boucles avec la syntaxe : + +```jinja +{% for variable in liste %} + +... + +{% endfor %} +``` + +Pour plus d'information sur la syntaxe des templates, référez vous à la +[documentation de jinja](https://jinja.palletsprojects.com/en/3.1.x/templates/) + +Enfin, lors de la configuration, il peut-être nécessaire d'exécuter des +opérations qui auront lieux UNIQUEMENT en cas de changement. Ceci seront dans +le dossier `handlers`. Par exemple, redémarrer nginx après modification des +fichiers de configuration. Pour plus d'information sur les handlers, vous +pouvez jeter un œil sur cette +[documentation](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_handlers.html). + +Voici un bref récapitulatif de la structure d'un dossier de roles : + +```bash +roles/[service]/ +├── handlers +│   └── main.yml +├── tasks +│   └── main.yml +└── templates + └── [des templates] +``` + +Ces propos sont très abstraits et probablement peu limpides. Si vous êtes dans +ce cas, regardez un fichier de configuration quelconque en même temps pour vous +familiarisez avec la structure et le fonctionnement ainsi que la syntaxe. +Cependant, vous devriez avoir les clés pour comprendre les fichiers de +configuration ! + +### Configurer le reverseproxy + +Si votre service nécessite de recevoir une connexion depuis l'extérieur, il +faut alors dire que l'on souhaite en recevoir. Ceci passe alors par Hodaur (le +reverseproxy). Pour cela il suffit de : + +- ajouter dans `group_vars/reverseproxy.yml` le site dont il est question + dans la catégorie `reverseproxy_sites`. Voici un exemple de ce qu'il faut + ajouter `- {from: helloworld.crans.org, to: 172.16.10.131}` +- exécuter le playbook reverseproxy + (`plays/reverseproxy -l hodaur.adm.crans.org --check`)