Créer un nouveau role

Créer la structure

Nous n'utilisons que les 4 dossiers suivants pour nos roles :

• tasks : Les fichiers de tache. On n'utilise le nom main.yml que s'il n'y a qu'un fichier. On préfère découper les opérations en fichiers avec un nom évocateur. Si c'est un role de service, il devrait avoir à minimas les fichiers suivants : install.yml, upgrade.yml, restore.yml, uninstall.yml
• defaults : Les valeurs par défault du role
• handlers : d'éventuels handlers
• templates : d'éventuels templates

# Exemple d'arborescence
├── defaults
├── handlers
│   └── main.yml
├── README.md
├── tasks
│   └── install.yml
│   └── upgrade.yml
│   └── restore.yml
│   └── uninstall.yml
└── templates

Tester le rôle

Il faut ajouter un hôte <role>_test et le référencer dans :

• Le groupe de sa machine (bardane), dans 10-machines ;
• Le groupe de son service (<role>), dans 01-applications

bardane, la VM de test, a une entrée DNS en *.test.paquerette.eu : on utilisera ce parent pour la variable application_domain.

Pour tester le rôle, on créera un playbook install/<role> qui importe le rôle.

Par sécurité, on se limitera explicitement à l'hôte test. Exemple pour coturn :

ansible-playbook playbook/install/<role>.yml --limit coturn_test

Passer en production

Créer un nouvel hôte, comme pour l'hôte de test, et penser à renseigner les mêmes variables (secrets, domaine...)

⚠️ Penser à ajouter le domaine dans la zone DNS.

Ajouter ensuite une entrée dans la documentation pour indiquer comment utiliser le service, en plus d'une entrée pour indiquer comment configurer le service.

Ajouter le role dans la doc

Éditer le fichier SUMMARY.md et ajouter le role dans la bonne section.

Bonne pratiques

Les chemins par défaut

Autant que possible, une application doit suivre les directives suivantes :

• S'installer dans : /var/www/APPLICATION_ID, avec configuration et petites données
• Mettre les données volumineuses dans : /mnt/nextcloud/APPLICATION_ID
• tourner avec l'utilisateur : APPLICATION_ID
• exposer ses logs dans : /var/log/nextcloud/APPLICATION_ID.log

De même en utilisant les roles existant, elle aura :

• un pool php_fpm portant le nom : APPLICATION_ID
• un fichier conf nginx : /etc/nginx/conf.d/APPLICATION_ID.conf
• une BDD du nom APPLICATION_ID_db avec l'utilisateur APPLICATION_ID_usr
• un fichier de backup : /etc/rustic/APPLICATION_ID.toml

Et d'une manière générale utiliser au maximum l'id de l'application comme référence pour le role afin de ne pas multiplier le variables.

{{ application_id }} vaut par défaut {{ inventory_hostname }}.

Exposition sur le web

L'URL est définie au niveau de l'hôte dans la variable application_domain.

Par défaut on suppose que l'application répond directement aux requêtes. Idéalement, le rôle prend en compte la possible existance de la variable behind_reverse_proxy (à true), qui indique que l'application est derrière un reverse proxy.

Exposition directe (sans reverse proxy)

Si l'application prend en charge TLS, on générera les certificats nécessaires avec la tâche :

- name: Register Let's Encrypt certificate
  import_role: 
    name: certbot
    tasks_from: cert.yml

Il y a deux cas.

• Si le service est non-HTTPS (TCP) ou bien chiffre lui-même la connexion, appeler le rôle avec la variable certbot_install_nginx: true.
• Si le service est exposé derrière le nginx de la machine, il faut copier un fichier de configuration dans /etc/nginx/conf.d.

Les certificats sont déposés dans /etc/letsencrypt/live/{{ application_domain }}. La clé publique s'appelle fullchain.pem et la clé privée privkey.pem. Le renouvellement est automatique.

ℹ️ Dans le cas d'un service non-HTTP(S), il faudra probablement modifier la configuration réseau de la machine cible.

Cas du reverse proxy

Prendre soin de désactiver TLS, la terminaison étant assurée par le reverse proxy.

Backups

#todo ajouter password au niveau des hosts_vars du service

Les backups sont assurés par rustic. Un rôle gère déjà la configuration, la planfication et l'externalisation des backups.

Il faut au minimum définir la variable suivante :

• rustic_backup_sources : répertoires ou fichiers à sauvegarder, séparés par des virgules

Si l'application a besoin d'un backup logique de base de données :

• application_type : local ou docker
• db_type : SGBD : postgresql ou mariadb supportés ;
• application_db_name : nom de la DB (si locale) ou du conteneur.

Le comportement générique du backup peut être étendu avec les variables suivantes :

• rustic_backup_before : script à lancer avant le backup ;
• rustic_backup_after : script à lancer après le backup.

Enfin, importer le fichier de tâches qui s'occupe de l'initialisation :

- name: Configure backup
  import_role:
      name: rustic
      tasks_from: add_backup.yml
  tags:
      - rustic

Télécharger des fichiers

Dans le cas d'un ou des fichier(s) qui seraient téléchargés sur différentes machines (e.g. un role voué à s'exécuter sur un groupe), utiliser le rôle download_archive pour gérer sa mise en cache.