{{tag>Brouillon CA Ansible}}

= Bonnes pratiques Ansible

Voir :
* https://docs.ansible.com/ansible/latest/tips_tricks/ansible_tips_tricks.html
* https://www.ansible.com/blog/ansible-best-practices-essentials
* https://www.redhat.com/sysadmin/10-great-ansible-practices
* https://redhat-cop.github.io/automation-good-practices/
* https://www.gaige.net/separating-ansible-roles-for-fun-and-profit.html
* https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_reuse_roles.html
* https://ansible.readthedocs.io/projects/awx/en/24.6.1/userguide/best_practices.html
* https://docs.ansible.com/ansible/latest/tips_tricks/sample_setup.html
* https://docs.ansible.com/ansible/2.8/user_guide/playbooks_best_practices.html
* https://timgrt.github.io/Ansible-Best-Practices/ansible/playbook/
* https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_advanced_syntax.html
* https://spacelift.io/blog/how-to-improve-ansible-performance


== Principes / Philosophie

=== Les 12 facteurs

=== Zen de Python

https://fr.wikipedia.org/wiki/Zen_de_Python

<code python>
import this
</code>


== Bonnes pratiques propres à Ansible I

=== Idempotents

* Privilégier les modules natifs
* Utiliser les handlers pour le redémarrage de services
* Utiliser ''changed_when'' **A(creates)** ou **A(removes)**


Codes de retour corrects \\
Change_when \\
Si Appel API -> Changed (par défaut)

Exemple :
<code yaml>
    - name: call api
      register: plop
      uri:
        url: https://tower.acme.fr/api/v2/job_templates/93/launch/
        method: POST
        force: true
        force_basic_auth: true
        user: username
        password: 'P@ssw0rd'
        validate_certs: false
        # body_format: form-urlencoded
        body_format: json
        headers:
          Content-Type: "application/json"
        body: |
          {
              "extra_vars": {
                  "git_path": "/project/plop",
                  "git_user": "gittoken"
              }
          }
        status_code: 201
</code>


Éviter autant que possible l'appel au **M(shell)** \\
Éviter d'utiliser les **M(script)** et **M(command)** \\
Privilégier **M(command)** à **M(shell)** \\
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''
* ''failed_when''
* ''changed_when''
ou bien : penser à utiliser **A(creates)** ou **A(removes)**


Exemple :
<code yaml>
- name: Check if my_package is installed
  command: dpkg-query -W my_package
  register: my_package_check_deb
  failed_when: my_package_check_deb.rc > 1
  changed_when: my_package_check_deb.rc == 1
  check_mode: false
  
- name: systemd-escape
  ansible.builtin.command: /usr/bin/timeout --kill-after=15 10 /usr/bin/systemd-escape -p --suffix=mount {{ CIFS_MOUNT_PATH | quote }}
  register: unit_systemd
  changed_when: false
  check_mode: false
  failed_when:
    - unit_systemd.rc != 0       # OK
    - unit_systemd.rc != 124     # Timeout. SIGTERM
    - unit_systemd.rc != 137     # Timeout. SIGKILL
</code>

Utiliser les **handlers** pour redémarrer les services
Mais attention avec les modules (import*), les handlers ne sont pas déclenchés par défaut. Faire ''ansible.builtin.meta: flush_handlers''


=== Ansible-lint

Ne pas utiliser de module obsolète "Deprecated" (RA_QUA_N2)
	
Corriger le code pour chaque avertissement.

Nommer chaque tâche

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)...



=== Encodage fichiers


Si beaucoup de données préférer les déplacer files/ plutôt que d'utiliser M(copy) A(content)

Deux types de fichiers :
* Fichier texte de tailles réduite
  * Taille < 100K ou mime-encoding = us-ascii / utf-8
* Binary large object (BLOB)
  * Taille > 100k ou mime-encoding = binary



==== BLOB - fichiers binaires et fichier textes volumineux

