Différences

Ci-dessous, les différences entre deux révisions de la page.

--- tech:bonnes_pratiques_ansible [2025/10/29 14:12] – Jean-Baptiste
+++ tech:bonnes_pratiques_ansible [2025/11/20 16:27] (Version actuelle) – Jean-Baptiste
@@ Ligne 74: / Ligne 74: @@
 Éviter d'utiliser les **M(script)** et **M(command)** \\
 Privilégier **M(command)** à **M(shell)** \\
-Si variables Jinja en argument à M(command) ou M(shell) : utiliser ''quote'' pour échapper les caractères spéciaux.
+Si variables Jinja en argument à M(shell) : utiliser ''quote'' pour échapper les caractères spéciaux.
 Pour **M(command)**, **M(shell)**, **M(script)**, contrôler le code de retour avec
 * ''register''
@@ Ligne 108: / Ligne 108: @@
 === Ansible-lint
-Ne pas utiliser de module obsolète "Deprecated"
+Ne pas utiliser de module obsolète "Deprecated" (RA_QUA_N2)
 Corriger le code pour chaque avertissement.
@@ Ligne 114: / Ligne 114: @@
 Nommer chaque tâche
-Les noms de tâche devraient être uniques
+Les noms de tâche devraient être uniques (RA_QUA_N3)
 Conformité ansible-lint
 Conformité indentation yamllint
+Préciser le owner/group/chmod pour M(copy), M(template)...
@@ Ligne 150: / Ligne 153: @@
 * Une référence unique. Un seul rôle (ou un seul playbook) fait appel directement à ce fichier.
 * Si deux roles ou besoin de ce même fichier : créer un 3em rôle et faire un dépendance de rôle.
 == Bonnes pratiques propres à Ansible II
+Si pas besoin des facts : mettre gather_facts à false (RA_PERF_N3)
+Si besoin de facts récuper seulement les facts utiles (RA_PERF_N3)
+<code yaml>
+    - name: Get minimal facts
+      ansible.builtin.setup:
+        gather_subset:
+          - '!all'
+          - distribution
+</code>
-Playbook pouvant fonctionner un Dry-Run (''--check'')
+Playbook pouvant fonctionner un Dry-Run (''--check'') (RA_TEST_N2)
 * ''check_mode: false'' quand nécessaire
 Ne pas utilisez ''ignore_errors: true'' et encore moins pour un playbook entier.
-Préferez "failed_when:"
+Préferez "failed_when:" (RA_QUA_N1)
+Éviter d’utiliser ''delegate_to'' surtout, dans les rôles (RA_QUA_N1)
+Pour les templates et les fichiers, systématiquement sauf si non applicable mettre en commentaire que ce fichier est géré par Ansible. (RA_QUA_N1)
+Exemple :
+''all.yml''
+<code yaml>
+ansible_managed: This file is managed by ansible. Manual changes are likely to be overwritten !
+</code>
+=== Pièges
+==== Run_once
+run_once will be executed at each serial execution in the play. That means, if you choose serial = 1, it will be asked to confirm as many times as the quantity of targets on the play.
+Check Ansible docs: https://docs.ansible.com/ansible/latest/user_guide/playbooks_strategies.html#running-on-a-single-machine-with-run-once
+When used together with serial, tasks marked as run_once will be run on one host in each serial batch. If the task must run only once regardless of serial mode, use ''when: inventory_hostname == ansible_play_hosts_all[0]'' construct.
+Attention aux slicing !
+=== Limiter l'usage des ressources
+<code yaml>
+- name: Installation d'un logiciel sur plusieurs serveurs avec throttle
+  ansible.builtin.apt:
+    name: nginx
+    state: present
+  async: 600  # Exécution en mode asynchrone avec un délai maximum de 10 minutes
+  poll: 5     # Vérification toutes les 5 secondes
+  throttle: 3  # Limite à 3 installations simultanées
+  when: inventory_hostname in groups['webservers']
+</code>
-Éviter d’utiliser ''delegate_to'' surtout, dans les rôles
@@ Ligne 172: / Ligne 226: @@
   * https://ansible.readthedocs.io/projects/awx/en/24.6.1/userguide/best_practices.html
-Ne pas utiliser ''M(vars_prompt)'' (remplacé par les "Surveys" et extra-vars)
+Ne pas utiliser ''M(vars_prompt)'' (remplacé par les "Surveys" et extra-vars) (RA_QUA_N1)
-Ne pas utiliser ''M(pause)'' sans timeout
+Ne pas utiliser ''M(pause)'' sans timeout (RA_QUA_N1)
-Utiliser des inventaires dynamiques (If you have an external source of truth)
+Utiliser des inventaires dynamiques (If you have an external source of truth) (RA_QUA_N3)
 * single source of truth (SSOT) architecture, or single point of truth (SPOT)
