Déplacement de la documentation

This commit is contained in:
Benjamin Bohard 2021-12-13 08:34:25 +01:00
parent 59ae3af3c6
commit f5ef8983d8
2 changed files with 307 additions and 301 deletions

301
README.md
View File

@ -2,304 +2,5 @@
Utilitaires pour gérer les modules EOLE à partir dansible
## Alimentation de la configuration de Zéphir
### zephir_etab
La description des éléments de la collection se trouve dans le fichier cadoles/eole/README.md
Le module a pour but la gestion des établissements.
Un établissement est identifié par un numéro *rne*.
``` plantuml
object etablissements
etablissements : rne (character varying(8) not null pkey)
etablissements : libelle (character varying(200) not null)
etablissements : type (integer not null references types_etab)
etablissements : ville (character varying(50) not null)
etablissements : cp (character varying(5) not null)
etablissements : adresse (character varying(100))
etablissements : tel (character varying(20))
etablissements : fax (character varying(20))
etablissements : mail (character varying(100))
etablissements : responsable (character varying(30))
etablissements : remarques (text)
object types_etab
types_etab : id (integer, not null)
types_etab : libelle (character varying(80), not null)
```
Quoique les champs `libelle`, `type`, `ville`, `cp` soient également obligatoires à la création, ils ne sont pas distinctifs de létablissement.
Le champ type fait référence à la table `types_etab` qui contient déjà des valeurs appropriées pour le contexte de lÉducation nationale.
Aucune API nest prévue pour modifier cette table.
#### Fonctionnement du module
Le module tire partie de lAPI XMLRPC authentifiée accessible localement.
Le module nécessite donc, outre les paramètres attendus par la base de données, des paramètres dauthentification.
##### Implémentation cible
``` flowchart
st=>start: Entrée
e=>end: Sortie
createproxy=>operation: Création du proxy
listetabs=>operation: Liste des établissements
etabexist=>condition: Létablissement existe déjà ?
samedata=>condition: Les données sont les mêmes ?
doingnothing=>operation: Ne rien faire
modifydata=>operation: Modification des données
createetab=>operation: Création de létablissement
st->createproxy
createproxy->listetabs
listetabs->etabexist
etabexist(yes)->samedata
samedata(yes)->doingnothing
doingnothing->e
samedata(no)->modifydata
modifydata->e
etabexist(no)->createetab
createetab->e
```
##### Implémentation actuelle
``` flowchart
st3=>start: start run_module
io5=>inputoutput: input:
op8=>operation: key_mapping = {'rne': 'rne', 'libelle': 'libelle', 'ville': 'ville', 'cp': 'code_postal', 'type': 'etab_type', 'adresse': 'adresse', 'tel': 'tel', 'fax': 'fax', 'mail': 'mail', 'responsable': 'responsable', 'remarques': 'remarques'}
op10=>operation: module_args = dict(zephir_user=dict(type='str', required=True), zephir_user_password=dict(type='str', required=True), rne=dict(type='str', required=True), libelle=dict(type='str', required=True), ville=dict(type='str', required=True), code_postal=dict(type='str', required=True), etab_type=dict(type='int', required=True), adresse=dict(type='str', required=False, default=''), tel=dict(type='str', required=False, default=''), fax=dict(type='str', required=False, default=''), mail=dict(type='str', required=False, default=''), responsable=dict(type='str', required=False, default=''), remarques=dict(type='str', required=False, default=''), state=dict(type='str', required=True, default='present'))
op12=>operation: result = dict(changed=False, rne=None, msg='')
op14=>operation: module = AnsibleModule(argument_spec=module_args, supports_check_mode=True)
cond17=>operation: module.exit_json(**result) if module.check_mode
op27=>operation: port_zephir = str((int(config.PORT_ZEPHIR) + 1))
op29=>operation: proxy_addr = 'http://{0}:{1}@localhost:{2}/'.format(module.params['zephir_user'], module.params['zephir_user_password'], port_zephir)
op31=>operation: proxy = EoleProxy(proxy_addr)
op33=>operation: (return_code, etabs) = proxy.etabs.get_etab()
cond36=>operation: etabs = {m['rne']: m for m in etabs} if return_code
cond47=>condition: if (module.params['rne'] in etabs)
op51=>operation: result['msg'] = 'Etab {} already exists'.format(module.params['rne'])
op53=>operation: data_change = {}
cond56=>condition: for (key, value) in etabs[module.params['rne']]
cond73=>operation: data_change[key] = module.params[key_mapping[key]] if (module.params[key_mapping[key]] != value)
cond86=>operation: module.exit_json(**result) if (not data_change)
op99=>operation: (return_code, proxy_msg) = proxy.etabs.add_etab(module.params['rne'], module.params['libelle'], module.params['adresse'], module.params['ville'], module.params['code_postal'], module.params['tel'], module.params['fax'], module.params['mail'], module.params['responsable'], module.params['remarques'], module.params['etab_type'])
cond102=>condition: if return_code
op106=>operation: result['changed'] = True
op108=>operation: result['rne'] = proxy_msg
op110=>operation: result['msg'] = 'Etab {}'.format(module.params['rne'])
sub119=>subroutine: module.exit_json(**result)
e121=>end: end run_module
op114=>operation: result['msg'] = 'Etab {} not created: {}'.format(module.params['libelle'], proxy_msg)
sub116=>subroutine: module.fail_json(**result)
st3->io5
io5->op8
op8->op10
op10->op12
op12->op14
op14->cond17
cond17->op27
op27->op29
op29->op31
op31->op33
op33->cond36
cond36->cond47
cond47(yes)->op51
op51->op53
op53->cond56
cond56(yes)->cond73
cond73->cond56
cond56(no)->cond86
cond86->op99
op99->cond102
cond102(yes)->op106
op106->op108
op108->op110
op110->sub119
sub119->e121
cond102(no)->op114
op114->sub116
sub116->sub119
cond47(no)->op99
```
### zephir_serveur
### zephir_module
### zephir_variante
## Configuration dun serveur
### creoleset
Le module a pour but de permettre la modification des variables de configuration creole.
La difficulté réside dans les liens de dépendances qui peuvent exister entre variables et la nécessité de pouvoir faire des modifications par bloc, de façon atomique.
``` flowchart
start=>start: début dexécution
e=>end: fin dexécution
creole_loader=>operation: Création de lobjet config en lecture/écriture
tri_variables=>operation: Tri des variables à modifier
start->creole_loader
creole_loader->tri_variables
tri_variables->e
```
``` yaml
---
- hosts: module_test
tasks:
- name: Test if minimal config is already done
stat:
path: "/etc/eole/config.eol"
register: configeol
- name: Configuration minimale
creoleset:
variables:
- name: "numero_etab"
value: "0000000B"
- name: "libelle_etab"
value: "bbohard_etab"
- name: "nom_academie"
value: "bbohard"
- name: "nom_domaine_local"
value: "bbohard.lan"
- name: "eth0_method"
value: "dhcp"
- name: "ip_ssh_eth0"
value:
- "192.168.122.0"
- name: "netmask_ssh_eth0"
value:
- "255.255.255.0"
- name: "ip_admin_eth0"
value: "192.168.122.0"
- name: "netmask_admin_eth0"
value: "255.255.255.0"
- name: "activer_exim_relay_smtp"
value: "non"
- name: "nom_machine"
value: "{{ hostname }}"
when: not configeol.stat.exists
- name: Set some hostnames
creoleset:
variables:
- name: activer_ajout_hosts
value: oui
- name: nom_court_hosts
value:
- minio-a1
- minio-a2
- minio-b1
- minio-b2
- name: nom_long_hosts
value:
- minio-a1.cadoles.lan
- minio-a2.cadoles.lan
- minio-b1.cadoles.lan
- minio-b2.cadoles.lan
- name: adresse_ip_hosts
value:
- 10.10.0.1
- 10.10.0.2
- 10.10.0.3
- 10.10.0.4
- name: Configuration dune variable isolée simple
creoleset:
variables:
- name: "libelle_etab"
value: "etab_test"
- name: Configuration dune variable isolée multi
creoleset:
variables:
- name: "adresse_ip_dns"
value:
- "1.1.1.1"
- "8.8.8.8"
- name: Configuration dun groupe de variables
creoleset:
variables:
- name: "ip_ssh_eth0"
value:
- "192.168.0.0"
- name: "netmask_ssh_eth0"
value:
- "255.255.0.0"
- name: Debug
shell:
cmd: "CreoleGet ip_ssh_eth0"
- name: Configuration avec variable nécessitant activation
creoleset:
variables:
- name: "additional_repository_name"
value: "Cadoles unstable"
- name: "additional_repository_source"
value: "deb https://vulcain.cadoles.com 2.7.0-unstable main"
- name: "additional_repository_key_type"
value: "URL de la clé"
- name: "additional_repository_key_url"
value: "https://vulcain.cadoles.com/cadoles.gpg"
state: present
- name: Configuration ajoutée
creoleset:
variables:
- name: 'additional_repository_name'
value: 'mariadb'
- name: 'additional_repository_source'
value: 'deb http://mariadb.mirrors.ovh.net/MariaDB/repo/10.3/ubuntu bionic main'
- name: 'additional_repository_key_type'
value: 'serveur de clés'
- name: 'additional_repository_key_signserver'
value: 'hkp://keyserver.ubuntu.com:80'
- name: 'additional_repository_key_fingerprint'
value: 'F1656F24C74CD1D8'
state: present
- name: Configuration vidée
creoleset:
variables:
- name: 'additional_repository_name'
value: []
- name: 'additional_repository_source'
value: []
- name: 'additional_repository_key_type'
value: []
- name: 'additional_repository_key_fingerprint'
value: []
- name: 'additional_repository_key_url'
value: []
- name: Configuration ajoutée
creoleset:
variables:
- name: "ip_ssh_eth0"
value: "10.253.30.0"
- name: "netmask_ssh_eth0"
value: "255.255.255.0"
state: present
- name: idempotence
creoleset:
variables:
- name: "ip_ssh_eth0"
value:
- "192.168.0.0"
- "10.10.0.0"
- name: "netmask_ssh_eth0"
value:
- "255.255.0.0"
- "255.255.255.0"
```
### zephir_register
Module basé sur pexpect
Il met en œuvre une série de questions articulées entre elles pour prendre en compte les enchaînements.

