Qu’est-ce que Ansible ?

Ansible est un outil écrit en Python qui permet de faire des déploiements.

Ansible se sert de deux fichiers de configuration pour fonctionner.

Le premier est l’inventory, il regroupe les adresses réseau des machines qu’on souhaite gérer.

Le second est un playbook, il agit comme un script qu’on pourra exécuter sur n’importe laquelle des machines de l’inventory.

Tous les fichiers de configuration d’Ansible sont au format YAML.

À partir de ces deux fichiers Ansible établit des connexions SSH sur les machines de notre choix (depuis l’inventory), transfert le playbook sur les machines connectées, l’exécute et enfin fait remonter les résultats.

Cette approche permet de facilement réaliser n’importe quel type de déploiement à petite comme à grande échelle en écrivant un seul script, et en utilisant une seule commande.

Les résultats et les erreurs (si il y en a) sont tous remontés une fois que tout est fini.


Ansible est écrit en Python et l’utilise également pour exécuter les playbooks sur les machines, il faut donc que ce dernier soit installé sur les systèmes où l’on veut faire des déploiements.

Les actions qu’on peut demander à Ansible de réaliser sont des modules, qui permettent de réaliser une tâche spécifique.

Chaque tâche dans le playbook utilise un module, et on peut ajouter autant de tâches qu’on a besoin, comme dans un script.

Parmi les modules fournis avec Ansible on peut par exemple exécuter des commandes shell, manipuler des fichiers, en télécharger, etc.

L’intérêt du fonctionnement par modules c’est que tout le monde peut en écrire et on peut utiliser ceux qui sont publiés sur Ansible Galaxy par la communauté.

Cette plateforme regroupe des centaines de collections, qui contiennent un ou plusieurs modules. Il en existe déjà pour énormément de services et applications de toutes sortes (bien trop pour tous les citer ici).

Il y a également des collections fournies par IBM pour interagir avec leurs systèmes, notamment l’IBM i avec la collection power_ibmi.


Pour réaliser des plus petites tâches rapidement il est possible d’exécuter des commandes dites ad hoc. L’exécution sera la même qu’avec un playbook, sauf qu’il n’y aura pas besoin de créer un playbook, à la place on donne les paramètres du module directement dans la ligne de commande.

Cette méthode est très utile pour des actions simples et moins fréquentes, par exemple pour redémarrer toutes les machines d’un inventory.

Quelques exemples simples

Voici à quoi ressemble un inventory très simple qui liste deux machines (machineA et machineB).

all:
    hosts:
        machineA:
            ansible_host: 10.0.0.1
        machineB:
            ansible_host: 10.0.0.2
    vars:
        ansible_ssh_user: root

La partie vars permet de donner des paramètres supplémentaires pour les connexions SSH et l’exécution des modules.

Le paramètre ansible_ssh_user permet d’indiquer en tant que quel utilisateur Ansible doit se connecter par SSH, ici nous serons root.


Voilà désormais un playbook très simple également qui ne fait qu’un simple ping, cela permet de vérifier si Ansible peut se connecter aux machines et exécuter un playbook.

- name: playbook ping
  gather_facts: no
  hosts: all
  tasks:
  - ping:

Le paramètre gather_facts est par défaut configuré sur yes. Le gather facts récupère des informations sur le système où le playbook s’exécute (système d’exploitation, environnement, versions de Python/Ansible, etc) qu’on peut ensuite utiliser dans le playbook ou afficher. Ici on ne souhaite faire qu’un ping pour vérifier qu’Ansible fonctionne bien, on peut désactiver le gather facts puisqu’on ne s’en sert pas.

Le paramètre hosts permet d’indiquer sur quels machines de l’inventory ce playbook doit être exécuté par défaut.

Le paramètre tasks liste chaque tâche à exécuter (avec le nom du module). Ici on utilise le module ansible.builtin.ping qu’on peut abréger en ping.


Pour exécuter ce playbook on utilise la commande ansible-playbook -i inventory.yml playbook.yml (en remplaçant bien entendu les noms des fichiers par ceux que vous avez).

Voici le résultat qu’on obtient avec l’inventory et le playbook précédents :

$ ansible-playbook -i inventory.yml ping.yml

PLAY [playbook ping] *****************************************************************

TASK [ping] **************************************************************************
ok: [machineA]
ok: [machineB]

PLAY RECAP ***************************************************************************
machineA  : ok=1  changed=0  unreachable=0  failed=0  skipped=0  rescued=0  ignored=0
machineB  : ok=1  changed=0  unreachable=0  failed=0  skipped=0  rescued=0  ignored=0

