Otoroshi 17.9 est là : découvrez mailer, Swagger UI, zip site, llms.txt, workflows

Lorsque vous déployez un site ou une API, sur Clever Cloud ou ailleurs, vous avez parfois besoin d’ajouter de “l’intelligence” en amont de votre application: des transformations sur les contenus ou les headers de la requête, de l’authentification, des règles de sécurité, ou même exposer simplement du contenu complémentaire.

C’est là qu’une API Gateway comme Otoroshi peut vous être utile. Ne vous arrêtez d’ailleurs pas à cette dénomination, ses possibilités sont nombreuses et pourraient bien vous aider dans de nombreuses situations, bien au-delà des sujets liés aux APIs.

Une solution open source qui gagne à être connue (et soutenue)

Otoroshi est un projet open source de la MAIF que de nombreux clients déployaient sur Clever Cloud. Lorsque nous avons décidé de mettre en place des services managés clés en main tels que Keycloak, Matomo ou Metabase, nous avons très vite pensé à Otoroshi comme une autre solution pouvant vous faciliter la vie, pour laquelle nous pouvions apporter une plus-value à travers une intégration poussée au sein de notre plateforme.

Nous avons alors décidé de nous associer à Mathieu Ancelin, l’un des développeurs principaux d’Otoroshi qui a cofondé Cloud APIM notamment pour travailler à des solutions complémentaire autour de cette API Gateway ultra-complète.

Depuis, cela a mené à des solutions telles que Biscuit Studio, qui permet la gestion et l’utilisation simplifiée de ces tokens que nous utilisons au sein de nos services et qui sont la base de notre futur IAM, un projet désormais sous l’égide de la fondation Eclipse. Mais aussi Clever AI, qui vise à abstraire et simplifier les fonctionnalités liées à l’utilisation de modèles IA, ainsi que leur intégration à des besoins d’entreprises.

Mais Otoroshi va bien plus loin. Outre ses fonctionnalités natives, il est livré avec de nombreux plugins, parfois méconnus même de ses utilisateurs chevronnés. Faisons un petit tour d’horizon de ceux qui peuvent vous intéresser, vous amuser ou qui ont été récemment ajoutés.

Déployer et gérer un Otoroshi n’a jamais été aussi simple

Commençons par la création d’un add-on Otoroshi qui peut se faire en quelques clics depuis notre Console. Cela vous déployera une application Java et une base de données Redis, préconfigurées. Vous n’aurez rien de plus à faire, le dashboard vous affichera les informations essentielles: vos identifiants pour l’interface web, l’API, le lien vers l’OpenAPI.json, etc.

Lorsqu’une nouvelle version est disponible, cela vous est notifié et vous pouvez mettre à jour d’un simple clic. Tout cela étant également possible à travers notre API ou les Clever Tools, notre CLI. Ces deux dernières vous ouvrent d’ailleurs des possibilités supplémentaires comme l’intégration de votre instance Otoroshi à un Network Group (nous en reparlerons dans un prochain billet), la personnalisation du domaine de son interface ou des nouvelles routes crées.

clever addon create otoroshi myOtoroshi \
  --option access-domain=otoroshi.example.com \
  --option routes-domain=otoroshi-routes.example.com

La seule chose que vous aurez à faire est de vous assurer que les DNS de ces domaines pointent bien vers les serveurs de la zone Clever Cloud ou l’Otoroshi est déployé.

Créer votre première route et… un site statique

Une fois votre Otoroshi créé, connectez-vous à son interface web. Vous pourrez alors créer une nouvelle route soit via le bouton “+” en haut à droite de l’interface, soit via le raccourci dans le menu latéral gauche. Vous pourrez alors définir le nom de la route, sa description, etc. Puis la créer en cliquant sur “Create Route” en haut à droite. Vous arriverez alors dans le designer.

