States et Modules#

Modules#

Introduction#

SaltStack est un framework d’exécution de commandes à distance

  • Le cœur du modèle d’exécution de salt est un ensemble de modules Python situés dans le package Python salt.modules

  • Tout le reste est bâti là-dessus :

    • les states sont mis en œuvre par le module salt appelé states (donc par le module Python salt.modules.states)

    • les grains sont mis en œuvre par le module salt appelé grains (donc par le module Python salt.modules.grains)

    • etc.

Terminologie#

Quand on parle d’un module salt, on fait référence à un module d’exécution à distance

Il peut être défini :

  • dans le package Python salt.modules

  • ou dans un module définit par l’utilisateur et placé dans $SALT_STATES/_modules/

Les autres composants (states, grains, etc.), sont implémentés à l’aide des modules salt correspondant.

Définition : module#

  • Un module salt, ou execution module est un module Python regroupant des fonctions qui peuvent être exécutées sur un minion

  • Une fonction d’un module salt exécute une opération sans se soucier de savoir à priori si cette opération est nécessaire ou pas

  • C’est à l’utilisateur de savoir si l’opération doit être effectuée

  • On peut exécuter une opération

    • depuis le master

      salt machine pkg.install vim

    • ou depuis le minion

      salt-call pkg.install vim

    Dans les deux cas présentés ci-dessus, le système va lancer la commande pour installer le paquet vim, même si ce dernier est déjà installé

Définition : state#

  • Un state vise à mettre le système dans un état particulier

  • Un state est une fonction Python définie dans un module Python appelé state module, présent :

    • dans le package salt.states

    • dans un fichier Python placé par l’utilisateur dans $SALT_STATES/_states/

  • Un state doit être idempotent, c’est à dire que l’exécuter une ou plusieurs fois doit donner le même résultat.

state : exemple#

L’exécution de la commande :

master# salt machine state.single pkg.installed name=vim

  • vérifiera si le paquet vim est déjà installé sur le système,

  • si c’est le cas, il ne fera rien mais terminera son exécution dans l’état True, sinon, il tentera de l’installer (avec la commande install du module salt pkg vue précédemment) et, en cas de succcès, terminera aussi avec True,

  • si l’installation ne se passe pas comme prévu ou si le paquet n’est pas disponible, l’état terminera dans l’état False

state file : rappels#

Un state file est un fichier .sls qui regroupe des déclarations de state à appliquer

La forme générale d’un state déclaré dans un state file ressemble à :

deploy-and-config-ssh: # identifiant (unique)
  pkg: # nom du state module
    - installed # nom de la fonction du state module
    - name : openssh-server
  file.managed: # concatenation statemodule.function
    # suivent arguments passés a la fonction
    - source: salt://ssh/authorized_keys
    - name: /root/.ssh/authorized_keys # nom du fichier
    - template: jinja
  service.running:
    - name: ssh
    - require: # declaration de dependance
      - pkg: openssh-server

Appliquer des states#

Soit le fichier vim.sls :

make sure vim is installed:
  pkg.installed:
    - name: vim

Il est possible de l’appliquer seul :

master# salt 'machine' state.apply vim

Ou de l’inclure dans le top.sls :

base:
  'machine':
     - vim

Et de l’appliquer en mettant la machine en conformité avec un apply :

master# salt 'machine' state.apply

Intérêts des states#

Les states sont logiquement utilisés pour définir (partiellement) l’état d’une machine. Cela permet :

  • d’éviter de réaliser des opérations inutiles (gain de temps),

  • de différencier les cas où salt réalise une opération de ceux ou salt ne fait rien

    • identifier les cas où les fichiers ont été modifiés

    • récupérer les différences

    • permet l’implémentation d’un mode test (distinguer ce qui doit être fait de ce qui est fait)

Modules et States polymorphes#

Salt propose un mécanisme de définition de module et de state virtuel permettant l’abstraction du système cible

Ainsi, indépendamment de la distribution utilisée sur la machine cible, une interface unifiée est disponible

Exemple : installer un paquet monpaquet

- pkg.installed: monpaquet

va se traduire, sur un système Debian, en :

root@minion:~# apt-get install monpaquet

ou, pour sur système Fedora, en :

root@minion:~# yum install monpaquet

Attention : de nombreux state modules ont le même nom que l”execution module sur lequel ils s’appuient ; il ne faut pas les confondre !