Ansible nous rapporte que la tâche ping a réussi sur les deux machines. La partie PLAY RECAP résume les résultats de toutes les tâches.


L’équivalent de ce playbook en mode Ad Hoc est la commande :

$ ansible -i inventory.yml -m ping all

Le dernier paramètre all correspond au paramètre hosts du playbook, il indique d’exécuter la commande sur tous les hôtes présents dans l’inventory.

Le paramètre -m ping indique quel module utiliser (la documentation sur les commandes ad hoc est disponible ici).

Commande ad hoc de ping

Ansible for i

IBM fournit la collection power_ibmi qui contient beaucoup de modules pour interagir avec les IBM i, la documentation se trouve ici, et la référence des modules ici.

Cette collection est d’ailleurs disponible sur Github ici (avec plusieurs exemples et autres ressources).


Voici un exemple de playbook qui utilise cette collection, plus particulièrement le module ibmi_sysval. Ce playbook va récupérer une valeur système puis faire une assertion de sa valeur.

- hosts: all
  gather_facts: no
  collections:
   - ibm.power_ibmi

  tasks:
  - name: Vérification CCSID
    ibmi_sysval:
      sysvalue:
        - {'name': 'qccsid', 'expect': '1147'}

Le paramètre collections indique qu’il faut d’abord chercher le module ibmi_sysval dans les collections énumérées (dans l’ordre) mais cette partie est optionnelle (comme indiqué dans la documentation ici).

Puis on indique que l’élément nommé qccsid dans la variable de retour sysvalue doit correspondre à la valeur 1147.

Voilà le résultat qu’on obtient lorsque la valeur système correspond :

$ ansible-playbook -i inventory.yml assert_ccsid.yml

PLAY [all] ***************************************************************************

TASK [Vérification CCSID] ************************************************************
ok: [machineA]
ok: [machineB]

PLAY RECAP ***************************************************************************
machineB : ok=1  changed=0  unreachable=0  failed=0  skipped=0  rescued=0  ignored=0
machineA : ok=1  changed=0  unreachable=0  failed=0  skipped=0  rescued=0  ignored=0

Et si le QCCSID ne correspond pas Ansible affiche une erreur à la place de ok: [machine], au format JSON :

fatal: [machineA]: FAILED! =>
{
	"changed": false,
	"fail_list": [{
		"check": "equal",
		"compliant": false,
		"expect": "1147",
		"msg": "Compliant check failed",
		"name": "QCCSID",
		"rc": -2,
		"type": "10i0",
		"value": "65535"
	}],
	"message": "",
	"msg": "non-zero return code when get system value:-2",
	"rc": -2,
	"stderr": "non-zero return code when get system value:-2",
	"stderr_lines": ["non-zero return code when get system value:-2"],
	"sysval": []
}

Note: Dans le terminal cette erreur est souvent affichée sans indentation ni retours à la ligne.

Ici on peut voir que l’assertion a échoué, la valeur système était 65535, mais le playbook s’attendait à ce qu’elle soit 1147.


Il y a de nombreux autres cas d’usage, plusieurs exemples sont disponibles sur le dépôt Github ansible-for-i.

Il y a quelques exemples pour des utilisations spécifiques ici, et d’autres exemples de playbooks ici.

Interfaces graphiques : AWX et Tower

Ansible est un outil qui s’utilise dans le terminal, mais il existe deux solutions qui fournissent une interface graphique plus intuitive en plus d’autres fonctionnalités (planification de tâches, gestion de plusieurs utilisateurs et de leurs droits, notifications).

Ces deux solutions sont AWX et Tower, les deux sont très similaires : AWX est un projet open-source (disponible ici), et Tower (disponible ici) est une solution qui est basée sur AWX mais qui nécessite une licence.

La principale différence entre les deux est que Tower subit beaucoup plus de tests pour être plus stable et vous pouvez recevoir de l’aide du support technique Red Hat si besoin. AWX en revanche est moins testé et donc plus susceptible de rencontrer des instabilités, il n’y a également pas de support technique pour AWX.

Si la stabilité est une nécessité (comme en environnement de production) mieux vaut s’orienter vers Tower.

AWX est compatible sur Linux (les distributions les plus populaires devraient toutes le faire fonctionner), Tower est également compatible sur Linux mais est beaucoup restreint. Actuellement ce dernier n’est compatible que sur Red Hat Enterprise Linux (RHEL), CentOS et Ubuntu.


Nous avons testé AWX sur Debian (Bullseye), l’installation peut être assez compliquée lorsqu’on découvre AWX et son environnement mais son utilisation est plutôt intuitive.

L’interface et le fonctionnement de Tower sont quasiment identiques à AWX.