Il vous exposera alors de manière visuelle la route telle qu’elle est configurée, ses paramètres de frontend (le domaine exposé par lequel vous accédez à la route) et le backend vers lequel il redirige. Vous pouvez d’ailleurs tester l’URL de frontend (sans le port 80 et le /*) qui renvoie par défaut vers un site qui détaille les headers de la requête reçue.

On peut alors chercher un plugin à utiliser et l’ajouter à cette route par défaut : Force HTTPS traffic. Cliquez sur “Add to flow” puis “Save”, il renverra automatiquement vers une version sécurisée de vos pages (ce qui est automatique si votre site est hébergé sur Clever Cloud).

On peut ensuite changer quelques détails. Par exemple cliquer sur “Frontend” dans le flow et ajouter un /static à la fin du domaine, puis sauvegarder la route. Il faudra désormais utiliser l’URL https://votre-domaine.tld/static pour accéder au backend.

Remplaçons ensuite ce dernier par un contenu HTML statique en ajoutant le plugin “Static Response”. Ce dernier vous permet de renvoyer toujours un même contenu HTML sur une route, ce qui est pratique pour une “one-page app” par exemple. Dans la partie “body” du plugin insérez le contenu HTML de votre choix, par exemple :

<!DOCTYPE html>
<html lang="fr">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Otoroshi Static Route</title>
</head>
<body>
    <h1>Welcome to Clever Cloud</h1>
    <p>This page is hosted by an Otoroshi instance</p>
</body>
</html>

Sauvegardez, le contenu statique sera alors renvoyé sur l’URL https://votre-domaine.tld/static.

Et si votre site était un fichier Zip ?

Cette fonctionnalité existe sous diverses formes dans Otoroshi. Vous avez par exemple la possibilité de servir du contenu statique depuis un dossier de l’instance, un service de stockage objet compatible S3 tel que Cellar ou… une archive zip.

Pour cela, retirez le plugin statique précédent de la route et ajoutez “Zip file backend”. Sauvegardez la route. Par défaut, ce plugin contient l’URL d’un fichier zip contenant une ancienne version de la documentation d’Otoroshi. Lorsqu’une requête arrive, l’archive est téléchargée, décompressée puis renvoyée. Elle est mise en cache pour le temps indiqué dans le champ de TTL (3 600 000 ms par défaut, soit une heure).

Vous pouvez ainsi stocker des sites statiques dans un service tel que Cellar, puis les héberger sur différentes routes ou domaine au sein d’une même instance Otoroshi sans effort.

Envoyez des emails depuis votre fournisseur via une API REST

Autre fonctionnalité intéressante d’Otoroshi déployé sur Clever Cloud: le plugin “Mailer endpoint”. Celui-ci vous permet d’utiliser n’importe quel service d’envoi d’email par SMTP, de celui de votre FAI à Gmail ou Outlook en passant par un service hébergé chez Gandi ou OVHCloud… et de le transformer en une API REST d’envoi d’email.

Pour cela, créez une nouvelle route finissant par /email par exemple. Placez-y le plugin qui aura besoin des paramètres du serveur SMTP: hôte, nom d’utilisateur, mots de passe, etc. Une fois configuré, enregistrez la route. Vous pouvez envoyer des emails d’une simple requête cURL:

curl -XPOST https://votre-domaine.tld/mail \
  -H 'Content-Type: application/json' \
  -d '{
    "subject": "Test Email",
    "from": "your name",
    "to": ["your-email@example.com"],
    "text": "This is a test email"
  }'

Attention tout de même: en l’état il n’y a pas d’authentification sur la route. Pour en ajouter, ajoutez le module “APIkeys”. Vous pourrez ensuite créer une clé d’API dans le menu dédié, attribuer la clé à votre route via le sélecteur “Authorized on”. Lorsque c’est fait, vous pourrez effectuer la même requête mais il faudra y ajouter la basic auth ou le bearer token de votre clé d’API pour qu’elle soit acceptée par Otoroshi.

Notez au passage qu’Otoroshi gère de très nombreuses solution d’authentification, tels que les JWT, les Biscuit, mais aussi des solutions plus complexes telles que Keycloak par exemple.

Otoroshictl, la CLI qui simplifie la vie

Et si vous pouviez faire toutes ces actions simplement en une seul commande ? C’est la promesse de la CLI Otoroshictl, qui permet de gérer vos instances Otoroshi et qui intègre depuis peu une fonctionnalité d’ajout simplifié du plugin mailer :

# Vous pouvez également télécharger un binaire depuis GitHub
cargo install otoroshictl
otoroshictl toolbox add-mailer

L’application vous demandera alors d’entrer les paramètres de votre serveur SMTP, créera la route, l’AP key, configurera le tout et vous donnera une requête cURL d’exemple.

Pour cela, il faudra au préalable avoir configuré votre instance Otoroshi Clever Cloud comme celle à utiliser. Là aussi nous avons tout fait pour vous simplifier la vie via les Clever Tools :

# Activez la gestion des opérateurs tels qu'Otoroshi
# Si ce n'est pas déjà fait
clever features enable operators

# Récupérez la configuration de votre Otoroshi
# Passez là à otoroshictl comme configuration courante
clever otoroshi get-config myOtoroshi | otoroshictl config import --stdin --current

Notez que cette application Rust est open source (sous licence Apache 2.0), n’hésitez pas à proposer vos idées ou même à y contribuer.

Exposez une UI Swagger depuis un simple openapi.json

Autre fonctionnalité qui pourra intéresser ceux qui proposent des API respectant le standard OpenAPI : l’hébergement simplifiée d’une interface Swagger. Ajoutez le plugin “Swagger UI” à l’une de vos routes, vous n’aurez qu’à indiquer l’emplacement du fichier OpenAPI.json pour qu’une page Swagger UI soit générée avec les paramètres de votre choix sur le tri des opérations, des tags, le thème à utiliser, etc.

Support de llms.txt: facilitez la vie aux IA

Vous disposez d’une documentation en ligne ? Les LLMs sont friands de la consommer dans sa version Markdown, le standard llms.txt a d’ailleurs été pensé pour cela et des générateurs de sites statiques comme Hugo commencent à supporter de telles fonctionnalités nativement.

Mais comment renvoyer la version Markdown d’une page lorsqu’elle existe ? De nombreux services, notamment dans le domaine de l’IA, ajoutent le header Accept: text/markdown dans leurs requêtes pour indiquer leur préférence. Mais celui-ci doit être supporté par votre serveur web afin d’être pris en compte, ce qui nécessite de la configuration.

Otoroshi intègre désormais un plugin “LLMs.txt Accept Markdown” pour répondre à ce besoin : si ce header est présent dans une requête et qu’une version Markdown de la page existe, c’est elle qui est renvoyée. Là aussi, un système de cache est mis en place afin de réduire les temps de réponse. Pour l’utiliser il suffit de l’ajouter à une route, de définir la durée et la taille du cache et de sauvegarder.

Envie d’en savoir plus ? Venez nous voir au FOST (ex-apidays)

Vous l’aurez compris, on pourrait vous parler d’Otoroshi et de ses fonctionnalités pendant des heures. Une chose est sûre: dans son océan de possibilités, il y en a sans doute une qui peut vous être utile. Notre conseil: déployez-en un, testez, expérimentez, faites nous vos suggestions et vos retours.

Nous serons d’ailleurs présents la semaine prochaine au FOST (ex-apidays) où nous tiendrons notre Amazing Clever Cloud Enterprise Summit (ACCES) où nous parlerons, avec nos clients et partenaires, de tout ce qui vous attend pour Clever Cloud en 2026. N’hésitez pas à venir nous rendre visite.

Découvrez les Workflow à 13h

Vous pouvez également vous rendre sur notre chaîne Twitch et YouTube à 13h, nous y présenterons en live et plus en détail Otoroshi, ses dernières grandes nouveautés dont une qui a été ajoutée au début de l’année et peaufinée depuis: les workflows. Ils vous permettent de créer des scénarios d’automatisation complet conjointement avec vos routes et leurs plugins, modèles d’IA avec une gestion qui peut être programmée, mais aussi simplement mise en place avec un éditeur visuel. Venez nous poser vos questions en direct !