nutools/lib/nulib/doc/deploydb/index.md

259 lines
7.4 KiB
Markdown

`deploydb` est un moyen de décrire des informations de déploiement ou de
configuration à propos de certains objets (hôtes, modules, webapps, woapps,
etc.)
# Syntaxe
Le format du fichier de configuration est volontairement simple. Toute la
logique est implémentée dans les clients qui accèdent à l'information stockée
Le fichier contient deux sortes d'informations:
* définition d'objet
* définition de faits
Les lignes vides ou commençant par '#' sont ignorées.
Si une ligne commence par un espace, elle est fusionnée avec la ligne
précédente.
## Définition d'objet
Une définition d'objet a le format suivant:
~~~
otype oid[=values] [ATTRS...] [LINKS...]
~~~
`otype`
: type d'objet à créer ou à mettre à jour
`oid`
: identifiant de l'objet à créer ou à mettre à jour
`values`
: valeurs de l'objet, séparées par des virgules
`ATTR`
: attribut de l'objet
`LINK`
: définition d'objet lié
Une définition d'attribut a l'un des formats suivants:
~~~
name[=value]
name+[=value]
name-[=value]
name%[=value]
~~~
Les attributs sont multivalués, et par défaut, on rajoute la nouvelle valeur aux
valeurs existantes sauf si elle existe déjà dans l'attribut.
value vaut par défaut 'true', ce qui n'est pas la même chose qu'une valeur
vide. comparer les deux définitions suivantes:
~~~
first # first vaut 'true'
second= # second vaut ''
~~~
Les types de mise à jour valides sont:
* `=` ajout de la valeur si l'attribut ne la contient pas déjà
* `+=` ajout inconditionnel d'une valeur à l'attribut
* `-=` suppression d'une valeur de l'attribut
* `%=` remettre à zéro l'attribut d'abord
Ainsi, les définitions suivantes sont équivalentes deux à deux:
~~~
attr=value attr=value # le doublon est supprimé
attr=value # c'est comme si on ne spécifie la valeur qu'une seule fois
attr=value attr%=first attr=second
attr=value attr-=value attr=first attr=second
~~~
Une définition de lien a le format suivant:
~~~
-otype oids... [ATTRS...]
~~~
`otype`
: type de l'objet lié
`oids`
: liste d'identifiants d'objets liés séparés par des virgules
`ATTR`
: attribut à rajouter à la définition du lien
Voici un exemple complet:
~~~
humain bob nom=Payet prenom=Robert
age=42
desc="un humain qui a un père, une mère et deux voitures"
-humain eric type=pere
-humain martine type=mere
-vehicule titine,bumblebee
humain eric nom=Payet prenom=Eric
humain martine nom=Payet prenom="Martine Joséphine"
vehicule titine marque=Citroen immatriculation=BX-467-PM
vehicule bumblebee marque=Camaro type=autobot
~~~
## Définition de faits
Un fait est l'affirmation d'un lien d'action ou d'état entre deux objets,
décrit par un verbe. Par exemple, pour décrire le fait que bob mange une
tarte, on écrirait:
~~~
humain bob
aliment tarte
-humain bob
mange -aliment tarte
~~~
Une définition de fait a le format suivant:
~~~
-sotype soids... [DEFATTRS...]
verb -totype toids... [FACTATTRS...]
...
~~~
`sotype`
`totype`
: types d'objets source et cible
`soid`
`toid`
: identifiants des objets source et cible
`verb`
: identifiant du lien entre la source et la destination. en général, il s'agit
d'un verbe d'action ou d'état conjugué à la 3ème personne du singulier.
si le verbe commence par `~` alors la définition est inversée. par exemple,
les deux faits suivants sont rigoureusement équivalents:
~~~
-otype src verb -otype dest
-otype dest ~verb -otype src
~~~
cela permet de supporter les cas où la définition inverse est plus facile.
`DEFATTR`
: attribut pour tous les faits définis dans cette déclaration
`FACTATTR`
: attribut spécifique au fait défini
# deploydb
Le script `deploydb` permet d'interroger la base de données ou de lancer une
fonction pour traiter le contenu de la base de données
Dans ce document, `DEPLOYDBDIR` désigne le répertoire du script `deploydb`
Options
`-c, --config CONFIG`
: spécifier un fichier de configuration à charger. la valeur par défaut est
`deploydb.conf`
si le fichier de configuration n'est pas spécifié ou est spécifié sans chemin,
`deploydb:path` est initialisé avec la valeur par défaut suivante:
~~~
~/etc/deploydb:/var/local/deploydb:DEPLOYDBDIR
~~~
sinon, `deploydb:path` est initialisé avec le répertoire de CONFIG
`-m, --module MODULE`
: spécifier un module supplémentaire à charger. le module python effectivement
cherché dans le path et chargé est `MODULE_module`. La liste par défaut des
modules à charger contient un seul élément, `base`, ce qui signifie que le
module `base_module` est chargé. Les modules permettent de définir de la
logique pour les objets, ou l'outil à lancer.
`-r, --func FUNC`
: spécifier le nom de la fonction à lancer après le chargement des modules et
des fichiers de configuration. La valeur par défaut est `base.query`, qui
interroge la base de données et affiche son contenu.
La fonction est appelée avec les arguments de la ligne de commande, sans les
options, qui sont traitées en amont.
`--dump`
: afficher le contenu complet de la base de données, pour débugger. ignorer
l'option `-r`
# Module base
Le module `base` chargé par défaut définit
* les objets de type `deploydb`, `host`
* la fonction `query()`
## deploydb
En créant des instances de cet objet avec des identifiants normalisés, il est
possible de modifier la configuration.
`deploydb path dir=CONFDIR`
: définir les répertoires de recherche pour les fichiers de configuration
spécifiés sans chemin. dans ce document, cette valeur est appelée
`deploydb:path`
`deploydb include file=CONFIG`
: définir des fichiers de configuration supplémentaire à charger. Si les
fichiers sont spécifiés sans chemin, il sont cherchés dans `deploydb:path`
`deploydb loadcsv file=CSVFILE`
: charger des définitions d'objets depuis des fichiers CSV. Si les fichiers sont
spécifiés sans chemin, ils sont cherchés dans `deploydb:path`
L'attribut `otype_col` qui vaut par défaut `otype` permet de définir la
colonne qui contient le type d'objet. L'attribut `otype` permet de spécifier
le type d'objet si la colonne n'existe pas dans le fichier.
L'attribut `oid_col` qui vaut par défaut `oid` permet de définir la colonne
qui contient l'identifiant d'objet à créer.
Toutes les autres colonnes du fichier sont utilisées pour définir les
attributs des objets.
## host
Cet objet définit un hôte vers lequel on peut par exemple déployer un artifact.
`host * domain=DOMAIN.TLD`
: définir un domaine par défaut pour tous les hôtes spécifiés sans domaine
Les attributs suivants sont supportés:
`host`
: nom d'hôte. le domaine par défaut est ajouté le cas échéant. pour ne pas
rajouter un domaine, spécifier le nom avec un point final e.g `localhost.`
`hostname`
: nom d'hôte sans le domaine
`domain`
: domaine sans le nom d'hôte
`ip`
: adresse IP de l'hôte
Si seul `host` est spécifié, `hostname` et `domain` sont calculés en fonction de
sa valeur.
Si seul `hostname` est spécifié, `host` est calculé en fonction de sa valeur et
de celle de `domain`
Si `ip` n'est pas spécifié, une résolution DNS est effectuée pour déterminer
l'adresse de `host`
Si l'objet est défini sans valeurs, alors la valeur finale est la liste des hôtes.
## base.query()
Interroger la base de données
XXX déterminer le format des requêtes
-*- coding: utf-8 mode: markdown -*- vim:sw=4:sts=4:et:ai:si:sta:fenc=utf-8:noeol:binary