technical_spec_and_todo.txt

################ This document
This document is only a todo/don't forget document for Jean Gabès, opsbro author because he have a small fish memory, really ┻━┻︵ \(°□°)/ ︵ ┻━┻

As a user, you don't have to read it.
But if you want to start a project (or help this one (/.__.)/ \(.__.\) ), you can give a look at the internal of "think" such a tool, how it's defined and why in adding a feature, 60% of the time is spec, 40% doing. (and another 40% debugging).




############# BIG PARTS
All the configuration / deployment is model based (aka into packs)

* service discovery (gossip / detectors / groups)
  * automatically detect new node in few seconds
  * detect what your server is and automatically set it into groups
* monitoring (collectors / checks / handlers)
  * based on groups, collects metrics/data from your system & applications (by queries or statsd / graphite)
  * checks theses metrics/data if they are OK
  * if they are not OK, raise alerts (mails, slack, other)
* configuration automation / system compliance (compliance / system driver / generator / executor / KV)


service discovery
automatic detection
monitoring
metrology
configuration automation
system compliance


########### Main philosophy
 * It follow the Lean Ops mantra
 * Don't be a cargo cult ops
   * it sounds cool
   * BUT end large corps need over powerful tools, and such tools finish to be hard to start with
   * complexity came from linking powerful tools, each one for a specific topic
   * difficulty = nb over powerfull tools ²
   * in the end you are loosing time to do your real job & build really fun things
 * I (Jean Gabès) did build such a over powerful tool, and it's a real success to large corps
    * but I know it's too much to lot of small teams!
 * Learn from the real world manufactoring (Toyota & co): they did reduce the cost of operation/production thanks to the Lean Manufactoring
   * We need to transform us into Lean Ops: use "just enough" tool
 * It's what OpsBro is for all Ops: it solve day to day real world use cases and stay in this philosophy








########## Doc & tuto plan

service discovery
automatic detection
monitoring
metrology
configuration automation
system compliance


################# Pypi
cat ~/.pypirc
[server-login]
repository: https://upload.pypi.org/legacy/
username: naparuba
password: XXXXXXXX

python setup.py register sdist upload


################################# CLI SPEC

#### Start (forground)
opsbro agent start


#### List commands
opsbro

### Show agent state
opsbro agent info
# avec logs:
opsbro agent info --show-logs

#### Detect other nodes on the network
opsbro agent detect


#### Install/desinstall windows service
opsbro agent service-install
opsbro agent service-remove


#### Debuging
opsbro agent show-threads
opsbro agent list-follow-log
opsbro agent follow-log




#### Exec: ???


### Show checks/services states
opsbro state
Ex:
Services:
Checks:
        packs/linux/checks/cpu UNKNOWN  -
             /linux/checks/disks OK       - OK: / is at 7%
             /linux/checks/load-average OK       - OK: load is at 0.05


### Show cluster members:
opsbro members


### Join a cluster:
opsbro join XXXX:YY

### Generate keys:
opsbro keygen


### Force a node to leave
# TODO: master key si distant
opsbro leave XXXX:YY


### Show version:
  opsbro version


########## collectors
  opsbro collectors list
  opsbro collectors run sshd
  opsbro collectors show sshd

  (TODO) opsbro collectors show  --short

######### detectors
opsbro detectors list
opsbro detectors run



######## docker
opsbro docker show



####### evaluator
  opsbro evaluator list

  opsbro -D evaluator eval "fileexists('/tmp/')"
  (TODO)   opsbro evaluator eval "fileexists('/tmp/') || {{collector.blabla.toto}} > {{configuration.mykey.key2}}"  --explain

##### Zone
  opsbro zone change




############################ API
/agent/state/:nname         ==> state of services and checks
/agent/info                 ==> agent internal info
/agent/checks/:cname        ==> get all checks  (GET, DELETE, PUT)
/agent/services/:sname      ==> get all services  (GET, DELETE, PUT)
/agent/generators/:gname    ==> get generators

/agent/propagate/libexec    ==> save libexec into kv and push event about reloading it to other nodes
/agent/propagate/configuration    ==> save configuration into kv and push event about reloading it to other nodes

/agent/detectors/           ==> get all detectors definition
/agent/detectors/run/:dname ==> run detectors and show the results

/agent/evaluator/list       ==> list functions available for evaluation
/agent/evaluator/eval       ==> POST an command evaluation in expr POST param

# gossip
/agent/name                 ==> name of the node
/agent/leave/:nname         ==> ask a node to leave
/agent/members              ==> get all nodes
/agent/join/:other          ==> join another node ring