View File

@ -1,3 +1,308 @@
# Ansible Collection - cadoles.eole
Documentation for the collection.
Documentation for the collection.
## Alimentation de la configuration de Zéphir
### zephir_etab
Le module a pour but la gestion des établissements.
Un établissement est identifié par un numéro *rne*.
``` plantuml
object etablissements
etablissements : rne (character varying(8) not null pkey)
etablissements : libelle (character varying(200) not null)
etablissements : type (integer not null references types_etab)
etablissements : ville (character varying(50) not null)
etablissements : cp (character varying(5) not null)
etablissements : adresse (character varying(100))
etablissements : tel (character varying(20))
etablissements : fax (character varying(20))
etablissements : mail (character varying(100))
etablissements : responsable (character varying(30))
etablissements : remarques (text)
object types_etab
types_etab : id (integer, not null)
types_etab : libelle (character varying(80), not null)
```
Quoique les champs `libelle`, `type`, `ville`, `cp` soient également obligatoires à la création, ils ne sont pas distinctifs de létablissement.
Le champ type fait référence à la table `types_etab` qui contient déjà des valeurs appropriées pour le contexte de lÉducation nationale.
Aucune API nest prévue pour modifier cette table.
#### Fonctionnement du module
Le module tire partie de lAPI XMLRPC authentifiée accessible localement.
Le module nécessite donc, outre les paramètres attendus par la base de données, des paramètres dauthentification.
##### Implémentation cible
``` flowchart
st=>start: Entrée
e=>end: Sortie
createproxy=>operation: Création du proxy
listetabs=>operation: Liste des établissements
etabexist=>condition: Létablissement existe déjà ?
samedata=>condition: Les données sont les mêmes ?
doingnothing=>operation: Ne rien faire
modifydata=>operation: Modification des données
createetab=>operation: Création de létablissement
st->createproxy
createproxy->listetabs
listetabs->etabexist
etabexist(yes)->samedata
samedata(yes)->doingnothing
doingnothing->e
samedata(no)->modifydata
modifydata->e
etabexist(no)->createetab
createetab->e
```
##### Implémentation actuelle
``` flowchart
st3=>start: start run_module
io5=>inputoutput: input:
op8=>operation: key_mapping = {'rne': 'rne', 'libelle': 'libelle', 'ville': 'ville', 'cp': 'code_postal', 'type': 'etab_type', 'adresse': 'adresse', 'tel': 'tel', 'fax': 'fax', 'mail': 'mail', 'responsable': 'responsable', 'remarques': 'remarques'}
op10=>operation: module_args = dict(zephir_user=dict(type='str', required=True), zephir_user_password=dict(type='str', required=True), rne=dict(type='str', required=True), libelle=dict(type='str', required=True), ville=dict(type='str', required=True), code_postal=dict(type='str', required=True), etab_type=dict(type='int', required=True), adresse=dict(type='str', required=False, default=''), tel=dict(type='str', required=False, default=''), fax=dict(type='str', required=False, default=''), mail=dict(type='str', required=False, default=''), responsable=dict(type='str', required=False, default=''), remarques=dict(type='str', required=False, default=''), state=dict(type='str', required=True, default='present'))
op12=>operation: result = dict(changed=False, rne=None, msg='')
op14=>operation: module = AnsibleModule(argument_spec=module_args, supports_check_mode=True)
cond17=>operation: module.exit_json(**result) if module.check_mode
op27=>operation: port_zephir = str((int(config.PORT_ZEPHIR) + 1))
op29=>operation: proxy_addr = 'http://{0}:{1}@localhost:{2}/'.format(module.params['zephir_user'], module.params['zephir_user_password'], port_zephir)
op31=>operation: proxy = EoleProxy(proxy_addr)
op33=>operation: (return_code, etabs) = proxy.etabs.get_etab()
cond36=>operation: etabs = {m['rne']: m for m in etabs} if return_code
cond47=>condition: if (module.params['rne'] in etabs)
op51=>operation: result['msg'] = 'Etab {} already exists'.format(module.params['rne'])
op53=>operation: data_change = {}
cond56=>condition: for (key, value) in etabs[module.params['rne']]
cond73=>operation: data_change[key] = module.params[key_mapping[key]] if (module.params[key_mapping[key]] != value)
cond86=>operation: module.exit_json(**result) if (not data_change)
op99=>operation: (return_code, proxy_msg) = proxy.etabs.add_etab(module.params['rne'], module.params['libelle'], module.params['adresse'], module.params['ville'], module.params['code_postal'], module.params['tel'], module.params['fax'], module.params['mail'], module.params['responsable'], module.params['remarques'], module.params['etab_type'])
cond102=>condition: if return_code
op106=>operation: result['changed'] = True
op108=>operation: result['rne'] = proxy_msg
op110=>operation: result['msg'] = 'Etab {}'.format(module.params['rne'])
sub119=>subroutine: module.exit_json(**result)
e121=>end: end run_module
op114=>operation: result['msg'] = 'Etab {} not created: {}'.format(module.params['libelle'], proxy_msg)
sub116=>subroutine: module.fail_json(**result)
st3->io5
io5->op8
op8->op10
op10->op12
op12->op14
op14->cond17
cond17->op27
op27->op29
op29->op31
op31->op33
op33->cond36
cond36->cond47
cond47(yes)->op51
op51->op53
op53->cond56
cond56(yes)->cond73
cond73->cond56
cond56(no)->cond86
cond86->op99
op99->cond102
cond102(yes)->op106
op106->op108
op108->op110
op110->sub119
sub119->e121
cond102(no)->op114
op114->sub116
sub116->sub119
cond47(no)->op99
```
### zephir_serveur
### zephir_module
### zephir_variante
## Configuration dun serveur
### creoleset
Le module a pour but de permettre la modification des variables de configuration creole.
La difficulté réside dans les liens de dépendances qui peuvent exister entre variables et la nécessité de pouvoir faire des modifications par bloc, de façon atomique.
``` flowchart
start=>start: début dexécution
e=>end: fin dexécution
creole_loader=>operation: Création de lobjet config en lecture/écriture
tri_variables=>operation: Tri des variables à modifier
start->creole_loader
creole_loader->tri_variables
tri_variables->e
```
``` yaml
---
- hosts: module_test
tasks:
- name: Test if minimal config is already done
stat:
path: "/etc/eole/config.eol"
register: configeol
- name: Configuration minimale
creoleset:
variables:
- name: "numero_etab"
value: "0000000B"
- name: "libelle_etab"
value: "bbohard_etab"
- name: "nom_academie"
value: "bbohard"
- name: "nom_domaine_local"
value: "bbohard.lan"
- name: "eth0_method"
value: "dhcp"
- name: "ip_ssh_eth0"
value:
- "192.168.122.0"
- name: "netmask_ssh_eth0"
value:
- "255.255.255.0"
- name: "ip_admin_eth0"
value: "192.168.122.0"
- name: "netmask_admin_eth0"
value: "255.255.255.0"
- name: "activer_exim_relay_smtp"
value: "non"
- name: "nom_machine"
value: "{{ hostname }}"
when: not configeol.stat.exists
- name: Set some hostnames
creoleset:
variables:
- name: activer_ajout_hosts
value: oui
- name: nom_court_hosts
value:
- minio-a1
- minio-a2
- minio-b1
- minio-b2
- name: nom_long_hosts
value:
- minio-a1.cadoles.lan
- minio-a2.cadoles.lan
- minio-b1.cadoles.lan
- minio-b2.cadoles.lan
- name: adresse_ip_hosts
value:
- 10.10.0.1
- 10.10.0.2
- 10.10.0.3
- 10.10.0.4
- name: Configuration dune variable isolée simple
creoleset:
variables:
- name: "libelle_etab"
value: "etab_test"
- name: Configuration dune variable isolée multi
creoleset:
variables:
- name: "adresse_ip_dns"
value:
- "1.1.1.1"
- "8.8.8.8"
- name: Configuration dun groupe de variables
creoleset:
variables:
- name: "ip_ssh_eth0"
value:
- "192.168.0.0"
- name: "netmask_ssh_eth0"
value:
- "255.255.0.0"
- name: Debug
shell:
cmd: "CreoleGet ip_ssh_eth0"
- name: Configuration avec variable nécessitant activation
creoleset:
variables:
- name: "additional_repository_name"
value: "Cadoles unstable"
- name: "additional_repository_source"
value: "deb https://vulcain.cadoles.com 2.7.0-unstable main"
- name: "additional_repository_key_type"
value: "URL de la clé"
- name: "additional_repository_key_url"
value: "https://vulcain.cadoles.com/cadoles.gpg"
state: present
- name: Configuration ajoutée
creoleset:
variables:
- name: 'additional_repository_name'
value: 'mariadb'
- name: 'additional_repository_source'
value: 'deb http://mariadb.mirrors.ovh.net/MariaDB/repo/10.3/ubuntu bionic main'
- name: 'additional_repository_key_type'
value: 'serveur de clés'
- name: 'additional_repository_key_signserver'
value: 'hkp://keyserver.ubuntu.com:80'
- name: 'additional_repository_key_fingerprint'
value: 'F1656F24C74CD1D8'
state: present
- name: Configuration vidée
creoleset:
variables:
- name: 'additional_repository_name'
value: []
- name: 'additional_repository_source'
value: []
- name: 'additional_repository_key_type'
value: []
- name: 'additional_repository_key_fingerprint'
value: []
- name: 'additional_repository_key_url'
value: []
- name: Configuration ajoutée
creoleset:
variables:
- name: "ip_ssh_eth0"
value: "10.253.30.0"
- name: "netmask_ssh_eth0"
value: "255.255.255.0"
state: present
- name: idempotence
creoleset:
variables:
- name: "ip_ssh_eth0"
value:
- "192.168.0.0"
- "10.10.0.0"
- name: "netmask_ssh_eth0"
value:
- "255.255.0.0"
- "255.255.255.0"
```
La configuration des groupes nécessite de toujours renseigner les variables maîtres
### zephir_register
Module basé sur pexpect
Il met en œuvre une série de questions articulées entre elles pour prendre en compte les enchaînements.