Dashboard AWX

Il y a plusieurs différences dans la manière d’utiliser Ansible dans le terminal et depuis AWX.

La configuration des machines, de leurs identifiants et des inventory est similaire et très facile. En revanche pour les playbooks ce n’est pas la même méthode.


Premièrement on doit configurer un projet. Un projet est un groupe d’un ou plusieurs playbooks sous la forme d’un dépôt Git ou d’une archive.

Paramètres d’un projet

Ensuite il faut créer des templates, une template peut être considérée comme la commande pour exécuter un playbook : on choisit quel playbook exécuter depuis un projet, on choisit sur quel inventory l’exécuter et les identifiants à utiliser pour les connexions SSH sur les machines de l’inventory.

Paramètres d’une template

On peut ensuite exécuter les templates et suivre leurs avancements et résultats dans l’onglet Jobs ou depuis la page de la template.

Dans l’onglet des templates on peut aussi créer des workflows, un workflow permet d’exécuter plusieurs templates à la suite en y ajoutant des conditions.

On peut choisir d’exécuter certaines templates si une autre réussit, et d’autres si elle échoue.

Éditeur des workflows

Ressources et liens utiles pour apprendre Ansible

Cette courte présentation vise à vous faire découvrir Ansible et ne couvre donc que les bases (beaucoup de détails ont été omis pour éviter la surcharge d’informations). Ansible est un outil très complet et il existe de nombreuses ressources pour apprendre à le prendre en main et le maîtriser.

En voici quelques unes pour bien débuter :


Ansible est un outil très puissant aux applications nombreuses, et peut notamment faciliter l’administration des IBM i (surtout à grande échelle). Malheureusement il n’existe à l’heure actuelle aucune solution clé en main, apprendre à utiliser Ansible et créer ses propres playbooks est indispensable.

Cet apprentissage peut prendre du temps sans expérience préalable avec les environnements Unix et/ou Python. Mais si Ansible peut paraître difficile à prendre en main et maîtriser, des solutions plus guidées et faciles d’accès pourraient arriver à l’avenir, permettant à tous d’utiliser Ansible à son plein potentiel sans avoir à le maîtriser chaque aspect.

, , Authentification par JWT (Json Web Token)

Pour mettre en place une authentification par JWT sur IBMi, on utilise l’API Qc3VerifySignature.

Le JWT

Il est composé de trois partie :

  • Un entête (header)
  • Une charge utile (payload)
  • Une signature numérique

Pour obtenir la signature, il faut tout d’abord encoder séparément le header et le payload avec BaseURL64, ensuite, on les concatène en les séparant d’un point.

On calcule enfin une signature d’après le header et le payload afin de garantir que le jeton n’a pas été modifié, d’après l’algorithme défini dans le header (RS256, HS256, HS512, …). Cette signature binaire est elle-même encodée ensuite en Base64URL.

On obtient ainsi le JWT : { header }.{ payload }.{ signature }

Préparation

Afin de tester cette API, il faut dans un premier temps générer une clé au format PEM en suivant les étapes ci-dessous :

  • openssl req -new -out monserveur.csr

Pour créer une demande certificate (.csr = certificat signing request)

Cela crée deux fichiers : monserveur.csr et privkey.pem

  • openssl rsa -in privkey.pem -out monserveur.key

Cela crée le fichier monserveur.key (clé privée sans le mot de passe)

  • openssl x509 -in monserveur.csr -out monserveur.cert -req -signkey monserveur.key

Cela crée le fichier monserveur.cert, qui est le certificat.

Paramètres d’appels de Qc3VerifySignature

  • Signature

La signature est fournie en BASE64, il faut la convertir en binaire pour la fournir à l’API

  • Longueur de signature

La longueur de la signature fournie après sa conversion

  • Donnée à contrôler

{ header }.{ payload } en ASCII

  • Longueur de la donnée à contrôler
  • Format de la donnée à contrôler
  • Description de l’algorithme

C’ ‘est une Data Structure qui contient les paramètres de l’algorithme.

  • Format de la description de l’algorithme
  • Description de la clé

C’ ‘est une Data Structure qui contient les paramètres de la clé.

  • Format de la description de la clé
  • Fournisseur de service cryptographique (0, 1 ou 2)
  • Nom du périphérique de cryptographie (à blanc si fournisseur 1 ou 0)
  • Code Erreur

C’est une Data Structure qui indique le code retour de l’exécution

Cinématique

Pour mettre en place l’appel à Qc3VerifySignature, nous avons défini les formats suivants :

  • Données             DATA0100 : La donnée est contrôlée sur sa valeur et sa longueur
  • Algorithme         ALGD0400 : Paramètres pour une opération de vérification de signature
  • Clé                      KEYD0600 : Certificat PEM (voir paragraphe « Préparation »)

