From 58ef3b007730ca4adf86f95451439b16116186ce Mon Sep 17 00:00:00 2001 From: William Petit Date: Tue, 23 May 2023 14:48:49 +0200 Subject: [PATCH] doc: add emissary introduction --- .gitignore | 3 +- doc/README.md | 14 ++--- doc/fr/introduction.md | 30 +++++++++ doc/fr/resources/overview.plantuml | 59 ++++++++++++++++++ doc/fr/resources/overview.svg | 99 ++++++++++++++++++++++++++++++ doc/tutorials/fr/first-steps.md | 4 +- 6 files changed, 200 insertions(+), 9 deletions(-) create mode 100644 doc/fr/introduction.md create mode 100644 doc/fr/resources/overview.plantuml create mode 100644 doc/fr/resources/overview.svg diff --git a/.gitignore b/.gitignore index fc7ef18..7cd102b 100644 --- a/.gitignore +++ b/.gitignore @@ -9,4 +9,5 @@ dist/ /agent-key.json /apps /server-key.json -/.emissary-token \ No newline at end of file +/.emissary-token +/out \ No newline at end of file diff --git a/doc/README.md b/doc/README.md index e81bd84..bde729d 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,20 +1,20 @@ # Documentation +- (FR) - [Introduction](./fr/introduction.md) + ## Tutorials - (FR) - [Premiers pas](./tutorials/fr/first-steps.md) ## References -### API +### Specifications -[See `misc/rest/server.rest`](../misc/rest/server.rest) - -### Spécifications - -- [Schéma `app.emissary.cadoles.com`](../internal/spec/app/schema.json) +- [Schéma `app.emissary.cadoles.com`](../internal/agent/controller/app/spec/schema.json) +- [Schéma `proxy.emissary.cadoles.com`](../internal/spec/proxy/schema.json) +- [Schéma `mdns.emissary.cadoles.com`](../internal/agent/controller/mdns/spec/schema.json) - [Schéma `uci.emissary.cadoles.com`](../internal/spec/uci/schema.json) -- [Schéma `gateway.emissary.cadoles.com`](../internal/spec/gateway/schema.json) +- [Schéma `sysupgrade.openwrt.emissary.cadoles.com`](../internal/agent/controller/openwrt/spec/sysupgrade/schema.json) ### Configuration diff --git a/doc/fr/introduction.md b/doc/fr/introduction.md new file mode 100644 index 0000000..587dd12 --- /dev/null +++ b/doc/fr/introduction.md @@ -0,0 +1,30 @@ +# Introduction + +"Emissary" est un programme entrant dans la catégorie des outils de gestion et déploiement de configuration. + +En utilisant un agent déployé sur chaque système cible, il permet aux administrateurs système de centraliser le contrôle et la supervision de la configuration. Grâce à ses fonctionnalités avancées, il est capable de faire converger la configuration d'une machine vers un modèle précis défini par une ou plusieurs spécifications centralisées sur un serveur de pilotage dédié. + +Le principal atout d'"Emissary" réside dans sa capacité à activer des "contrôleurs" spécifiques pour chaque aspect de la configuration système. Ces contrôleurs sont des modules intelligents qui agissent comme des agents spécialisés, veillant à ce que les paramètres de configuration soient correctement appliqués et respectent les spécifications définies. + +Grâce à cette approche modulaire, "Emissary" peut gérer diverses facettes de la configuration, telles que les paramètres réseau, les règles de sécurité, les options de performance et bien plus encore. Chaque contrôleur est conçu pour répondre à des besoins spécifiques, offrant ainsi une flexibilité et une granularité optimales dans la gestion de la configuration. + +Certains contrôleurs permettent également l'exécution de services spécialisés comme des serveurs mandataires inverses ou des applications web autonomes. + +L'utilisation d'un serveur de pilotage centralisé permet à "Emissary" de stocker et de mettre à jour les spécifications de configuration de manière cohérente. Les administrateurs peuvent définir des modèles de configuration précis, les affiner au fil du temps et les appliquer en un seul clic sur l'ensemble du parc de machines gérées. Cela garantit une uniformité et une conformité accrues, tout en facilitant la maintenance et les mises à jour à grande échelle. + +À l'heure actuelle, Emissary est conçu pour cibler spécifiquement le système d'exploitation OpenWRT. L'activation des "contrôleurs" spécifiques à cet OS permet de converger la configuration de la machine OpenWRT vers un modèle correspondant aux spécifications centralisées sur le serveur de pilotage. Ces spécifications peuvent inclure des paramètres réseau, des configurations de sécurité, des règles de pare-feu, des options de routage, des services système, et bien d'autres éléments spécifiques à OpenWRT. + +## Vue d'ensemble de l'architecture + +![](./resources/overview.svg) + + +## Contrôleurs + +Voici la liste des contrôleurs implémentés à ce jour: + +- **Contrôleur UCI** - Permet de modifier les données [UCI](https://openwrt.org/docs/guide-user/base-system/uci) (**U**nified **C**onfiguration **S**ystem) d'un système OpenWRT et ainsi configurer les services systèmes, les règles pare-feu, la configuration des NICs, etc sur celui-ci. +- **Contrôleur SysUpgrade** - Permet de mettre à jour un système OpenWRT via l'outil [`sysupgrade`](https://openwrt.org/docs/guide-user/installation/generic.sysupgrade). +- **Contrôleur Proxy** - Permet de déployer des services de type passerelle mandataire inverse ("reverse proxy") sur la machine cible. +- **Contrôleur mDNS** - Permet d'annoncer des services via mDNS sur les différents réseaux de la machine cible. +- **Contrôleur App** - Permet de déployer des applications web "embarquées" (s'exécutant localement et non dépendantes d'une connectivité internet) sur la machine cible. Voir le projet ["Edge App"](https://forge.cadoles.com/arcad/edge). \ No newline at end of file diff --git a/doc/fr/resources/overview.plantuml b/doc/fr/resources/overview.plantuml new file mode 100644 index 0000000..9b3ef95 --- /dev/null +++ b/doc/fr/resources/overview.plantuml @@ -0,0 +1,59 @@ +@startuml +top to bottom direction +skinparam linetype ortho + +node PilotNode as "Pilot Node" { + database DataStore as "Data Store" + + component EmissaryServer as "Emissary Server" { + + component SpecificationRegistry as "Specification Registry" { + component UCISpecification as "UCI Spec" + component MDNSSpecification as "mDNS Spec" + component AppSpecification as "App Spec" + component ProxySpecification as "Proxy Spec" + component SysUpgradeSpecification as "SysUpgrade Spec" + } + + component HTTPHandler as "HTTP Handler" + + HTTPHandler .down.> SpecificationRegistry: validates agents data with + + HTTPHandler .right.> DataStore: saves agent data in + } +} + +node OperatorNode as "Operator Node" { + component EmissaryClient as "Emissary Client" + + EmissaryClient -left-> HTTPHandler: administrates +} + +node OpenWRTNode as "OpenWRT Node" { + component EmissaryAgent as "Emissary Agent" { + + component StateManager as "State Manager" + + StateManager --up-> HTTPHandler: fetches agent ^*specs from + + component UCIController as "UCI Controller" + + UCIController .up.> StateManager: reconciles with + + component SysUpgradeController as "SysUpgrade Controller" + + SysUpgradeController .up.> StateManager: reconciles with + + component ProxyController as "Proxy Controller" + + ProxyController .up.> StateManager: reconciles with + + component MDNSController as "mDNS Controller" + + MDNSController .up.> StateManager: reconciles with + + component AppController as "App Controller" + + AppController .up.> StateManager: reconciles with + } +} diff --git a/doc/fr/resources/overview.svg b/doc/fr/resources/overview.svg new file mode 100644 index 0000000..2d339bd --- /dev/null +++ b/doc/fr/resources/overview.svg @@ -0,0 +1,99 @@ +Pilot NodeEmissary ServerSpecification RegistryOperator NodeOpenWRT NodeEmissary AgentData StoreHTTP HandlerUCI SpecmDNS SpecApp SpecProxy SpecSysUpgrade SpecEmissary ClientState ManagerUCI ControllerSysUpgrade ControllerProxy ControllermDNS ControllerApp Controllervalidates agents data withsaves agent data inadministratesfetches agent ^*specs fromreconciles withreconciles withreconciles withreconciles withreconciles with \ No newline at end of file diff --git a/doc/tutorials/fr/first-steps.md b/doc/tutorials/fr/first-steps.md index f9d9762..cda60db 100644 --- a/doc/tutorials/fr/first-steps.md +++ b/doc/tutorials/fr/first-steps.md @@ -1 +1,3 @@ -# Premiers pas \ No newline at end of file +# Premiers pas + +> TODO \ No newline at end of file