Salut, salut,

Ceci est un long mail pour parler un peu de la nouvelle API qui va prochainement arriver dans Re2o et des changements qui viennent avec. Je vous préviens il y a plein d'infos et de détails donc je vous conseille de vous posez avant de lire ce mail. Bonne lecture !

Commencons par parler de l'API côté server Re2o.

Tout d'abord pour ceux qui ne passent pas leur vie sur #re2o (askip, ça existe mais je suis pas sûr), je vais décrire où en est actuellement la situation et les problèmes liés à l'API actuelle:

1) Actuellement, les endpoints de l'API ont été fait un peu l'arrache aux moments et aux endroits où on en avait besoin. Par exemple les premiers endpoints commencent par "/machines/rest/..." parce que les premières données nécessaires étaient des infos dans l'app "machines" puis des endpoints en "/users/rest/..." sont apparus parce qu'on utilisait des infos dans l'app "users". Bref vous l'aurez compris, les endpoints ne sont pas a des endroits logiques et un peu difficile à trouver donc à utiliser (et puis c'est pas parce qu'on avait écrit rest dans l'url que l'API était REST ...)

2) Les infos exposées sont celles dont on avait besoin uniquement et dans un format qui nous arrangeait donc autant dire que c'est pas vraiment utilisable pour autre chose. Ce qui fait que si quelqu'un voudrait dev un script utilisant les infos de Re2o via l'api, bah il faut commencer par ajouter les endpoints dans Re2o ce qui est sacrément décourageant.

3) On utilise django-rest-framework pour gérer l'api, sérialiser les infos, ... (c'est probablement le package le plus courant pour gérer une api avec Django). Sauf que les quelques endpoints utilisent vraiment les trucs les plus basiques et assez salement parce que ça suffisait et que personne n'avait fait l'effort d'apprendre comment fonctionnait django-rest-framework (qui a une courbe d'apprentissage assez violente il faut le dire).

Bref autant dire que le peu d'api qui existait n'était pas vraiment utilisable. Je me suis donc lancé dans le projet de refaire l'api et je vous annonce donc qu'il va bientôt avoir une nouvelle app "api" dans re2o qui exposera tous les modèles de Re2o de façon REST, systèmatique et uniforme (ex : des urls en "/api/<model>/<id>" ou encore des opérations basés sur les méthodes HTTP "GET", "POST", ...). Pour plus de détails, je vous invite a aller voir la documentation à partir de https://gitlab.federez.net/federez/re2o/wikis/API/Raw-Usage (puis vous balader dans la section API du wiki pour plus d'infos). Et oui on a commencé à écrire de la doc ;).

Pour les détails de l'implémentation, la MR est encore en phase de review : https://gitlab.federez.net/federez/re2o/merge_requests/172

Pour ceux qui craignent de voir leur prod cassée à cause d'un changement d'API, sachez qu'on essaye de le faire le plus en douceur possible:

1) on ajoute les endpoints dans Re2o (ça c'est la MR et ce que j'ai décrit au-dessus) SANS supprimer les anciens endpoints.

2) Pendant que les gens pull Re2o avec la nouvelle API, on dev les script utilisant la nouvelle API

3) Les gens pullent ces scripts utilisant la nouvelle API (génération de DNS, DHCP, ...)

4) Quand on a la confirmation que plus personne utilise l'ancienne API (il y a suffisament peu d'instance en prod pour qu'on puisse se permettre de faire comme ça), on vire l'ancienne API.

Passons maintenant au second sujet, un peu plus récent: le client API.

En effet qui dit "nouvelle API" dit "re2o-tools doit utiliser cette API" et donc dit aussi "refaire pas mal de choses dans re2o-tools" qui commencait à présenter plusieurs soucis. Selon moi, il y a en particulier:

1) Tous les services sont dans le même projet, ce qui veut dire que si tu veux ajouter un service qui n'est utilisé que dans ton asso, bah tu te retrouves à l'ajouter partout (dans ton dns, dans ton dhcp, chez les autres assos, ...) ce qui a aussi pour conséquence que tu te retrouves avec des dépendances qui ne font pas de sens. Par exemple actuellement il faut python3-mongodb pour faire tourner re2o-tools (parce qu'un des services l'utilise) et honnêtement c'est un peu dommage quand tu veux juste générer des fichiers de zone DNS.

2) Le manager est devenu trop complexe. C'est un truc qui marche bien mais son code est assez violent pour un projet dont le but c'est de récupérer quelques infos depuis l'API et de faire trois actions basiques avec ces infos. Une des idées primaire de ce manager était justement de pouvoir gérer plusieurs services en même temps (lequels regen, forcer la regen de certains, ...) mais bon soyons hônnetes, en pratique tout le monde n'utilise qu'un seul service à la fois. Personne ne fait tourner en prod un DNS, un DHCP, un server mail et un contrôleur de bornes Wi-Fi sur la même machine ... En quand bien même quelqu'un voudrait le faire, ce serait plus simple et plus propre d'avoir plusieurs fois re2o-tools dans des dossiers séparés. En termes de perf, c'est pareil et tu évites de mélanger les fichiers et les conf tout en t'assurant que si la génération d'un service plante, ça ne plante pas les autres. Bref, virez-moi ce manager overkill.