<code bash>
find . -type f -wholename "*/files/*" -size +100k
find . -type f -wholename "*/files/*" -size -100k -exec file --mime-encoding {} + | awk -F: '/binary/ { print $1 }'
</code>



* Systématiquement vérifier le hash, par exemple en utilisant A(checksum) avec M(copy) et M(get_url)
  * Voir https://github.com/openshift/openshift-ansible/blob/master/docs/best_practices_guide.adoc
* Devrait être dépôt dédié sépare de Git 
  * Exemple : Artifact / S3 (MinIO) / NAS (NFS) / HTTP
* Garder une arborescence similaire aux petits textes : le chemin doit contenir le nom de rôles ou du playbook
* 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'') (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:" (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>



== Bonnes pratiques AWX

Voir :
  * 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) (RA_QUA_N1)

Ne pas utiliser ''M(pause)'' sans timeout (RA_QUA_N1)

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)


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.$

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

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)




== Bonnes pratiques IT


Logger (via AWX, ou via un callback plugin, ARA Records Ansible...). Et utiliser la directive ''no_log:'' pour les secrets. 
Voir aussi : https://docs.ansible.com/ansible/latest/reference_appendices/config.html

Tester les playbooks sur un environnement hors prod.
* https://www.commitstrip.com/fr/2013/04/16/tester-ou-ne-pas-tester-telle-est-la-question/?

Mettre en place des tests unitaires :
* https://www.commitstrip.com/fr/2017/02/08/where-are-the-tests/
* Molecule


Utiliser le cache que cela est possible :
* 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)
<code ini>
[inventory]
cache = True
cache_plugin = memory
cache_timeout = 1800
</code>


== Bonnes pratiques code

Éviter le code spaghetti

Assert extra_var, controler les inputs des utilisateurs (RA_SEC_N1)

Assert sur les cibles (RA_SEC_N2)

Faire les contrôle de plus tôt possible.

Exemple :
Contrôle avant d'effectuer la connexion : playbook localhost avec gather_facts=false
Playbook dédié : ''ansible.builtin.import_playbook: _assert_extra_vars.yml''

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 (RA_GEN_N1)

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) (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."
* En créant des rôles en les appelant avec des arguments / variables
* ''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)



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)

Encodage fichier
* UTF-8
* Pas de tabulation (Utiliser un IDE avec greffon pour Ansible ou configurer son IDE pour remplacer les tabulations par deux espaces)



=== Utiliser les modules déjà existant / ne pas réinventer la roue (RA_GEN_N1)



<code bash>
ansible-doc -l |grep reboot
ansible-doc ansible.builtin.reboot
</code>


Si pas présent, chercher si une collection / un rôle n'existe pas déjà 
* https://docs.ansible.com/ansible/latest/collections/index_module.html
* https://catalog.redhat.com/en/platform/red-hat-ansible
* https://galaxy.ansible.com/ui/

<code bash>
ansible-galaxy search reboot
</code>


Timeout après 5s (''async'')
<code yaml>
---

- name: Test
  hosts: localhost

  tasks:
    - name: Sleep
      ansible.builtin.command: /bin/sleep 60
      async: 10
      # poll: 5
</code>


Voir : https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_checkmode.html#check-mode-dry

Éviter ''command: cat''. Préférez :
<code yaml>
- name: get actual effective params
  slurp:
    src: /proc/cmdline
  become: true
  register: all_current_activ_params

- name: show effective params
  debug:
    msg: "{{ all_current_activ_params.content | b64decode }}"
</code>



=== run_once

https://github.com/ansible/ansible-lint/issues/1026#issuecomment-685849603

Ansible ignores ''run_once'' with the free strategy which means your tasks are run many times, once for each valid inventory host

Si ''run_once'', toujours préciser le ''delegate_to'' ou ''when: inventory_hostname == ''