@@ Ligne 182: / Ligne 236: @@
 Variable Management for Inventory - Keeping variable data along with the hosts and groups definitions (see the inventory editor) is encouraged, rather than using group_vars/ and host_vars/
-Autoscaling - Using the “callback” feature to allow newly booting instances to request configuration is very useful for auto-scaling scenarios or provisioning integration.
+Autoscaling - Using the “callback” feature to allow newly booting instances to request configuration is very useful for auto-scaling scenarios or provisioning integration.$
-Larger Host Counts - Consider setting “forks” on a job template to larger values to increase parallelism of execution runs. Voir : Strategy, Mitogen, Slicing, Async (Asynchronous)
+Larger Host Counts - Consider setting “forks” on a job template to larger values to increase parallelism of execution runs. Voir : Strategy, Mitogen, Slicing, Async (Asynchronous) (RA_PERF_N3)
 Ne pas utiliser Verbosity à 4 ou 5. Eviter d'augmenter la verbosité si l'inventaire est conséquent
-Eviter le cache des facts coté serveur (Enable Fact Storage)
+Ne pas mettre les facts des nœuds dans la base de données - Ne pas activer "Enable Fact Storage"
+Le cache des facts doit être sur les managed_hosts et non coté serveur (RA_GEN_N1)
+Ne pas faire de ''command: ansible-galaxy'' ni de ''shell: ansible-galaxy'', mais utiliser la manière native de AAP / AWX (RA_QUA_N1)
@@ Ligne 206: / Ligne 265: @@
 Utiliser le cache que cela est possible :
-* Pour les facts (facts caching)
+* Pour les facts (facts caching) (RA_PERF_N3)
 * Mais éviter "Enable Fact Storage" qui met les fact dans la base de données
 * Pour les inventaires (cache_plugin, Fact Cache)
@@ Ligne 221: / Ligne 280: @@
 Éviter le code spaghetti
-Assert extra_var, controler les inputs des utilisateurs
+Assert extra_var, controler les inputs des utilisateurs (RA_SEC_N1)
-Assert sur les cibles
+Assert sur les cibles (RA_SEC_N2)
 Faire les contrôle de plus tôt possible.
@@ Ligne 231: / Ligne 290: @@
 Playbook dédié : ''ansible.builtin.import_playbook: _assert_extra_vars.yml''
-Utiliser un logiciel de gestion de versions tel que Git
+Utiliser un logiciel de gestion de versions tel que Git (RA_GEN_N1)
 Use Source Control https://ansible.readthedocs.io/projects/awx/en/24.6.1/userguide/best_practices.html
-Utiliser l'encodage UTF8
+Utiliser l'encodage UTF8 (RA_GEN_N1)
-Remplacer les tabulations par 2 espaces (A config si ce n'est pas le cas dans l'IDE)
+Remplacer les tabulations par 2 espaces (A config si ce n'est pas le cas dans l'IDE) (RA_GEN_N1)
-Factoriser - Éviter de dupliquer du code - Don't Repeat Yourself (DRY)
+Factoriser - Éviter de dupliquer du code - Don't Repeat Yourself (DRY) (RA_GEN_N3)
 Dans la mesure du possible, seulement se répéter est mieux que d'écrire un code difficilement lisible.
 Car "à la pureté, privilégie l'aspect pratique."
@@ Ligne 244: / Ligne 303: @@
 * ''module_defaults'' (If you frequently call the same module with the same arguments)
 * En utilisant import* et include* (attention aux notify avec include)
+* En utilsant ''block''
+Utiliser SonarQube ou équivalent (RA_GEN_N4)
-Utiliser SonarQube ou équivalent
 Petits textes
 * Utiliser le charset ''utf-8'' (ou ''us-ascii'' si aucun caractère unicode)
 * Convertir le charset ''iso-8859-1'' et autres en ''utf-8''
-* Devrait être dans ''<role_name>/files/'' ( ou dans ''files/'' si appelé directement depuis un playbook)
+* Devrait être dans ''<role_name>/files/'' (ou dans ''files/'' si appelé directement depuis un playbook)
 Encodage fichier
@@ Ligne 258: / Ligne 320: @@
-=== Utiliser les modules déjà présent / ne pas réinventer la roue
+=== Utiliser les modules déjà existant / ne pas réinventer la roue (RA_GEN_N1)
@@ Ligne 369: / Ligne 432: @@
 You cannot use loops on 'import_tasks' statements. You should use 'include_tasks' instead.
 </code>