3) Le code est parfois dégueulasse. Faut dire ce qui est, le code marche mais c'est loin d'être le plus beau. Je parles d'expérience puisque je vais prendre un example que j'ai écrit. Dans le code pour générer les fichiers de DNS, il y a une partie pour générer les fichiers de reverse que j'ai écrite. Bon si on oublie le fait que j'ai appris plein de trucs en python depuis (notament à moins réinventer la roue), je reste impressioné de voir que l'algo que j'ai pondu marche nickel mais je dois bien être le seul puisqu'à chaque fois il me faut 5-10 minutes pour recomprendre les 30 lignes de codes en question. Donc ça s'appelle un code moche et pas maintenanable quand seul l'auteur le comprend (et pas sans efforts en plus).

Bref une nouvelle API était l'occasion de revoir en profondeur tous ces problèmes. Et j'ai donc commencer à faire un POC de ce que ça pouvait donner. Bien que le résultat ne soit pas terminé, ça marche assez bien. Les résultats sont dispo à https://gitlab.federez.net/re2o.

By the way vous verrez que cette URL mène à un nouveau groupe que j'ai commencé sur le gitlab de FedeRez dédié à Re2o (d'où le nom du groupe ^^) parce que je ne trouvais pas normal que je soit "owner" du groupe FedeRez (dans lequel est Re2o actuellement) sous prétexte que je dev Re2o. Bon rassurez vous, si je voulais faire une connerie je l'aurais déjà faite mais bon sur le principe, je trouve pas ça super. Alors autant profiter de faire des projets from scratch pour commencer ce nouveau groupe. (j'avais prévenu qu'il y avait plein de nouveauté dans ce mail).

Pour ce qui est du nouveau fonctionnement des services j'ai écrit un bout de doc là (https://gitlab.federez.net/federez/re2o/wikis/API/API-Client) (désolé pour la piètre qualité du schéma). Le principe est d'abord d'avoir un client API qui facilite grandement l'utilisation de l'API (gestion de l'authentification, des URLs, du formats des réponses, ...). Bref simplifier tout ça. Et surtout proposer un truc que tout le monde peut utiliser de façon indépendante des autre projets. C'est de là qu'est venue l'idée d'utiliser une "API en couche". L'idée est d'avoir une couche facile à utiliser (= le client API dont on parle) mais qui cache plein de choses (et donc ne permet pas une utilisation ultra pécise) et si nécessaire, il est toujours possible "d'enlever une couche" et d'utiliser directement la lib requests de python ou encore l'API REST avec un autre language que python mais à vous de réimplémenter les trucs compliqués.

Sur le groupe Re2o, il y a un projet "Re2o API client" qui est donc ce client API en question. Ce code là est quasi complet, il y a sans doute des ajustements à faire mais dans l'ensemble il ne bougera pas trop je pense. Les autres projets sont justement les POC pour remplacer re2o-tools (DHCP, DNS et ML pour l'instant) en utilisant le client API comme submodule git (à terme avoir un package python serait encore mieux mais chaque chose en son temps). Tout d'abord, vous verrez qu'ils sont dans des projets séparés, ce qui était (toujours selon moi) un problème de re2o-tools. Vous verrez que les codes de ces projets sont bien plus simples que ceux de re2o-tools (mais pas commenté, oui je sais). Bien qu'il n'y ait pas encore tout le sucre qui consiste à vérifier les fichiers générés sont corrects, la base du script fonctionne et génère les fichiers. Ils pourraient presque être déjà utilisés en prod. \o/

En résumé, (parce qu'il faut bien un résumé à la fin de ce roman) les nouveautés sont :

1) Une nouvelle API RESTful qui permet d'accéder à l'ensemble des données de Re2o

2) Un nouveau client API qui a pour but de simplifier grandement l'utilisation de la nouvelle API et faire en sorte de ne pas se prendre la tête pour dev un nouveau service

3) Un nouveau groupe dédié à Re2o sur le gitlab (je suis encore le seul membre mais il est publique est je propose d'y transférer les gens si l'idée de ce groupe convient à tout le monde)

4) Je sais pas faire des infos concises et des mails courts (mais ça c'est pas nouveau) ;)

N'hésitez pas à me faire part de vos avis si ces changements sont bien ou pas. Perso je suis assez content de la tournure que ça prend et je trouve la base plus saine mais bon j'ai pas un avis très neutre.

Et enfin pour ceux qui ont lus jusque là, sachez que la version 2.7 se rapproche à grand pas et ne devrait plus trop tarder à être annoncée.

Voilà merci de votre attention,

Bon baisers de Russie d'Allemagne

Maël "MoaMoaK" Kervella