Données

On crée la donnée à contrôler en concaténant header et payload, séparés d’un point, comme expliqué au paragraphe précédent.

Exemple :

ATTENTION : Il faut, pour être utilisable, que celle-ci soit en ASCII. Pour ce faire on utilise le programme système QDCXLATE qui permet de faire de la conversion de chaines de caractères grâce à des tables système.

Data Structure du format ALGD0400 (algorithme) :

cipher   INT(10) inz(50)                  // Code secret pour RSA , initialisé à 50

PKA      CHAR(1) inz(1)                  // PKCS bloc 01

filler   CHAR(3) inz(x’000000’)      // Réservé : ce champ doit rester NULL

hash     INT(10) inz(3)                   // Signature Algorithme de Hash 3=SHA256

Data Structure du format KEYD0600 (clé) :

keylen INT(10)                                       // Longueur du certificat PEM

filler CHAR(4) inz(x’00000000′)           // Réservé : ce champ doit rester NULL

key CHAR(4096) CCSID(65535)           // Certificat PEM en ASCII

Code Retour

L’appel de l’API avec les paramètres choisis , retourne un Data Structure ErrorCode décrite ci-dessous :

bytesProv  INT(10) inz( %size( ErrorCode ) ); // ou 64 pour voir MSGID

bytesAvail INT(10) inz(0);

MSGID CHAR(7);

filler CHAR (1);

data  CHAR (48);

Dans le cas où la signature est vérifiée, les valeurs retour sont les suivantes

  • BYTESPROV = 64                                          
  • BYTESAVAIL = 0                                          
  • MSGID = ‘       ‘                                       
  • FILLER = ‘ ‘                                            
  • DATA = ‘                                                ‘

Si la signature n’est pas vérifiée, les valeurs retour seront  :

  • BYTESPROV = 64                                          
  • BYTESAVAIL = 15                                         
  • MSGID = ‘CPF9DEF’                                       
  • FILLER = ‘0’                                            
  • DATA = ‘                                                ‘
, , , QCMDEXC en Fonction SQL

Depuis la TR4 de la version V7R4, vous pouvez utiliser la fonction QCMDEXC

C’est l’occasion de faire un rappel sur les différents usages disponibles jusque la

1 ) C’est une api (un programme) que vous pouvez appelez depuis un programme RPG ou CLP

en RPGLE

Dcl-Pr Exec_Commande QCMDEXC ExtPgm(‘QCMDEXC’);
Cmd Char(3000) Const;
CmdLen packed(15:5) Const;
End-Pr;

Dcl-S Gbl_Cmd Char(3000);

Gbl_Cmd = ‘Votre commande’ ;

Exec_commande(Gbl_Cmd : %len(Gbl_Cmd)) ;

En CLLE

PGM
DCL &CMD *CHAR 300
DCL &LEN *DEC (15 5)

CHGVAR &CMD (‘VOTRE COMMANDE’)
CHGVAR &LEN %LEN(&CMD)
CALL QCMDEXC (&CMD &LEN)

2) C’est une procédure SQL

call qcmdexc(‘votre commande’)

en sql embarqué

Dcl-S Gbl_Cmd Char(3000);

call qcmdexc(:Gbl_Cmd)

3) C’est une Fonction SQL à partir de la TR4

réorganisation des fichiers BD

SELECT qcmdexc(‘RGZPFM FILE(‘ concat
trim(substr(TABLE_SCHEMA, 1 , 10))
concat ‘/’ concat
substr(TABLE_NAME, 1 , 10) concat ‘)’) as résultat
FROM systables WHERE TABLE_SCHEMA =
‘GDATA’ and FILE_TYPE = ‘D’

la fonction renvoi 1 si ok et -1 si ko

Conclusion :
Vous avez un aperçu des possibilités qcmdexc sur la machine, à vous de jouer !

, , UTILISATION DES API EN SQL

Récupérer une API

Il existe un grand nombre d’API aux fonctionnalités diverses dont certaines nous permettent de récupérer des données structurées dans différents formats (XML, JSON, …).

Grace aux fonctions SQL de l’IBMi nous pouvons récupérer ces données pour les insérer dans les fichiers de la base de données.

Pour les exemples qui suivent, on se base sur trois API tirées du site https://openweathermap.org/ :

  • Une première qui récupère la météo dans une ville donnée

https://api.openweathermap.org/data/2.5/weather?q={city name}&appid={API key}&mode=xml’

  • Une qui récupère jusqu’à 50 communes autour de coordonnées choisies

