Commit b38cdc69 authored by nono's avatar nono 💻
Browse files

Mise à jour de la documentation

parent 78d60211
# PiOps playbook
```
████████████ ████████████
███████████ ████████████████ ███████████
███████ ▄██████████████████████▄ ████████
█████ █████████████████████████████▄ █████
███ ██████████████████████████████████▄ ███
█ ██████████████████████████████████████▄ █
██████████████████████████████████████████
███████████▀ ████████
██████████▀ ████ ███████ ████████████████
▓█████████▌ █████▌ ███████ █████████████████
███████████▆▆█████▌ ███████ █████████████████
██████████████████▌ ███████ █████████████████
█████████████████▌ ████████ █████████████████
█████████████████▌ ████████ █████████████████
█████████████████ ████████ █████████████████
▐██████████████ █████████ ████████████████▌
█████████████▀ █████████ ██▌ ███████████
▐██████████▀ █████████ ▐█████████▌
▀█████████ ▄█████████▆ ▐█████████▀
█ ▀█████████▆▆██████████████▆▆▆▆▆███████▀ █
███ ▀██████████████████████████████████▀ ██
█████ ██████████████████████████████▀ ████
███████ ▀█████████████████████████▀ ██████
██████████ ██████████████████▀▀ █████████
████████████ ███████████
![Logo du dépôt PiOps](https://git.laquadrature.net/uploads/-/system/project/avatar/238/bookonscreen.jpg?width=128)
# PiOps playbook
```
> Ce dépôt contient l'ensemble des configurations des serveurs de LQDN. Cette configuration est gérée par Ansible.
Le but de ce projet est de pouvoir faciliter le travail des équipes techniques
de LQDN en développant un ensemble de recettes décrivant l'infrastructure.
### Doc ansible
Pour référence, la documentation pour la dernière version d'ansible est
[ici](https://docs.ansible.com/ansible/latest/user_guide/)
## Configuration
## Installation
Commencez par télécharger le dépôt sur votre ordinateur de contrôle. Pour cela, il vous suffit de faire :
......@@ -60,31 +30,12 @@ Assurez-vous d'avoir une connexion SSH à l'ensemble des serveurs listés dans l
Une fois le dépôt sur votre ordinateur de contrôle, vous devez choisir si vous voulez fait un test, ou une mise en production. Pour cela, voyez dans le fichier `inventory.yml` quels serveurs sont affectés au groupe production et ceux affectés au groupe test.
Dans chaque cas, vous aurez à ajuster les variables dans le dossier `group_vars/<service>/<service>.vault.yml` pour les données sensible, et `group_vars/<service>/<service>.yml` pour les autres.
### Ajouter un rôle
Pour ajouter un rôle, cela se passe en deux étapes ;
- Ajouter le rôle au dépôt `piops` comme un sous module:
- Ajout : `cd roles && git submodule add -b master <url git du rôle>`
- Synchronisation : `cd .. && git submodule update --init --recursive`
Vous devrez maintenant avoir un dossier du nom de votre rôle dans le dossier `roles` de ce dépôt. Il ne vous reste plus qu'a le configurer ;
- Dans le fichier `test|production.yml`, ajoutez la tâche qui correspond à vôtre rôle. Vous devriez avoir reçu des indiquations sur la façon de procéder avec le rôle en question, sinon, renseignez vous en lisant le rôle et en notant les variables qui n'ont pas d'affectation par défaut.
📖 Voir les [conventions](docs/CONVENTION.md) et la [configuration](docs/CONFIG.md).
## Utilisation
Une fois que vous avez remplis le fichier hosts, vous pouvez éxécutez le playbook de la manière suivante :
`~$ ansible-playbook test.yml --ask-vault-pass --syntax-check`
pour effecuter un test de syntaxe.
Pour éxecuter le playbook, faites ceci :
Une fois que vous avez remplis l'inventaire, vous pouvez éxécutez le playbook de la manière suivante :
`~$ ansible-playbook test.yml --ask-vault-pass`
`$ ansible-playbook test.yml --ask-vault-pass`
Si vous ne voulez pas exécuter l'ensemble du playbook, vous pouvez utiliser des tags, comme par exemple le nextcloud ;
......@@ -96,26 +47,45 @@ Si vous avez définit des groupes ou des hôtes, vous pouvez choisir de n'éxéc
La différence entre ces deux options, c'est la nécessité d'ajouter des tags dans le premier cas, alors que dans le deuxième cas, vous pouvez éxécuter tout les chapitres d'un groupe ou hôte.
📖 Voir la [configuration](docs/CONFIG.md) et les [roles](docs/ROLES.md).
### Exemple :
Je voudrai déployer le rôle [shell-lqdn](https://git.laquadrature.net/lqdn-interne/piops-roles/shell-lqdn).
- Je vérifie qu'il est bien présent dans le dossier `roles/`,
- Je vérifie qu'il est bien présent dans le fichier `test.yml,`
- Il nécessite une configuration, je regarde dans le fichier `roles/shell-lqdn/vars/main.yml` si j'ai besoin de faire des ajouts ;
- Si oui, je fait mes modifications et ajouts dans `group_vars/test/test.yml`.
- Sinon, je continue.
- Je vérifie la syntaxe du playbook.
- J'éxécute [le test](docs/TEST.md) 📖
- `$ ansible-playbook test.yml --ask-vault-pass`
- Si tout se passe bien, mon rôle est déployé sur les serveurs faisant parti du group `test`.
## Documentation
Le playbook permet de 1) Configurer les hôtes sur lesquels appliquer les rôles et 2) Configurer les variables de ces rôles.
La documentation pour ce playbook se trouve [dans le dossier docs/](docs/README.md) et indiqué par l'emoji 📖 .
Nous avons deux playbook : Un pour les tests, et un pour la production.
Le playbook permet de ;
Les hôtes sont à renseigner dans le fichier `inventory.yml`.
1. Configurer les hôtes sur lesquels appliquer les rôles
2. Configurer les variables de ces rôles.
Les rôles sont trouvables dans le dossier `roles`. Le contenu de chaque rôle est géré dans son propre dépôt git, trouvable ici : https://git.laquadrature.net/lqdn-interne/piops-roles
Nous avons deux playbook :
- Un pour les tests : `test.yml`
- un pour la production : `production.yml`
Ils sont ensuite ajouté au dépôt via la commande `git submodules`. Cela permet de les intégrer à ce dépôt, tout en suivant les modifications de chaque dépôt dans son propre historique. Pour plus d'informations, voir [la documentation git.](https://git-scm.com/docs/git-submodule).
Les hôtes sont à renseigner dans le fichier `inventory.yml`.
Afin de savoir quels variables vous avez besoin de configuer pour chaque rôles, lisez le fichier `README.md` du dépôt correspondant au rôle qui vous intéresse. Vous pouvez aussi voir quels variables sont configurés dans le dossier `group_vars`.
Les rôles sont trouvables dans le dossier `roles`. Le contenu de chaque rôle est géré dans son propre dépôt git, trouvable ici : https://git.laquadrature.net/lqdn-interne/piops-roles
### Description de déroulement de la pièce ( play )
### Déroulement du playbook
- Nous avons plusieurs types de serveurs : **production** et **test** ainsi que le groupe pour chaque service.
- Pour chaque serveur, nous avons un ensemble de rôles qui vont être exécutés sur tout les serveurs. Ce sont ceux listés dans `site.yml``hosts: all`. [^1]
- Pour chaque serveur, nous avons un ensemble de rôles qui vont être exécutés sur tout les serveurs. Ce sont ceux listés par exemple dans `production.yml``hosts: all`. [^1]
- Ensuite, chaque serveur ayant **un** service et un seul, nous avons un ensemble de rôle décrivant la configuration à ce serveur en particulier. Par exemple, pour un serveur imaginaire, nous pouvons imaginer la configuration suivante :
```
......@@ -124,46 +94,19 @@ Afin de savoir quels variables vous avez besoin de configuer pour chaque rôles,
roles:
- shell-lqdn
- updates-lqdn
- security-lqdn
- monitoring-lqdn
- service-imaginaire-lqdn
```
Et ce, pour chaque serveur.
#### Configuration partagée basique
La configuration basique se découpe en plusieurs points :
- Sécurité
- `security-lqdn`
- Ce rôle configure les paquets `fail2ban`, `portsentry`, `rkhunter`, `tripwire`, `lynis`.
- `ansible-role-firewall`
- Configuration du firewall, à travers `iptables`
- Surveillance
- `logging-lqdn`
- Configuration des logs, à travers `logrotate`
- `ansible-node-exporter`
- Export des données de chaque serveur au niveau hardware. Consommées par le serveur admin avec grafana + prometheus.
- Mises à jours
- `updates-lqdn`
- Mises à jours à travers `unattend-upgrades`.
- Configuration utilisateurices
- `packages-lqdn`
- Installation des paquets supplémentaires par défaut.
- `shell-lqdn`
- Configuration des comptes utilisateurices et logging des actions de ces comptes.
À noter que les hôtes peuvent se trouver dans plusieurs groupes. Par exemple, le groupe Nextcloud ne contient d'un seul serveur, lqdncloud. Par contre, lqdncloud se trouve dans le groupe nextcloud, ainsi que dans le groupe production.
Nous avons donc les hôtes, qui se trouvent dans un ou plusieurs groupes. Il peut aussi y avoir des groupes contenant plusieurs serveurs, si par exemple nous voudrions plusieurs serveurs avec le même service ( SSO, Etherpad, nodeBB )...
## Questions Fréquemment Posées
### Ajouter un·e utilisateurice
### Contribuer
Afin d'ajouter un accès à un serveur, voyez le rôle `shell-lqdn`.
Si vous avez lut jusqu'ici, merci ! Pour nous aider à contribuer à ce playbook, vous pouvez prendre contact avec l'équipe technique de la Quadrature Du Net, via
- Le dépôt gitlab, en ouvrant des tickets ou des pull-requests.
- [Via Matrix/IRC](https://lqdn.fr/nous)
### Ajouter un paquet
### Licence
Afin d'ajouter un paquet, voyez le rôle `packages-lqdn`.
GPLv3
# Configuration du Playbook
## Options pour l'éxécution
### Installer le playbook
Pour effectuer l'installation complète du playbook, vous avez simplement à l'éxécuter avec la commande suivante ;
```
$ ansible-playbook production.yml -i inventory.yml --ask-vault-pass
```
### Effectuer des mises à jours
Lors de l'éxécution du playbook, vous pouvez utiliser le tag `update` pour effectuer les mises à jours ;
```
$ ansible-playbook production.yml -i inventory.yml --tags=update --ask-vault-pass
```
## Configuration partagée basique
La configuration basique, appliquée à tout les serveurs, se découpe en plusieurs points :
- Sécurité
- `security-lqdn`
- Ce rôle configure les paquets `fail2ban`, `portsentry`, `rkhunter`, `tripwire`, `lynis`.
- `ansible-role-firewall`
- Configuration du firewall, à travers `iptables`
- Surveillance
- `logging-lqdn`
- Configuration des logs, à travers `logrotate`
- `ansible-node-exporter`
- Export des données de chaque serveur au niveau hardware. Consommées par le serveur admin avec grafana + prometheus.
- Mises à jours
- `updates-lqdn`
- Mises à jours à travers `unattend-upgrades`.
- Configuration utilisateurices
- `packages-lqdn`
- Installation des paquets supplémentaires par défaut.
- `shell-lqdn`
- Configuration des comptes utilisateurices et logging des actions de ces comptes.
À noter que les hôtes peuvent se trouver dans plusieurs groupes. Par exemple, le groupe Nextcloud ne contient d'un seul serveur, lqdncloud. Par contre, lqdncloud se trouve dans le groupe nextcloud, ainsi que dans le groupe production.
Nous avons donc les hôtes, qui se trouvent dans un ou plusieurs groupes. Il peut aussi y avoir des groupes contenant plusieurs serveurs, si par exemple nous voudrions plusieurs serveurs avec le même service ( SSO, Etherpad, nodeBB )...
# Conventions d'écriture
### Stockage des variables
Dans chaque cas, vous aurez à ajuster les variables dans le dossier `group_vars/<service>/<service>.vault.yml` pour les données sensible, et `group_vars/<service>/<service>.yml` pour les autres.
## Questions Fréquemment Posées
### Ajouter un·e utilisateurice
Afin d'ajouter un accès à un serveur, voyez le rôle `shell-lqdn`.
### Ajouter un paquet
Afin d'ajouter un paquet, voyez le rôle `packages-lqdn`.
# Documentation PiOps
## Sommaire
- [Options de configuration](CONFIG.md)
- [Réaliser des tests](TEST.md)
- [Conventions d'écriture](CONVENTION.md)
- [Ajouter un nouveau rôle](ROLES.md)
- [FAQ](FAQ.md)
# Références
> Les références vers de la documentation en amont.
### Doc ansible
Pour référence, la documentation pour la dernière version d'ansible est
[ici](https://docs.ansible.com/ansible/latest/user_guide/)
### Ajouter un rôle
Pour ajouter un rôle, cela se passe en deux étapes ;
- Ajouter le rôle au dépôt `piops` comme un sous module:
- Ajout :
- `cd roles`
- `git submodule add -b master <url git du rôle>`
- Synchronisation :
- `cd ../piops`
- `git submodule update --init --recursive`
Ils sont ajouté au dépôt via la commande `git submodules` qui permet de les intégrer à ce dépôt, tout en suivant les modifications de chaque dépôt dans son propre historique. On as donc une référence externe.
Vous devrez maintenant avoir un dossier du nom de votre rôle dans le dossier `roles` de ce dépôt. Il ne vous reste plus qu'a le configurer ;
### Configurer un rôle
Afin de savoir quels variables vous avez besoin de configuer pour chaque rôles, lisez le fichier `README.md` du dépôt correspondant au rôle qui vous intéresse. Vous pouvez aussi voir quels variables sont configurés dans le dossier `group_vars`.
Dans le fichier `test|production.yml`, ajoutez la tâche qui correspond à vôtre rôle. Vous devriez avoir reçu des indiquations sur la façon de procéder avec le rôle en question, sinon, renseignez vous en lisant le rôle et en notant les variables qui n'ont pas d'affectation par défaut.
Pour plus d'informations, voir [la documentation git](https://git-scm.com/docs/git-submodule).
# Réaliser des tests
### Tester le playbook
#### Syntaxe
Pour effecuter un test de syntaxe ;
`$ ansible-playbook test.yml --ask-vault-pass --syntax-check`
#### Exécution
Afin de tester le bon déroulement des commandes ci-dessus, vous pouvez éxécuter le playbook sur un inventaire de test.
Commencez par completer le fichier `test-inventory.yml`, puis completez le fichier `group_vars/test/test.vault.yml`
Ensuite, vous pouvez lancer le playbook ;
```
$ ansible-playbook test.yml -i test-inventory.yml --ask-vault-pass
```
### Tester sur l'infrastructure lqdn
Sur l'infrastructure de La Quadrature, nous utilisons le serveur `lqdn-test` pour effectuer des tests. En général, nous utilisons un tag associé au rôle que nous voulons tester. Par exemple, pour tester le rôle keycloak ;
```
$ ansible-playbook test.yml -i inventory.yml --limit test.lqdn.fr --tags=test --ask-vault-pass
```
### Tester des rôles
Nous utilisons Vagrant et Molecule pour effectuer les tests dans les rôles. Toute la configuration de test pour chaque rôle est décrite dans le dossier `molecule` de chaque rôle.
Pour référence, voir ;
- https://floatingpoint.sorint.it/blog/post/setting-up-molecule-for-testing-ansible-roles-with-vagrant-and-testinfra
Vous pouvez aussi faire des tests petit à petit. Voir ;
- https://docs.ansible.com/ansible/latest/user_guide/playbooks_startnstep.html
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