/configuration/update       ==> PUT (file) put a json and update the configuration
/configuration/             ==> GET configuration

/push-pull                  ==> merge nodes between nodes
/state/services/:sname      ==> états des services

/kv/:ukey                   ==> kv (GET, PUT, DELETE)
/kv/                        ==> GET all keys
/kv-meta/changed/:t         ==> key changed since t


# TS
/list/:key                  ==> TS get all keys for this name
/_ui_list/:key              ==> TS get get for the UI
/metric/find/               ==> TS GET list of metrics
/render/                    ==> GET/POST render call "à la graphite"


/stop                       ==> stop the  agent


/exec/:tag                  ==> (?cmd=XXXX) execute a command on the tag nodes
/exec-get/:cid              ==> GET hte result of a run


/collectors/:_id            ==> get collectors


/docker/                    ==> Bool sur connecté ou pas
/docker/containers/:_id     ==> list containers
/docker/images/:_id         ==> list images
/docker/stats/              ==> get docker stats

/packs                      ==> get all packs values

/threads                    ==> list all threads


/api                        ==> list all calls with doc


:2003 UDP/TCP  ==> graphite listener
:8025 UDP      ==> statsd listener
:23   UDP      ==> DNS listener






########### Repertoires

## Chemins principaux et ports:
/etc/opsbro/
           local.json    <== surcharge de conf genre chemins principaux and co

## Spécifique au node (basé sur hostname) aka son identitée
/var/lib/opsbro/identity/---HOSTNAME---/
									  checks.dat     <=== retention des checks
									  collectors.dat <=== retention collectors
									  incarnation    <=== incarnation number
									  nodes.json     <=== other nodes
									  server.key     <=== UUID
									  services.dat   <=== retention ds services

## lié au système et à l'installation même de l'agent


opsbro.sock     <=== socket de connection
last_alive     <=== synchro des KV
local-configuration/

					listeners/
                    		 websocket.json
                    		 statsd.json
                             graphite.json
                             dns.json
global-configuration/
					generators/(json+data)   <=== update de fichiers locaux
					handlers/                <=== comment réagir à un event. Exemple: email
					keys/ (priv/pub)         <=== couples of priv/pub allowed keys
					packs/                   <=== check+collectors
						  ---PNAME---/
						  			  package.json  <=== descriptif
						  			  collectors/collector_*py   <=== code pour collector
						  			  detectors/ (json)          <=== rule for detetion, based on collector data
						  			  services/ (json)           <=== exposed services to the outside world, linked to a check
						  			  checks/ (json)             <=== unitary checks, based on command or collectors data

##TODO: templates?

## Data
ttl
updates





########### zones
Besoins:
  > si pas de liens, zone fonctionnelle (donc besoin des conf poussées sur les sous zones)
  > info de vivant/mort purement local
  > besoin de savoir si relays OK ou pas, mais sans propagations aux sur-zones (on peux pas dead un sur relay dans la sur-zone, donc on ne propage que si zone ou sous zone)
  > besoin d'être sûr d'un relay de sur-zone est légitime


* Internet
   * ping/dead entre les noeuds d'une même zone
   * visibilité de la zone internet
   * et de ses sous zones
   * clé priv/pub internet
   * 1/X noeuds relays
      * ont la clé priv des sous zones

   > Shinken-solutions
      * ping/dead entre les noeuds de la sous zone
      * un/X noeud est relay
      * visibilité des sous zones
      * et des noeuds relay de la sur-zone
      * un relay mets tjs quelques sur-relay dans sa boucle
      * clé priv/pub shinken-solutions





#################### Parties
[ CORE ]
* gossip / appartenance
* raft (lock / master node )
* generator de configuration (fichier plein et partiel)
* check " à la nagios "
* check à l'évaluation + exemples
  ** fonctions pour l'évaluator à mettre dans des modules