Il est aussi possible de faire quelque chose comme :
<code yaml>
- command: /opt/application/upgrade_db.py
  when: inventory_hostname == webservers[0]
</code>

Les tâches marquées comme ''run_once'' seront exécutées sur un hôte dans chaque série de lot. Si la tâche ne doit s'exécuter qu'une seule fois quel que soit le "serial" mode , utilisez
<code yaml>
when: inventory_hostname == ansible_play_hosts_all[0] 
</code>






== Convention dev

Commencer chaque playbook par contrôler les entrées de l'utilisateur. \\
* Grâce au M(assert) et M(fail)
* Grâce à ''argument_specs.yml''
  * voir https://pypi.org/project/ansible-argument-spec-generator/

Contrôler que la cible correspond bien \\
Exemple : 
* Bonne version OS
* Agent pas déjà installé via autre autre procédure...
* Espace disque et autres ressources disponibles sur la cible




== Portée des variables

''DEFAULT_PRIVATE_ROLE_VARS''

M(ansible.builtin.include_roles) and M(ansible.builtin.import_roles)
C(public)

=== Import vs include

Modules :
* ansible.builtin.import_playbook
* ansible.builtin.import_role
* ansible.builtin.import_tasks
* ansible.builtin.include_role
* ansible.builtin.include_tasks
* ansible.builtin.include_vars

<code ->
You cannot use loops on 'import_tasks' statements. You should use 'include_tasks' instead.
</code>




== Sécurité

Mettre les ''become'' que sur les tâches nécessitant les privilèges, et non sur tous le playbook (RA_SEC_N1)


* RBAC CRUD
* Logs
  * AWX
  * Callback
    * https://toshio.fedorapeople.org/ansible/latest/plugins/callback.html
    * https://docs.ansible.com/ansible/latest/collections/index_callback.html
    * community.general.syslog_json

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 
# https://docs.ansible.com/ansible/devel/porting_guides/porting_guide_12.html
export _ANSIBLE_TEMPLAR_UNTRUSTED_TEMPLATE_BEHAVIOR=fail

https://docs.ansible.com/ansible/devel/porting_guides/porting_guide_core_2.19.html#untrusted-templates
export ANSIBLE_DISPLAY_TRACEBACK=always


== Performance

Voir :
* https://www.reddit.com/r/ansible/comments/11jc4c0/mitogen_speedup_the_actual_value/
* https://prohoster.info/fr/blog/administrirovanie/uskoryaem-ansible-s-pomoshhyu-mitogen
* 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) (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
* Garder les tunnels SSH ouverts


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>


=== Tests

* tests manuels
* tests unitaire
* tests fonctionnels

== Autres

=== Ping

Voir [[Ansible Ping ICMP]]
 


== Convention de nommage 

=== Naming things

* 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

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

Définir et respecter une convention de nommage


Convention pour les variables, il doit être possible de distinguer deux types (fonctionnel) de variables : 
* Entrées utilisateurs
* Variables internes

Nommer les templates Jinja avec l’extension **j2** (RA_CONV_REQ)


Préférer les variables a plat plutôt que les variables dictionnaires (RA_CONV_OPT)
<code yaml>
endpoint_url:
endpoint_port:
</code>

plutôt que

<code bash>
endpoint:
  url:
  port:
</code>


=== Boucles

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.

Il est recommandé de définir une convention de nommage pour la variable de boucle. Par exemple d'avoir toujours un suffixe **_item**

Exemple :
<code yaml>
- include_tasks: inner.yml
  loop:
    - 1
    - 2
    - 3
  loop_control:
    loop_var: outer_item
</code>

Utiliser ''label'' dans ''loop_control'' pour rendre l'affichage plus lisible


=== Fichiers / templates

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
* templates/etc/nginx/site-aviable/plop.j2



== Annexes 

Outils
* Formation
* Ansible-lint
* yamllint
* Sonarqube
* CI/CD Gitlab-CI