From ece97ef32916dab41fb051c0aec2e78e0eb7ca31 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 | 2 + doc/fr/introduction.md | 19 +++++++ doc/fr/resources/overview.plantuml | 55 ++++++++++++++++++ doc/fr/resources/overview.svg | 91 ++++++++++++++++++++++++++++++ 5 files changed, 169 insertions(+), 1 deletion(-) 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..d1b4ee9 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,5 +1,7 @@ # Documentation +- (FR) - [Introduction](./fr/introduction.md) + ## Tutorials - (FR) - [Premiers pas](./tutorials/fr/first-steps.md) diff --git a/doc/fr/introduction.md b/doc/fr/introduction.md new file mode 100644 index 0000000..194968a --- /dev/null +++ b/doc/fr/introduction.md @@ -0,0 +1,19 @@ +# 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) \ 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..ac831d5 --- /dev/null +++ b/doc/fr/resources/overview.plantuml @@ -0,0 +1,55 @@ +@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 HTTPAPIHandler as "HTTP API Handler" + + HTTPAPIHandler .down.> SpecificationRegistry: validates agents data with + + HTTPAPIHandler .right.> DataStore: saves agent data in + } +} + +node OpenWRTNode as "OpenWRT Node" { + component EmissaryAgent as "Emissary Agent" { + + component StateManager as "State Manager" + + StateManager --up-> HTTPAPIHandler: fetches 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..f99b2f9 --- /dev/null +++ b/doc/fr/resources/overview.svg @@ -0,0 +1,91 @@ +Pilot NodeEmissary ServerSpecification RegistryOpenWRT NodeEmissary AgentData StoreHTTP API HandlerUCI SpecmDNS SpecApp SpecProxy SpecState ManagerUCI ControllerSysupgrade ControllerProxy ControllermDNS ControllerApp Controllervalidates agents data withsaves agent data infetches specs fromreconciles withreconciles withreconciles withreconciles withreconciles with \ No newline at end of file