* detectors + exemples de rules
* collectors + exemples
* KV pour la configuration
* storage TS (finesse + moyenne à l'heure)
* agrégats de checks? (AKA services?)
* handlers (notifications)
*


[ MODULES ]
* export nagios/shinken
* DNS local
* websocket
* entrée graphite
* sortie graphite
* entrée statsd
* storage TS C
* docker manager

[ OTHER ]
* UI





############### POC installer definitions:

  * un installeur pour X distros, + simple à lire
  * l'installeur peux avoir un if qui permet de savoir s'il s'active ou pas
  * l'installeur a une liste d'envrionnements qui vont pouvoir être matché dans l'ordre
     * le premier à matcher est pris, et stop la boucle
     * chaque env a un if pour savoir s'il est actif ou pas
     * si pas de if, True, (donc closera la liste)


installor:
    name: mysql
    note: This installer will install the mysql server if you set the server into the mysql user defined group. Support debian (8 and lower) and centos/redhat platforms.
    if:   "is_in_defined_group('mysql')"
    # You can set variables in order to not repeat yourself in the if rules
    variables:
        is_debian: "{{collector.system.os.linux.distribution}} == 'debian'"
        is_centos: "{{collector.system.os.linux.distribution}} == 'centos'"
        is_redhat: "{{collector.system.os.linux.distribution}} == 'redhat'"
    environments:
        - name: debian 8
          if: "{{variables.is_debian}} and {{collector.system.os.linux.major_version}} == 8"
          packages:
              - mysql-server-5.5
        - name: debian
          if: "{{variables.is_debian}}"
          packages:
              - mysql-server
        - name: centos
          if: "{{variables.is_centos}} or {{variables.is_redhat}}"
          packages:
              - mysql


####### Exemple de cas d'usage:
* on juste check, ou on fix si on peux (audit / enforce)
* est-ce que le fichier /etc/passwd est bien:
    * en 644 (rw,r,r)
    * user=root
    * group=root

compliance:
   display_name: passwd is root/644
   if:   "is_in_group('linux')"
   mode: enforce
   rule:
      file-rights:
           file: /etc/passwd
           owner: root
           group: root
           permissions: 644

* entrée dans /etc/hosts
  * https://github.com/jonhadfield/python-hosts
  * & https://github.com/hickeroar/win_inet_pton
* routing ipv4
* routing ipv6
* nfs client
* nfs server

* services
compliance:
   display_name: mysql is started
   if:   "is_in_defined_group('mysql')"
   mode: audit
   rule:
      services:
           name: mysql
           status: started

* ssh auth keys
* ssh parameters

* (security) file integrity
* cron jobs
* file system mounts points
* motd and pre-login banner

compliance:
   displayçname: motd is deployed
   if:   "is_in_group('linux')"
   mode: enforce
   rule:
      motd:
           text: "Welcome on server {{}}"

* user crées et valide
* groups crées et valide
* entrée sudoers
* le paquet X:
  * doit être installé
  * ne doit PAS être installé (exemple: pas de gcc sur les machines de production)

compliance:
   display_name: gcc not in production
   if:   "is_in_defined_group('production')"
   mode: audit
   rule:
      packages:
           name: gcc
           status: not-installed


* logout automatique: fichier ou clé de registre


compliance:
    display_name:
    note: This installer will install the mysql server if you set the server into the mysql user defined group. Support debian (8 and lower) and centos/redhat platforms.
    if:   "is_in_defined_group('mysql')"
    # You can set variables in order to not repeat yourself in the if rules
    variables:
        is_debian: "{{collector.system.os.linux.distribution}} == 'debian'"
        is_centos: "{{collector.system.os.linux.distribution}} == 'centos'"
        is_redhat: "{{collector.system.os.linux.distribution}} == 'redhat'"
    environments:
        - name: debian 8
          if: "{{variables.is_debian}} and {{collector.system.os.linux.major_version}} == 8"
          packages:
              - mysql-server-5.5
        - name: debian
          if: "{{variables.is_debian}}"
          packages:
              - mysql-server
        - name: centos
          if: "{{variables.is_centos}} or {{variables.is_redhat}}"
          packages:
              - mysql



Bon exemples d'utilisation pour du déploiement:
https://github.com/zwindler/ansible-deploy-elasticsearch
https://github.com/zwindler/ansible-deploy-kibana
https://github.com/zwindler/ansible-deploy-logstash


#### ROADMAP:


# 0.3: version actuelle

# 0.4: remise à niveau des zones, avec rajout des clés par zone
    * GOSSIP LEAVE appel à leave doit comporter la clé master/auth si distant
    * CLI: setter un paramètre de la conf locale (daemon & node, parameters c'est déjà fait)


# 0.5: UI remise à niveau, avec affichage mode "Bro"
    * UI: affichage clean & Bro
    * UI: affichage des checks
    * UI: affichage de "agent info"
    * UI voir si http://qrohlf.com/trianglify/#gettingstarted ne ferais pas un fond interessant


# 0.6: Rajout de la partie compliance
    * COMPLIANCE rajouter les objets et les modules de compliance
    * Installers exporter leur états dans le CLI
    * Compliance exporter leur états dans le CLI


# 0.7: Services/roles des nodes est disponible et utilisé côté UI
    * ROLES: redéfinir les "services" en autre choses qui se base sur une expression de dispo des checks
    * UI les roles sont visibles


# 0.8: Replication de l'installation & sharing/sync des packs
    * REPLICANT: installer: allow to keep the tar-ball of my own installation to allow another node to install myself
    * REPLICANT: installer: execute the tar-ball installer on another node (ssh based)
    * PACKS: permettre de synchronizer sa configuration globale avec les autres noeuds
    * PACKS: permettre de synchronizer sa configuration zone avec les autres nodes
    * PACKS: permettre de copier la configuration locale d'une autre noeud
    * PACKS UPDATE: permettre de mettre à jour tout ce qui est autre que paramètres d'un pack d'un niveau vers un autre niveau
    * CLI PACKS LIST des packs et leurs composants (même ceux pas pris, mais on montre qui gagne suivant le level)
       * ✔ opsbro pack list
       * opsbro pack list --level=global  (donc que global et en dessous)
    * ✔ CLI PACKS SHOW des packs finalement pris en compte et affichage de ce qu'il y a dedans et le paramétrage associé (paramètre par défaut/manquant, etc etc)
    * ✔ CLI PACKS OVERLOAD : prends un pack d'un niveau supérieur vers un niveau inférieur.
        * opsbro packs overload global.shinken --to-local (default)   ou --to-zone
    * CLI PACKS PROMOTE : prends un pack d'un niveau bas et l'augmente vers un niveau + haut
       * opsbro packs promote local.shinken --to-zone (defult niveau +1) ou --to-global
       * attention: nécessite la clé maitre de la zone/global pour être autoriser à faire ça
    * CLI PACKS COPY d'un pack sur un autre mais au même niveau
       * opsbro packs copy local.shinken  monitoring-generic
    * CLI PACKS DELETE d'un pack sur un level particulier
       * opsbro packs delete local.shinken
    * ✔ CLI PACKS EDIT d'un paramètre comme par exemple:
       * ✔ opsbro packs parameters set local.nagios.socket_path  /var/local/blabla.cmd
       * ✔ opsbro packs parameters get local.nagios.enable => true


# 0.9: Collectors : + de visibilité et de documentation
    * COLLECTORS : rajouter + d'états pour signaler si l'utilisateur a raté nun truc dans la conf ou s'il manque la discovery
       * missing configuration
       * not detected
       * error
       * ok
       * ??

    * COLLECTORS permettre un meilleur export des docs des functions de l'evaluater
    * COLLECTORS fonction pour get les données du collecter
    * COLLECTORS : avoir un moyen de choper X informations par exemple {{collectors.mongodb.dbstats.*.datasize}} renvoit une liste avec les valeurs, qu'on peux alors max().
    * COLLECTORS sortir les data importantes en "spec" genre distribution, CPUs ou Country
    * CLI définir une cli pour les TS (put/dump)


# 0.10: Fonctionnement sous windows
    * DRIVER windows (va falloir livrer des msi)
      ** ==> https://github.com/pahaz/sshtunnel/blob/master/appveyor.yml


# 0.11: Meilleur développement des users avec accès en ligne à la doc
    * API permettre un meilleur export des docs/specs des appels HTTP
    * CLI: rajouter un option --explain sur l'appel eval afin de voir la transformation et idéalement d'où vient l'info



# 1.0: tout ce qu'il y a au dessus


# X.X A discuter/MISC:
    * CLI définir une CLI pour les KV (put/list/get/delete)
    * MONITORING gérer les expressions d'application d'ensembles sur les groupes ( & | ! )
    * GROUPS séparer à l'affichage/fonctions les groupes configurés et les auto-groups détectés
        * defined_groups
        * detected_groups
    * RAFT avoir une valeur sure de stabilisation, et voir les indicateurs sur ce qui aide/diminue la stabilisation
    * PACK Azure
    * PACK ipmi (hardware stuff)
    * PACK smart (disques)
    * PACK raid linux (md)
    * PACK rabbitmq: prendre exemple sur les endpoints listés sur https://github.com/nagios-plugins-rabbitmq/nagios-plugins-rabbitmq/tree/master/scripts
    * SLACK bot de commande (écoute slack pour des ordres)
    * SLACK query dns (écoute slack pour des ordres)
    * DRIVER opensuse (zipper)
    * DRIVER fedora (dnf)
    * DRIVER alpine (pkg)
    * DRIVER core os
    * CORE enlever la dépendance à psutil sur les linux (/proc c'est pas là pour faire joli)
   * les fonctions non encore disponibles/exportées