https://api.openweathermap.org/data/2.5/find?lat=45.75&lon=4.5833&cnt=50&appid={API key}&mode=xml

  • Une qui récupère jusqu’à des communes dans un rectangle de coordonnées choisies

https:// api.openweathermap.org/data/2.5/box/city?bbox=4,45,8,46,50&appid={API key}

Extraire les données de l’API

Sortie API en XML

La commande SQL suivante permet d’afficher les données dans un champ DATA 

SELECT DATA FROM (values
char(SYSTOOLS.HTTPGETCLOB('https://api.openweathermap.org/data/2.5/weather?q={city name}&appid={API key}&mode=xml',''), 4096))
ws(data);

Sortie API en JSON

La commande SQL suivante permet d’afficher les données dans un champ DATA 

SELECT DATA FROM (values
char(SYSTOOLS.HTTPGETCLOB('api.openweathermap.org/data/2.5/weather?q={city name}&appid={API key}',''), 4096))
ws(data);

Sortie API en HTML

La commande SQL suivante permet d’afficher les données dans un champ DATA 

SELECT DATA FROM (values
char(SYSTOOLS.HTTPGETCLOB('https://api.openweathermap.org/data/2.5/weather?q={city name}&appid={API key}&mode=html',''), 4096))
ws(data);

Récupération des données

En XML

On crée un fichier qui contiendra les colonnes que l’on veut récupérer (Ville, Température en cours, date, …)

CREATE TABLE GG/METEODB
(VILLE_ID DECIMAL (9, 0) NOT NULL WITH DEFAULT,
VILLE_NOM CHAR (50) NOT NULL WITH DEFAULT,
TEMPERATURE DECIMAL (5, 2) NOT NULL WITH DEFAULT,
TEMP_MIN DECIMAL (5, 2) NOT NULL WITH DEFAULT,
TEMP_MAX DECIMAL (5, 2) NOT NULL WITH DEFAULT,
DATE_MAJ CHAR (20) NOT NULL WITH DEFAULT)
;

Récupérer les données de l’API dans le fichier créé :

INSERT INTO GG.METEODB
select xdata.* FROM xmltable('$doc/cities/list/item'
PASSING XMLPARSE(document SYSTOOLS.HTTPGETCLOB('https://api.openweathermap.org/data/2.5/find?lat=45.75&lon=4.5833&cnt=10&appid={API key}&mode=xml','')) AS "doc"
COLUMNS
ville_id decimal(9, 0) PATH 'city/@id',
ville_nom varchar(50) PATH 'city/@name',
temperature decimal(5, 2) PATH 'temperature/@value',
temp_min decimal(5, 2) PATH 'temperature/@min',
temp_max decimal(5, 2) PATH 'temperature/@max',
date_maj varchar(20) PATH 'lastupdate/@value' ) as xdata;

En JSON

Contrairement à XML, on peut créer tout de suite un fichier qui contiendra les colonnes que l’on veut récupérer.

CREATE TABLE GG.METEOBD
(VILLE_ID DECIMAL (9, 0) NOT NULL WITH DEFAULT,
VILLE_NOM CHAR (50) NOT NULL WITH DEFAULT,
TEMPERATURE DECIMAL (5, 2) NOT NULL WITH DEFAULT,
TEMP_MIN DECIMAL (5, 2) NOT NULL WITH DEFAULT,
TEMP_MAX DECIMAL (5, 2) NOT NULL WITH DEFAULT,
DATE_UX_MAJ DECIMAL (12, 0) NOT NULL WITH DEFAULT)

Récupérer les données de l’API dans le fichier créé :

INSERT INTO GG.METEOBD
select * from JSON_TABLE(SYSTOOLS.HTTPGETCLOB('https://api.openweathermap.org/data/2.5/box/city?bbox=4,45,8,46,50&appid={API key}','') ,
'$.list[*]'
COLUMNS
(ville_id decimal(9, 0) PATH '$.id',
ville_nom varchar(50) PATH '$.name',
temperature decimal(5, 2) PATH '$.main.temp',
temp_min decimal(5, 2) PATH '$.main.temp_min',
temp_max decimal(5, 2) PATH '$.main.temp_max',
date_ux_maj decimal(12, 0) PATH '$.dt'));

Pour aller plus loin

En utilisant une API de LA POSTE qui ne nécessite pas d’inscription au préalable, ni d’identification. Nous pouvons réaliser un programme qui nous aide à retrouver une commune à partir d’un code postal, dans l’optique d’aider au remplissage de certains formulaires.
On crée un fichier temporaire en interrogeant directement l’API.