.. -*- coding: utf-8 -*- :orphan: =================== 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 : .. code-block:: bash 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 à : .. code-block:: yaml 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`` : .. code-block:: yaml make sure vim is installed: pkg.installed: - name: vim Il est possible de l'appliquer seul : .. code-block:: bash master# salt 'machine' state.apply vim Ou de l'inclure dans le ``top.sls`` : .. code-block:: yaml base: 'machine': - vim Et de l'appliquer en mettant la machine en conformité avec un ``apply`` : .. code-block:: bash 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` .. code-block:: yaml - pkg.installed: monpaquet va se traduire, sur un système Debian, en : .. code-block:: console root@minion:~# apt-get install monpaquet ou, pour sur système Fedora, en : .. code-block:: console 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`` ------- .. warning:: 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 .. code-block:: console 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 : - des modules d'exécution (``execution modules``) : https://docs.saltstack.com/en/latest/ref/modules/all/ - des modules d'état (``state modules``) : https://docs.saltstack.com/en/latest/ref/states/all/