Les principaux state modules#

pkg#

State module de gestion de l’installation de logiciels via un système de paquets

  • l’implémentation dépend de la distribution (utilise grains)

  • attention à la sémantique des 2 fonctions installed vs. latest

    • installed

      s’assure que le paquet est installé (et éventuellement à la version demandée)

    • latest

      s’assure que la dernière version disponible du paquet est installée

    • removed

      s’assure que le paquet n’est pas installé, et le désinstalle s’il est présent.

    • purged

      identique à removed, en supprimant les fichiers de configuration.

pkgrepo#

Gestion des sources de paquets supplémentaires (apt, yum, etc.)

  • managed

    s’assure que le dépôt est présent et configuré sur le système

  • absent

    s’assure que le dépôt n’est pas présent sur le système

file#

State module de manipulation de fichiers

  • absent

    s’assure que le fichier n’existe pas

  • append

    s’assure qu’un texte est présent dans un fichier

  • comment

    s’assure qu’une ligne est commentée (regex)

  • directory

    s’assure que le répertoire existe (droits, etc.)

  • exists

    s’assure qu’un fichier existe (mais n’en produit pas le contenu

  • managed

    s’assure qu’un fichier dont le contenu est produit par salt existe et à jour

  • uncomment

    s’assure qu’un ligne de texte est décommentée (regex)

file : remarques#

  • attention aux watch

  • attention aux droits (conversion en octal si on oublie les quotes et suppression du 0 en premier caractère)

  • le templating (jinja) pour compléter le contenu du fichier permet de bien exploiter les grains et pillars

  • attention à la nécessité de file.absent pour supprimer un fichier (après modification des fichiers .sls par exemple)

file : templating#

Pour activer le templating, utiliser l’argument template

deploy templated file:
  file.managed:
    - name: /etc/service/conf.d/config.conf
    - source: salt://service/templates/mainconf.tmpl
    - template: jinja

Il est possible de « passer » des arguments au templating jinja:

deploy templated file:
  file.managed:
    - name: /etc/service/conf.d/config.conf
    - source: salt://service/templates/mainconf.tmpl
    - template: jinja
    - context:
       variable: value
       variable2: value2

ini_managed#

Gestion des fichiers ini (sections, clef/valeurs). Pratique avec des dictionnaires génériques.

  • sections_present:

    s’assure qu’une section est présente dans le fichier ini

  • option_present

    s’assure qu’une option est fixé à une value (section en option)

  • sections_absent:

    s’assure qu’une section n’est pas dans le fichier

  • options_absent:

    s’assure qu’une clef/valeur n’est pas dans la section et le fichier ini

cmd#

State module de gestion des états résultant de l’exécution d’une commande arbitraire

  • run

    exécute une commande (si les circonstances l’exigent)

  • script

    exécute un script après l’avoir téléchargé depuis le master

cmd : remarques#

  • À éviter quand c’est possible :

    • ne dispose pas des protections d’un state (vérification du résultat, non-exécution si déjà dans l’état recherché)

  • force à exécuter la commande à chaque fois

  • utiliser cmd.run avec onchanges pour avoir une exécution conditionelle.

Les principaux execution modules#

Introduction#

  • Ils sont en général bien documentés

    • mais ne pas hésiter à aller lire le code python

  • Les modules sont chargés en fonction du besoin

    • salt-minion détecte au démarrage s’il a besoin de charger un module donné

      Par exemple si la commande zfs n’est pas disponible sur l’hôte, il ne chargera pas le module zfs

    • En revanche, si un état modifie le système (eg. installe le paquet git), les modules sont rechargés.

      Ceci permet d’utiliser un module alors que l’on vient d’installer ce qui lui permet de fonctionner.

sys#

Avertissement

Le module s’appelle sysmod dans la documentation.

  • Module de documentation et d’introspection

  • sys.doc : commande salt de documentation des execution modules

    • renvoie l’ensemble des documentations des modules salt

    • on peut spécifier en plus un module ou une fonction

root@minion:~# salt-call sys.doc file
master:~$ salt 'machine1' sys.doc file.uncomment

  • argspec

    revoie la signature d’une fonction

  • list_functions

    liste les fonctions de tous les modules (ou d’un seul si spécifié)

  • list_modules

    liste les modules disponibles

  • reload_modules

    demande au minion de recharger les modules

test#

Module proposant divers tests exécutés par salt-minion

  • echo

    retourne la chaîne passée en paramètre (test de la connexion)

  • get_opts

    renvoie les options de configuration du minion

  • not_loaded

    liste des modules d’exécution non chargés par le minion

  • ping

    s’assure que le minion répond à une requête du master

  • version

    retourne la version salt du minion

  • versions_report

    retourne les versions des composants utilisés par salt

pkg#

Module virtuel de gestion des paquets d’une distribution Linux

pkg.

  • available_version

    version d’un paquet candidate pour la mise à jour

  • file_list

    liste des fichiers d’un paquet installé

  • install

    installe un paquet

  • latest_version

    dernière version disponible d’un paquet

  • list_pkgs

    liste des paquets installés

  • list_repos

    liste des sources d’entrepôts

  • purge

    purge un paquet installé ou supprimé

  • refresh_db

    met à jour la base des paquets disponibles

  • remove

    supprime un paquet installé

  • upgrade

    met à jour tous les paquets

  • upgrade_available

    vérifie si un paquet est candidat à une mise à jour

  • version

    version d’un paquet installé

service#

service.

Module de manipulation des services Linux (démons, init scripts System V et systemd)

  • available

    renvoie True si le service est disponible

  • disable/enable

    désactive/active le service

  • disabled/enabled

    renvoie True si le service est désactivé/activé

  • force_reload

    recharge le service (forcé)

  • get_all

    liste tous les services disponibles

  • get_disabled

    liste les services désactivés

  • get_enabled

    liste les services activés

  • reload

    recharge un service

  • restart

    redémarre un service

  • start

    démarre un service

  • status

    affiche l’état du service

  • stop

    arrête un service

network#

Module de gestion des interfaces réseau

  • arp

    retourne la table arp du minion

  • dig

    effectue une requête DNS sur le minion

  • hw_addr

    renvoie les adresses MAC des interfaces réseau

  • interfaces

    retourne un dictionnaire des informations sur les interfaces réseau

  • ip_addrs

    retourne les adresses IPv4

  • ip_addrs6

    retourne les adresses IPv6

  • netstat

    retourne des informations sur les ports ouverts

  • ping

    effectue un ping réseau

  • subnets

    liste des subnets auquel le minion appartient

  • traceroute

    effectue un traceroute

iptables#

Module de manipulation de iptables

  • append

    ajoute une règle iptable

  • check

    vérifie la présence d’une règle iptable

  • delete

    supprime une règle

  • flush

    supprime toutes les règles

  • get_policy

    retourne la politique d’une table/chaîne

  • get_rules

    retourne les règles iptables

  • insert

    insère une règle

  • set_policy

    configure la politique d’une table/chaîne

  • version

    version de iptables

hg et git#

Modules de manipulation d’un entrepôt Mercurial ou git

  • archive

    créee une archive (tgz) à partir d’un entrepôt hg ou git

  • clone

    clone un entrepôt hg

  • describe

    retourne l’identifiant d’une révision

  • revision

    retourne le hash long d’une révision

ainsi que la plupart des commandes de bases pour chacun de ces 2 DVCS

saltutil#

Module de manipulation d’un salt-minion

  • cmd

    exécute une commande salt (le minion doit aussi être un master)

  • find_job

    retourne les données associées à un job id

  • is_running

    renvoie True si la fonction passée en argument est en cours d’exécution (peut utiliser des glob patterns)

  • kill_job/term_job

    interrompt l’exécution d’un job (SIGKILL 9 / SIGTERM 15)

  • signal_job

    envoie un signal à un job

  • regen_keys

    demande au minion de régénérer ses clefs AES

  • running

    retourne des informations sur les processus salt qui tournent sur le minion

  • sync_all

    demande au minion de rafraîchir tous ses modules dynamiques

  • sync_grains

    demande au minion de recharger les modules _grains

  • sync_modules

    demande au minion de recharger les modules _modules

  • sync_outputters

    demande au minion de recharger les modules _outputters

  • sync_returners

    demande au minion de recharger les modules _returners

  • sync_states

    demande au minion de recharger les modules _states

  • refresh_modules

    demande au minion de rafraîchir les données des modules et des grains

  • refresh_pillar

    demande au minion de rafraîchir les données des pillars

Liste complète des modules#

Retrouvez la liste complète, dans la documentation de référence :