@@ Ligne 379: / Ligne 438: @@
 == Sécurité
-Mettre les ''become'' que sur les tâches nécessitant les privilèges, et non sur tous le playbook
+Mettre les ''become'' que sur les tâches nécessitant les privilèges, et non sur tous le playbook (RA_SEC_N1)
@@ Ligne 390: / Ligne 449: @@
     * community.general.syslog_json
-Utiliser ''no_log: true'' pour les taches utilisant des secrets
+Utiliser ''no_log: true'' pour les taches utilisant des secrets (RA_SEC_N1)
+Pour les données sensibles utiliser ansible-vault ou les Crendential AWX (RA_SEC_N1)
 Troubleshooting untrusted templates
@@ Ligne 407: / Ligne 468: @@
 * https://docs.redhat.com/fr/documentation/red_hat_ansible_automation_platform/2.6/html-single/performance_tuning_for_ansible_automation_platform/index
-* Mettre en cache les facts (fact_caching)
+* Mettre en cache les facts (fact_caching) (mais sur les noeuds, pas en DB) (RA_PERF_N3)
 * Analyser les temps d’exécution anormalement long ''callback_whitelist = timer, profile_tasks''
 * Utiliser Mitogen
@@ Ligne 413: / Ligne 474: @@
+Eviter de boucler innutilement - vérifier si le module prends des listes (RA_PERF_N2)
+<code yaml>
+- name: Install packages
+  ansible.builtin.package:
+    name: "{{ item }}"
+    state: present
+  loop:
+    - curl
+    - wget
+</code>
+<code yaml>
+- name: Install packages
+  ansible.builtin.package:
+    name:
+      - curl
+      - wget
+</code>
@@ Ligne 434: / Ligne 511: @@
 == Convention de nommage
-Si beaucoup de templates dans le role : utiliser une arborescence du style :
+=== Naming things
-* files/etc/nginx/sites-available/plop
+* Use valid Python identifiers following standard naming conventions of being in snake_case_naming_schemes for all YAML or Python files, variables, arguments, repositories, and other such names (like dictionary keys).
+* Do not use special characters other than underscore in variable names, even if YAML/JSON allow them.
+Source : https://redhat-cop.github.io/automation-good-practices/#_naming_things
+=== name
+For example, if you have a task named **Restart server** inside a file named ''tasks/deploy.yml'', this rule suggests renaming it to **deploy | Restart server**
+Source : https://ansible.readthedocs.io/projects/lint/rules/name/#nameprefix
+=== role-name
+(snake case)
+Role names must contain only lowercase alphanumeric characters and the underscore _ character. Role names must also start with an alphabetic character.
+Source : https://ansible.readthedocs.io/projects/lint/rules/role-name/
+=== var-naming
+...
+Variable names must contain only lowercase alphanumeric characters and the underscore _ character. Variable names must also start with either an alphabetic or underscore _ character.
+...
+role_name_ as a prefix
+...
+Source : https://ansible.readthedocs.io/projects/lint/rules/var-naming/
+=== Extra_vars
 Voir : https://github.com/openshift/openshift-ansible/blob/master/docs/style_guide.adoc
-Convention pour les **register**
+Exemple : ''cli_plop''
+=== Register
+Convention pour les **register**.
+Exemple ''r_foo''
+=== Autres
 Les listes seront nommées avec un **s** finals. L'emploi du pluriel indique plusieurs éléments possibles
@@ Ligne 450: / Ligne 566: @@
 * Variables internes
-Nommer les templates Jinja avec l’extension **j2**
+Nommer les templates Jinja avec l’extension **j2** (RA_CONV_REQ)
-Préciser le owner/group/chmod
-Préférer les variables a plat plutôt que les variables dictionnaires
+Préférer les variables a plat plutôt que les variables dictionnaires (RA_CONV_OPT)
 <code yaml>
 endpoint_url:
@@ Ligne 474: / Ligne 586: @@
 === Boucles
-De préférence nommer la variable de boucle (''loop_var'') à la place d'utiliser le nom par défaut ''item''
+De préférence nommer la variable de boucle (''loop_var'') à la place d'utiliser le nom par défaut ''item'' (RA_CONV_OPT)
 C'est plus lisible, et cela permet un fonctionnement non équivoque en cas de boucles imbriqués.
@@ Ligne 496: / Ligne 608: @@
 === Fichiers / templates
-Pour les roles contenants beaucoup de fichiers dans "files/" privilégier une arborescence comme suit
+Pour les roles contenants beaucoup de fichiers dans "files/" privilégier une arborescence comme suit (RA_CONV_OPT)
 * files/etc/nginx/sites-available/plop
 * files/etc/systemd/system/plop.service