wiki/HowtoAnsible.md

---
title: Howto Ansible : automatisation d'infrastructure
categories automation
---

* Documentation : <http://docs.ansible.com/>

[Ansible](https://www.ansible.com/) est un outil d'automatisation de configuration et gestion de serveurs : il permet le déploiement de logiciels et l'exécution de tâches via une connexion SSH.

Ansible fonctionne sans agent sur les serveurs (*agent-less*) et selon le concept d'**[idempotence](https://fr.wikipedia.org/wiki/Idempotence)** : on décrit l'état d'un serveur et des actions seront exécutées dans le but de rendre le serveur conforme à cette description. On pourra relancer Ansible plusieurs fois, l'état final reste le même : seules les actions nécessaires seront exécutées.


## Installation

Nous utilisons actuellement Ansible 2.7 (version proposée en Debian 10) :

~~~
# apt install ansible sshpass

$ ansible --version
ansible 2.7.7
  config file = /etc/ansible/ansible.cfg
  configured module search path = Default w/o overrides
~~~

Ansible peut exécuter des actions sur des machines distantes. Mais certains logiciels sont requis :

* *Debian 6* et supérieur : `# apt-get install --no-install-recommends python python-apt dbus sudo`
* *Debian 4 / 5* : utiliser le module [raw](https://docs.ansible.com/ansible/raw_module.html) d'Ansible
* *OpenBSD* : voir **[pré-requis pour OpenBSD](#pré-requis-openbsd)**
* *FreeBSD* : `# pkg install python`


## Utilisation de base

Configuration minimale :

~~~
$ cat ~/.ansible.cfg
[defaults]
inventory = $HOME/.ansible/hosts

[ssh_connection]
#ssh_args = -o ControlMaster=no -o ControlPersist=no
ssh_args = -o ControlMaster=auto -o ControlPersist=300s
pipelining = True
~~~

Exemples d'utilisation basique sur sa machine en local :

~~~
$ ansible localhost -m ping
localhost | SUCCESS => {
    "changed": false,
    "ping": "pong"
}
~~~

Ou sur une machine distante :

~~~
$ echo mon-serveur >> ~/.ansible/hosts
$ ssh-copy-id mon-serveur
$ ansible mon-serveur -i $HOME/.ansible/hosts -m ping --one-line --forks 1
mon-serveur | SUCCESS => {"changed": false, "ping": "pong"}

$ ansible "mon-*" -m command --args "date"
mon-serveur | SUCCESS | rc=0 >>
jeudi 26 mai 2016, 23:16:01 (UTC+0200)
~~~

Quelques exemples de commandes pratiques :

~~~
$ ansible "*" -bK --one-line --forks 42 -m command --args "grep foo /etc/passwd"
$ ansible "*" -bK --one-line --forks 42 -m command --args "lxc-ls" | grep CHANGED
$ ansible stretch -bK --one-line --forks 42 -m command --args "grep -r SFTPEngine /etc/proftpd"
~~~


## Les éléments d'Ansible

L'élément de base d'Ansible est le [module](#modules) : on peut exécuter une tâche (installation de paquets, copie de fichiers, etc.) en exécutant simplement `ansible -m mon_module`.
Pour regrouper plusieurs tâches, on utilise un [playbook](#playbook) : un fichier en syntaxe YAML qui va lister une succession de modules avec des arguments.
Au sein d'un playbook, on dispose d'options pratiques comme les [handlers](#handlers) : ils permettent le déclenchement d'une commande sous certaines conditions (redémarrage d'un service par exemple).
Si l'on veut organiser de façon poussée les différentes tâches, on utilisera des [roles](#roles) : il s'agit simplement d'inclure dans un playbook des fichiers YAML respectant une structure conventionnelle.
Enfin, pour s'exécuter sur un ensemble de machines, Ansible a besoin d'un [inventory](#inventory) : c'est la liste des serveurs potentiellement concernés.

### modules

<http://docs.ansible.com/ansible/list_of_all_modules.html>

Un module est comme une bibliothèque. Il constitue une couche d'abstraction par rapport au shell et commandes sous-jacentes. C'est cette couche qui permet l'idempotence et le fonctionnement sur plusieurs plateformes.

Les modules disposent de certains comportements et fonctionnalités communs : indication de succès/erreurs/changements, gestion des [variables](http://docs.ansible.com/ansible/playbooks_variables.html), des [conditions](http://docs.ansible.com/ansible/playbooks_conditionals.html), des [boucles](http://docs.ansible.com/ansible/playbooks_loops.html), des états de sortie…

Pour avoir la liste des modules utilisables : `ansible-doc -l`

Voici quelques exemples de modules que nous utilisons :

* Module [command](http://docs.ansible.com/ansible/command_module.html) :

~~~{.yaml}
- command: date
~~~

Ce module ne permet que l'exécution de commandes simple (pas de pipe…) mais en échange il vérifie les commandes et les assainit pour limiter les injections.

* Module [shell](http://docs.ansible.com/ansible/shell_module.html) :

~~~{.yaml}
- shell: cat foo.txt | grep bar
~~~

Ce module permet en revanche d'exécuter arbitrairement et sans contrôle toute commande, au sein d'un shell lancé pour l'occasion.

* Module [file](http://docs.ansible.com/ansible/file_module.html) :

~~~{.yaml}
- file:
    path: /etc/cron.daily/apticron
    state: absent
~~~

* Module [copy](http://docs.ansible.com/ansible/copy_module.html) :

~~~{.yaml}
- copy
    src: files/foo
    dest: /etc/bar
    owner: root
    group: root
    mode: "0644"
~~~

* Module [replace](http://docs.ansible.com/ansible/replace_module.html) :

~~~{.yaml}
- replace:
    dest: /etc/ssh/sshd_config
    regexp: '^(Match User ((?!{{ name }}).)*)$'
    replace: '\1,{{ name }}'
~~~

* Module [lineinfile](http://docs.ansible.com/ansible/lineinfile_module.html) :

~~~{.yaml}
- lineinfile:
    dest: /etc/evocheck.cf
    insertafter: EOF
    line: "IS_APTICRON=0"
    regexp: "^IS_APTICRON="
~~~

*Note:* _replace_ vs _lineinfile_ ? Le fonctionnement exact de _replace_ et de _lineinfile_ peut être déroutant. Voici quelques constatations :

* avec _lineinfile_, si l'argument _regexp_ n'est pas matché… il insère quand même la ligne ! _regexp_ n'est pas une condition pour l'insertion mais pour remplacer au lieu d'insérer !
* avec _lineinfile_, sauf cas tordus, l'argument _regexp_ doit matcher l'argument _line_ (sinon il va insérer la valeur de _line_ à chaque exécution !)
* _lineinfile_ va d'abord évaluer si _regexp_ matche et remplacer la dernière occurrence ; si _regexp_ ne matche pas, il ajoute alors _line_ (sans d'autre condition… même si elle existe déjà)
* _replace_ va remplacer uniquement si _regex_ est matché, comme la commande _sed_
* avec _lineinfile_, si l'on veut utiliser une référence (`\1`) dans _line_, ça donne une erreur, il faut utiliser _replace_
* avec _lineinfile_, l'argument `backrefs: yes` sert à utiliser une référence au sein de l'argument _regexp_ (et non pas au sein de l'argument _line_).

* Module [blockinfile](http://docs.ansible.com/ansible/blockinfile_module.html) :

~~~{.yaml}
- blockinfile:
    dest: /etc/apache2/envvars
    block: |
      ## Set umask for writing by Apache user.
      ## Set rights on files and directories written by Apache
~~~

* Module [ini_file](http://docs.ansible.com/ansible/ini_file_module.html) :

~~~{.yaml}
- ini_file:
    dest: /root/.my.cnf
    section: client
    option: user
    value: root
    mode: "0640"
~~~

Ce module permet de facilement d'ajouter/modifier/supprimer des valeurs dans des fichiers INI, dans la bonne section, sans se soucier de la syntaxe.

* Module [user](http://docs.ansible.com/ansible/user_module.html) :

~~~{.yaml}
- user:
    state: present
    name: "jdoe"
    comment: 'John Doe'
    shell: /bin/bash
    groups: adm
    append: yes
    password: '$6$k/Fg76xH'
~~~

* Module [group](http://docs.ansible.com/ansible/group_module.html) :

~~~{.yaml}
- group:
    state: present
    name: "foobarcorp"
    gid: "1042"
~~~

* Module [stat](http://docs.ansible.com/ansible/stat_module.html) :

~~~{.yaml}
- stat:
    path: /etc/sudoers.d/foo
  register: foo_sudoers_file
~~~

* Module [apt](http://docs.ansible.com/ansible/apt_module.html) :

~~~{.yaml}
- apt:
    name: '{{ item }}'
    state: latest
    update_cache: yes
    cache_valid_time: 3600
  with_items:
  - vim
  - htop
~~~

Ce module fait partie d'une courte liste de modules pour lesquels l'utilisation d'une boucle (avec `with_items` par exemple) ne provoque pas l'exécution séquentielle et répétée du module. Dans l'exemple ci-dessus le module utilisera "apt" intelligemment.

* Module [apt_repository](http://docs.ansible.com/ansible/apt_repository_module.html) :

~~~{.yaml}
- name: exemple
  apt_repository:
    repo: "deb https://artifacts.elastic.co/packages/5.x/apt stable main"
    filename: elastic
    state: present
~~~

L'indication "filename" permet de référencer le dépôt dans `/etc/apt/sources.list.d/<filename>.list`.

* Module [mysql_user](http://docs.ansible.com/ansible/mysql_user_module.html) :

~~~{.yaml}
- mysql_user:
    name: mysqladmin
    password: my_password
    priv: "*.*:ALL,GRANT"
    state: present
    config_file: /root/.my.cnf
    update_password: on_create
~~~

Lorsqu'une réplication est en place, on peut choisir de ne pas propager l'action dans les binlogs, avec l'option `sql_log_bin: no`.

* module [mysql_variables](http://docs.ansible.com/ansible/latest/mysql_variables_module.html)

~~~{.yaml}
- mysql_variables:
    variable: read_only
    value: 1
~~~

Cela permet d'exécuter une commande du type "SET GLOBAL read_only = 1;" de manière idempotente.

* module [htpasswd](http://docs.ansible.com/ansible/latest/htpasswd_module.html)

~~~{.yaml}
- htpasswd:
    path: /etc/nginx/htpasswd_phpmyadmin
    name: jdoe
    password: 'PASSWORD'
    owner: root
    group: www-data
    mode: "0640"
~~~

Il nécessite la bibliothèque Python "passlib", installable sous Debian grace au paquet "python-passlib".

* Module [sysctl](http://docs.ansible.com/ansible/sysctl_module.html) :

~~~{.yaml}
- name: exemple
  sysctl:
    name: vm.max_map_count
    value: 262144
    sysctl_file: /etc/sysctl.d/elasticsearch.conf
~~~

* Module [alternatives](http://docs.ansible.com/ansible/alternatives_module.html) :

~~~{.yaml}
- alternatives:
    name: editor
    path: /usr/bin/vim.basic
~~~

* Module [service](http://docs.ansible.com/ansible/service_module.html) :

~~~{.yaml}
- name: exemple pour redémarrer un service (compatible avec sysvinit, systemd…)
  service: nginx
    state: restarted
~~~

* Module [openbsd_pkg](http://docs.ansible.com/ansible/openbsd_pkg_module.html) :

~~~{.yaml}
- openbsd_pkg:
    name: "{{ item }}"
    state: present
  with_items:
    - wget
    - vim--no_x11
~~~

* module [timezone](http://docs.ansible.com/ansible/timezone_module.html) :

~~~{.yaml}
- timezone:
    name: Europe/Paris
~~~

Si systemd est présent, le module utilise `timedatectl`.
Sinon, sur Debian il utilise "/etc/timezone" et reconfigure le paquet "tzdata".


* module [git](http://docs.ansible.com/ansible/latest/git_module.html) :

~~~{.yaml}
- git:
    repo: https://forge.evolix.org/evoadmin-web.git
    dest: /home/evoadmin/www
    version: master
    update: yes
~~~

Pour avoir plus d'infos sur un module :

~~~
# ansible-doc shell
> SHELL

  The [shell] module takes the command name followed by a li
  space-delimited arguments. It is almost exactly like the
  (…)
~~~

> *Note* : c'est pratique pour avoir la documentation exacte pour votre version d'Ansible. En effet, celle du site correspond à la dernière version et n'indique pas toujours toutes les différences.

### playbook

<http://docs.ansible.com/ansible/playbooks.html>

Un playbook va ensuite dérouler des actions qui seront organisées en _tasks_, [roles](#roles) et [handlers](#handlers).

Exemple de playbook simple :

~~~{.yaml}
---
- hosts: all

  tasks:
  - shell: echo hello World

# vim:ft=ansible:
~~~

Un playbook plus évolué :

~~~{.yaml}
---
- hosts: all
  gather_facts: yes
  become: yes

  vars_files:
  - 'vars/main.yml'

  vars:
    external_roles: ~/GIT/ansible-roles
    external_tasks: ~/GIT/ansible-public/tasks

  pre_tasks:
  - name: Minifirewall is stopped (temporary)
    service:
      name: minifirewall
      state: stopped

  roles:
  - "{{ external_roles }}/minifirewall"

  post_tasks:
  - include: "{{ external_tasks }}/commit_etc_git.yml"
    vars:
      commit_message: "Ansible run firewall.yml"

  handlers:
  - name: restart minifirewall
    service:
      name: minifirewall
      state: restarted

# vim:ft=ansible:
~~~

On lance des playbooks ainsi :

~~~
$ ansible-playbook PLAYBOOK.yml --limit HOSTNAME --forks 1

$ ansible-playbook PLAYBOOK_WITH_SUDO.yml --limit HOSTNAME --ask-become-pass
~~~

Options utiles pour [ansible-playbook](https://manpages.debian.org/cgi-bin/man.cgi?query=ansible-playbook&apropos=0&sektion=0&manpath=Debian+unstable+sid&format=html&locale=en) :

* `-vvvv` : très verbeux (utile notamment pour debug SSH quand on a une erreur _unreachable_)
* `-k` / `--ask-pass` : demande le mot de passe pour la connexion SSH
* `-K` / `--ask-become-pass` : demande le mot de passe pour l'escalade (via sudo, su, doas…)
* `-l` / `--limit HOSTNAME` : limite la connexion à un ou plusieurs serveurs (attention, par défaut c'est *all*, cf `/etc/ansible/hosts`)
* `-f` / `--forks N` : nombre de process lancés en parallèle (par défaut 5)… peut être utile de mettre à 1 pour ne pas paralléliser
* `-i` / `--inventory FILENAME/DIRNAME` : utiliser le fichier ou le dossier d'inventaire fournit en paramètre
* `-i` / `--inventory "example.com,"` : utilise un inventaire dynamique définie en paramètre (doit être un tableau)
* `-D` / `--diff` : montre un diff des changements effectués par les templates

#### Limiter l'exécution à certaines machines

Quelques exemples d'utilisation de l'option `--limit` (ou `l`) :

* limiter aux groupes _www_ et _sql_ (qui peuvent être indifféremment des groupes ou des serveurs) :

~~~
$ ansible-playbook -l "www:sql" playbook.yml
~~~

* limiter aux serveurs _foo-www01_, _foo-lb01_, _foo-filer_… :

~~~
$ ansible-playbook -l "foo-*" playbook.yml
~~~

* limiter aux 10 premiers serveurs de l'inventaire (utile pour faire par paquets) :

~~~
$ ansible-playbook -l "*[0:9]" playbook.yml
~~~

* puis à ceux restants :

~~~
$ ansible-playbook -l "*[10:]" playbook.yml
~~~

Il est de toute façon préférable de ne pas mettre `all` dans le champs `hosts` dans le playbook pour éviter un oubli.

### handlers

Les **handlers** sont des actions définies dans un playbook, qui ne sont exécutées que dans certains cas.
On utilise l'option `notify` au sein d'un module pour évoquer un handler. Celui-ci ne sera exécuté que si un module a effectivement provoqué un changement.
L'usage classique est de recharger un service après une modification de configuration : si la modification est réalisée => le service est rechargé, si la modification est déjà effectuée => aucune action.

Par défaut, l'exécution effective des handlers se fait **une seule fois** à la fin du playbook, quel que soit le nombre de fois où il a été demandé pendant l'exécution.

Exemple :

~~~{.yaml}
tasks:
- name: copy Apache configuration
  copy: (…)
  notify: Restart Apache

handlers:
- name: Restart Apache
  service:
    name: apache2
    state: restarted
~~~

Dans des rôles longs, nous conseillons de purger les handlers de temps en temps (en fin de groupe d'action). En effet, si un playbook est interrompu les handlers ne sont pas forcément exécutés alors que l'action qui les a déclenchés a bien eu lieu. On insère alors l'action suivante :

~~~{.yaml}
- meta: flush_handlers
~~~

> *Note*  : n'importe quel module peut être utilisé comme handler.

### roles

<http://docs.ansible.com/ansible/playbooks_roles.html>

Lorsqu'on a besoin d'utiliser des fichiers ou _templates_ à copier, des variables avec des valeurs par défaut, des handlers… on peut organiser tout cela dans un **role** en respectant la structure conventionnelle suivante :

~~~
foo
├── defaults
│   └── main.yml
├── files
├── handlers
│   └── main.yml
├── meta
│   └── main.yml
├── README.md
├── tasks
│   └── main.yml
├── templates
├── tests
│   ├── inventory
│   └── test.yml
└── vars
    └── main.yml
~~~

Cette structure permet à Ansible de retrouver automatiquement les fichiers et de les rendre disponibles dans l'exécution du rôle.

À titre d'exemple, voici des rôles Ansible que nous utilisons : <https://forge.evolix.org/projects/ansible-roles/repository>

### inventory

<http://docs.ansible.com/ansible/intro_inventory.html>

La partie **inventory** correspond à la description de l'inventaire des serveurs à configurer et inclus un mécanisme de configuration individuelle et par groupe.

Il permet d'indiquer la liste des machines concernées par Ansible (peut être limité lors de l'exécution de la commande par l'option `-l`) et de pouvoir les ranger dans des groupes.

Exemple:

~~~
hostname.internal

[httpservers]
machine[01:57].example.com
http.example.com:2222

[dbservers]
machine12.example.com
machine50.example.com
m[a:o]chine52.example.com
alias ansible_port=2222 ansible_host=192.0.2.42

[client]
host1 http_port=80 maxRequestsPerChild=808 # des variables qui seront automatiquement auto-completées liées à cet host

[commercant]
mercerie
chapeautier

[commercant:vars]
ntp_server=ntp.mercerie.example.com
proxy=proxy.mercerie.example.com
~~~

* `hostname.internal` : serveur présent dans aucun groupe
* `[httpservers]` : le nom du groupe (pour les serveurs http). Les noms de hosts qui suivent appartiendront à ce groupe
* `machine[01:57].example.com` : on peut indiquer une [pseudo-]expression régulière - ici ajoutera les machines _machine01.example.com_, _machine02.example.com_, _machine03.example.com_… _machine57.example.com_
* `HOSTNAME:2222` : ansible se connecte par ssh, et _HOSTNAME_ a un port SSH d'écoute différent qui est 2222
* `[dbservers]` : groupe pour les serveurs de base de données
* `machine50.example.com` : cette machine est déjà présente dans le groupe _httpservers_, mais sera aussi accessible à partir du groupe _dbservers_
* `alias ansible_port=2222 ansible_host=192.0.2.42` : la machine _alias_ n'a pas un vrai FQDN mais pointera vers _192.0.2.42_ car on a indiqué des variables propres à Ansible. Il est existe aussi `ansible_connection` (local ou ssh) ou `ansible_user` (le nom de l'utilisateur de la machine distante avec lequel Ansible se connectera en ssh)
* `host1 http_port=80 maxRequestsPerChild=808` : des variables qui seront automatiquement disponibles pour les actions sur _host1_
* `[commercant:vars]` : des variables qui seront liées au groupe _commercant_.

On peut aussi créer des groupes de groupes en utilisant `:children`

On peut aussi découper le fichier "inventory" selon les groupes et les variables : <http://docs.ansible.com/ansible/intro_inventory.html#splitting-out-host-and-group-specific-data>

Les variables propres à Ansible : <http://docs.ansible.com/ansible/intro_inventory.html#list-of-behavioral-inventory-parameters>


### variables

Les variables sont un élément clé de la configuration des playbooks et roles. Exemple :

~~~{.yaml}
vars:
  ip: 192.0.2.42
  conf_file: /etc/foo.conf

tasks:
- command: echo {{ ip }} >> {{ conf_file }}
~~~

Les variables peuvent être définies à de multiples niveaux, chacun ayant une certaine précédence (extrait de la [documentation](http://docs.ansible.com/ansible/playbooks_variables.html#variable-precedence-where-should-i-put-a-variable)) :

* role defaults
* inventory vars
* inventory group_vars
* inventory host_vars
* playbook group_vars
* playbook host_vars
* host facts
* play vars
* play vars_prompt
* play vars_files
* registered vars
* set_facts
* role and include vars
* block vars (only for tasks in block)
* task vars (only for the task)
* extra vars (always win precedence)

Pour gérer de nombreuses variables dans un projet, on peut stocker toutes celles qui correspondent à un groupe de serveur dans un fichier portant le nom du groupe, ainsi que toutes celles d'un serveur en particulier dans un fichier du nom du serveur. Voici l'arborescence conseillée :

~~~
└── inventory
    ├── hosts              # fichier d'inventaire
    ├── group_vars         # dossier regrouppant …
    │   └── group1.yml     # … les variables du groupe "group1"
    │   └── group2.yml     # … les variables du groupe "group2"
    └── host_vars          # dossier regrouppant …
        └── hostname1.yml  # … les variables du serveur "hostname1"
        └── hostname2.yml  # … les variables du serveur "hostname2"
~~~

Les groupes sont définis dans le fichier d'[inventaire](http://docs.ansible.com/ansible/intro_inventory.html).

### Tags

<https://docs.ansible.com/ansible/playbooks_tags.html>

Les tags permettent de ranger/trier chaque tâche ou rôle dans une catégorie.

~~~{.yaml}
- name: Coucou
  debug:
    msg: "Saloute!"
  tags: message
~~~

On peut également utiliser les tags pour limiter/exclure des tâches :

~~~
$ ansible-playbook (…) --skip-tags "message"
~~~

On peut aussi n'exécuter que certains tags :

~~~
$ ansible-playbook (…) --tags "configuration,packages"
~~~

> *Note* : on peut également _taguer_ des rôles `include`.

### Register

`register` est un attribut d'action que l'on peut rajouter pour tout type de tâche et qui initialisera la variable (par le nom donné) avec les valeurs retournées par le module.
Pour `shell`, on a le droit à `.stdout`, `.stderr`, `.rc`… mais cela dépend des valeurs de retour du module.

Il est possible de consulter le contenu détaillé de la variable avec `debug` :

~~~{.yaml}
- stat:
    path: /etc/passwd
  register: st

- debug:
    var: st

- fail:
    msg: "Whoops! file ownership has changed"
  when: st.stat.pw_name != 'root'
~~~

Pour certains modules, `register` est presque un passage obligatoire pour une utilisation cohérente des éléments (stat…).

### Vault

<http://docs.ansible.com/ansible/latest/playbooks_vault.html>

Un Vault permet d'avoir un fichier protégé par un mot de passe.

Pour éditer un Vault nommé `foo.yml` (utilise l'éditeur configuré) :

~~~
# ansible-vault edit foo.yml
~~~

Pour consulter un Vault (sortie standard) :

~~~
# ansible-vault view foo.yml
~~~

Pour modifier le mot de passe d'un vault :

~~~
# ansible-vault rekey foo.yml
~~~

Pour créer un vault vide :

~~~
# ansible-vault create bar.yml
~~~

Pour créer un vault sur un fichier clair :

~~~
# ansible-vault encrypt baz.yml
~~~

Pour retirer le chiffrement d'un fichier chiffré :

~~~
# ansible-vault decrypt baz.yml
~~~

Pour utiliser vault, il faut préciser l'option `--ask-vault-pass` avec les commandes `ansible` ou `ansible-playbook`.


## Configuration

<https://docs.ansible.com/ansible/intro_configuration.html>

La configuration est lue dans l'ordre suivant :

* `ANSIBLE_CONFIG` (variable d'environnement)
* `./ansible.cfg`
* `~/.ansible.cfg`
* `/etc/ansible/ansible.cfg`

### ansible.cfg

Quelques options qui peuvent être utiles :

* `display_args_to_stdout` : mettre à `True` si on veut voir tout le contenu du _tasks_ executé pour chaque étape écrit sur _stdout_
* `display_skipped_hosts` : mettre à `False` si on ne veut pas voir affiché sur _stdout_ l'information d'un _task_ qui n'est pas exécuté _(le nom de variable est confu - mais il s'agit bien de l'affichage du task)_
* `error_on_undefined_vars` : mettre à `True` pour être sûr que le script Ansible s'arrête si une variable n'est pas définie (alors qu'il y a utilisation de cette dernière dans une _task_)
* `force_color` : mettre à `1` pour forcer la couleur
* `forks` : le nombre de processus en parallèle possible lors déploiement du script Ansible sur nombreux _hosts_
* `hosts` : accès vers les _hosts_ par défaut (`all`)
* `private_key_file` : le chemin  pour la clé pem
* `remote_port` : le port SSH par défaut (`22`)
* `remote_user` : l'utilisateur pour la connexion SSH par défaut (`root`)
* `retry_files_enabled` : mettre à `True` pour la création de fichier `.retry` après un échec d'Ansible, pour reprendre le travail précédent - ajouté en argument dans l'appel de la commande


## Jinja

Ansible utilise la bibliothèque [Jinja2](http://jinja.pocoo.org/docs/2.10/templates/) pour ses templates, ses filtres, ses conditions…

* fusionner et dédoublonner 2 listes :

~~~
a: [1, 2, 3]
b: [3, 4, 5]
c: a | union(b) | unique
~~~

Il existe plein de [filtres sur les listes](http://docs.ansible.com/ansible/latest/playbooks_filters.html#list-filters) ; `union`, `intersect`, `difference`, `unique`, `sort`…

* liste avec valeur par défaut (variable vide, indéfinie ou liste vide)

~~~
a: []
c: a | default([1, 2], true)
~~~

C'est le second paramètre (`true`) qui permet à `default()` d'agir lorsque la variable `a` n'est pas seulement nulle ou indéfinie, mais aussi en cas de chaîne vide, tableau vide…

* boucler sur un attribut d'un dictionnaire

On veut par exemple créer les groupes des utilisateurs du dictionnaire suivant :

~~~
users:
  user1:
    name: user1
    groups: group1

  user2:
    name: user2
    groups: group2

  user3:
    name: user3
    groups: group1
~~~ 

On va donc faire une boucle avec la liste des groupes définit dans l'attribut "groups" :

~~~
- name: "Create secondary groups"
  group:
    name: "{{ item }}"
  with_items: "{{ users.values() | map(attribute='groups') | list | unique }}"
~~~

## Erreurs

Les messages d'erreurs ne sont pas le point fort d'Ansible. Il n'est pas toujours clair de savoir si c'est un soucis de syntaxe YAML, un problème de sémantique d'Ansible ou une erreur dans l'utilisation de Jinja2. De plus, Ansible tente de faire des recommandations, mais elles sont des fois plus déroutantes qu'éclairantes. En voici quelques unes que nous avons rencontrées.

### unbalanced jinja2 block or quotes

~~~
fatal: [HOSTNAME]: FAILED! => {"failed": true, "reason": "error while splitting arguments, either an unbalanced jinja2 block or quotes"}
~~~

Bien vérifier la syntaxe : cela peut être un guillemet mal fermé (ou mélange simples/doubles guillemets), ou encore histoire de crochet devenant une parenthèse…

### Missing required arguments

~~~
fatal: [HOSTNAME]: FAILED! => {"changed": false, "failed": true, "msg": "missing required arguments: section"}
~~~

Le message est assez clair, donc bien relire la doc du module sur Ansible pour ajouter les arguments obligatoires pour ce module.

### Requires stdlib json or simplejson module

~~~
fatal: [HOSTNAME]: FAILED! => {"changed": false, "failed": true, "msg": "Error: ansible requires the stdlib json or simplejson module, neither was found!"}
~~~

~~~
# apt install python-simplejson
~~~


## Astuces

### Vérifier un playbook

* Vérifier la syntaxe :

~~~
$ ansible-playbook --syntax-check my-experimental-playbook.yml
~~~

Voir <http://www.yamllint.com/>

* vérifier les actions qui vont être faites (mode `dry-run`) sans rien exécuter :

~~~
$ ansible-playbook --check my-experimental-playbook.yml
~~~

> *Note* : certaines actions ne sont pas exécutées en mode "check", cela peut donc perturber celles qui sont bassées dessus.

* avoir le diff des fichiers modifiés (ne marche pas avec les modules `replace`/`lineinfile` à priori) :

~~~
$ ansible-playbook --check --diff my-experimental-playbook.yml
~~~

### Stopper l'éxecution du code

Pour par exemple, stopper le code à un moment pour lire les valeurs d'une variables

~~~{.yaml}
- debug:
    var: foo

- command: /bin/false
~~~

ou

~~~{.yaml}
- debug:
    var: foo

- fail:
    msg: "FAIL"
~~~

ou

~~~{.yaml}
- debug:
    var: foo

- pause:
~~~

### Lancement tâches hosts asynchrone

Pour éviter que les différentes tâches s'appliquent une par une sur tout les hosts impliqués par l'exécution du playbook, on peut utiliser l'option `strategy` à la valeur `free` pour que chaques tâches sur un host puisse continuer dès la fin de son exécution sans attendre l'état des autres hosts concernés en cours.

~~~{.yaml}
- hosts: all
  (…)
  strategy: free
~~~

> *Note*: ne plus se fier au texte `host changed` après texte de la tâche, car il pourrait s'agir d'une autre tâche affichée plus en haut dans le texte de l'historique.

### Fréquence des hosts

Lors de l'exécution d'un play, on peut indiquer une fréquence sur le nombre d'hôtes concernés par l'éxecution du playbook.

* `Fork` pour le nombre d'hôtes simultanés (modifiable dans le fichier _ansible.cfg_ - mettre une valeur importante > centaine).
* `serial` en en-tête contenant une valeur numérique qui représente le nombre de machines pour chaque tour d'éxecution de playbook, ou un pourcentage par rapport à la liste inventory concerné.

### Cowsay

<https://support.ansible.com/hc/en-us/articles/201957877-How-do-I-disable-cowsay->

Si la commande `cowsay` est disponible sur votre machine, vous verrez un message à la fin :

~~~
 ____________________
< NO MORE HOSTS LEFT >
 --------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||
 ____________
< PLAY RECAP >
 ------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||
~~~

Pour le désactiver : `export ANSIBLE_NOCOWS=1`

Disponible aussi dans la conf du fichier `/etc/ansible/ansible.cfg`

### Conditions dans fichier jinja2

<http://jinja.pocoo.org/docs/dev/templates/#builtin-tests>

~~~
{% if python_is_installed is defined %}
Ansible devrait marcher -pardi!
{% endif %}
~~~

Voir la doc pour plus de détails : <http://jinja.pocoo.org/docs/dev/>

### Lire une entrée au clavier

<https://docs.ansible.com/ansible/playbooks_prompts.html>

S'il manque une valeur pour la suite du script, soit on le gère en mettant une erreur, ou une valeur par défaut, mais sinon on peut aussi demander une saisie clavier :

~~~{.yaml}
vars_prompt:
- name: 'prenom'
  prompt: 'Quel est votre prénom ?'
  private: no

tasks:
- debug:
    var: prenom
~~~

Malheureusement pour le moment, cela doit se situer avant `tasks`.

Si on veut utiliser cette variable dans une tâche, il faut simplement utiliser le nom de la variable, et si on veut l'utiliser (explicitement) pour un play ne se trouvant pas dans le même fichier (donc ici la variable dans autre.yml s'appelera _prenom_de_autre_ et non prenom) :

~~~{.yaml}
- include: './tasks/autre.yml'
  vars:
    prenom_de_autre: prenom
~~~

### Exécuter un playbook en mode interactif

<https://docs.ansible.com/ansible/playbooks_startnstep.html>

~~~
$ ansible-playbook playbook.yml --step
~~~

### Ne pas lancer une commande shell si le fichier existe

En indiquant l'argument `creates` indiquant le chemin de fichier lors de l'utilisation du module shell, cette tâche ne s'exécutera que si le fichier indiqué par `creates` n'existe pas.
Le corollaire est possible avec l'argument `removes` qui empêche l'exécution si le fichier n'existe pas.

Ces arguments sont disponibles pour certains modules (comme `shell`).

C'est beaucoup plus simple et rapide que de tester le fichier par le module `stat` juste avant.

### Lancer tâche sur machine précise (voire localhost)

<https://docs.ansible.com/ansible/playbooks_delegation.html#delegation>

~~~{.yaml}
- name: /etc/hosts
  command: cat /etc/hosts
  register: tmp
  delegate_to: localhost

- debug:
    var: tmp.stdout
~~~

Pour une exécution locale, on peut aussi utiliser l'attribut `local_action`.

### Ne lancer tâche qu'une seule fois

<https://docs.ansible.com/ansible/playbooks_delegation.html#run-once>

~~~{.yaml}
- name: Début installation, envoie email
  run_once: true
  (…)
~~~

Si cet attribut est utilisé avec `delegate_to`, alors cette machine sera la seule à exécuter cette tâche. Sinon, c'est la première dans la liste de l'inventaire.

### Appliquer une tâche à une liste (tableau) -> boucle

#### with_items

~~~{.yaml}
- name: Manger les fruits
  command: eat '{{ item }}'
  with_items:
  - Apple
  - Orange
  - Strawberry
  - Mango
~~~

Par exemple pour l'installation de plusieurs nouveaux paquets :

~~~{.yaml}
---
- hosts: localhost

  tasks:
  - apt:
      name: '{{ item }}'
      state: present
    with_items:
    - cmatrix
    - tetrinet-server
    - tetrinet-client
    - xtel
    - xtell
~~~

Même si il y aura plusieurs paquets installés, cela ne comptera que pour *un* changement (`changed=1`).
Cette tâche appellera un par un les éléments de la liste (présents dans `with_items`) pour le module.

#### with_nested

Pour croiser les éléments des items :

~~~{.yaml}
tasks:
- include: "./ajout_utilisateur_sur_machine.yml"
  vars:
    user: "{{ item[0] }}"
    server: "{{ item[1] }}"
  with_nested:
  - [ 'alice', 'bob' ]
  - [ 'machine1', 'machine2', 'machine-backup' ]
~~~

Cela a pour effet d'exécuter l'inclusion pour `alice` pour chacune des 3 machines, puis pour `bob` pour chacune des 3 machines.

#### with_dict

Avec hash :

~~~{.yaml}
users:
  bob:
    name: Bob
    uid: 1000
    home: /home/bob
  alice:
    name: Alice
    uid: 1001
    home:

tasks:
- user:
    name: "{{ item.key }}"
    comment: "{{ item.value.name }}"
    uid: "{{ item.value.uid }}"
    home: "{{ item.value.home }}"
    with_dict: "{{ users }}"
~~~

#### [with_first_found](http://docs.ansible.com/ansible/playbooks_loops.html#finding-first-matched-files)

Permet de prendre le premier fichier trouvé :

~~~{.yaml}
- name: Copy HAProxy configuration
  template:
    src: "{{ item }}"
    dest: /etc/haproxy/haproxy.cfg
    force: yes
  with_first_found:
  - "haproxy.cfg/{{ inventory_hostname }}"
  - "haproxy.cfg/{{ host_group }}"
  - "aproxy.cfg/default"
~~~

De cette manière, si un fichier portant le nom du serveur en cours existe, il sera utilisé, sinon on cherche un fichier du nom du groupe du serveur et enfin on cherche un fichier par défaut, valable pour tous les serveurs qui n'ont pas de configuration spécifique ou de groupe.

### Se connecter sous un autre utilisateur UNIX

Par défaut, l'utilisateur se connectant sur le serveur distant l'utilisateur UNIX courant. On peut soit le préciser dans le fichier de conf principal d'Ansible avec `remote_user: michu`, dans l'inventaire pour un groupe ou un serveur précis ou encore en l'indiquant en argument lors de l'éxecution du playbook.

~~~
$ ansible-playbook -u michu -k play.yml
~~~

### Éviter que la commande shell n'indique d'élement 'changed'

Sur tous les modules, chaque tâche retourne un statut sur son résultat :

* `ok` : aucune modification n'a été nécessaire
* `changed` : une modification a eu lieu par rapport à l'état précédent (droits fichiers…)
* `failed` : une erreur s'est produite

Pour des modules comme `shell`, `command`… Ansible ne peut savoir si un changement a eu lieu ou pas. Il indique alors toujours `changed`.

Il est possible de forcer le statut du changement :

~~~{.yaml}
- command: date
  changed_when: False
~~~

### Voir variables disponibles

~~~
$ ansible -m setup <hostname>
HOSTNAME | SUCCESS => {
    "ansible_facts": {
        (…)
        "ansible_architecture": "x86_64",
        "ansible_bios_date": "12/01/2006",
        "ansible_bios_version": "VirtualBox",
        "ansible_cmdline": {
            "BOOT_IMAGE": "/boot/vmlinuz-3.16.0-4-amd64",
            "quiet": true,
            "ro": true,
            "root": "UUID=37de3cbb-3f28-48d2-a4eb-c893a2f2fbc3"
        },
        "ansible_date_time": {
            "date": "2016-05-06",
            "day": "06",
            "epoch": "1462546886",
            "hour": "17",
            (…)
        },
        "ansible_default_ipv4": {
(…)
}
~~~

~~~
$ ansible -m debug -a "var=hostvars['hostname']" localhost
~~~

Pour récupérer toutes les adresses MAC des machines :

~~~{.yaml}
---
- hosts: all
  gather_facts: true

  tasks:
  - debug:
      var: ansible_eth0.macaddress
~~~

que l'on pourra combiner par exemple avec un pipe en ligne de commande :

~~~
$ ansible-playbook mac_address.yml | grep ansible_eth0.macaddress | sed 's/^\s*"ansible_eth0.macaddress": "\(.*\)"/\1/'
~~~

Il est possible aussi d'accéder aux variables d'environnement shell :

~~~
"{{ lookup('env','HOME') }}"
~~~

### Pré-requis OpenBSD

Voici les étapes nécessaires à l'utilisation d'Ansible sur des serveurs OpenBSD.

Installer _Python_ :

~~~
# pkg_add -z python-3 sudo
~~~

et surcharger la variable `ansible_python_interpreter` dans le fichier _inventory_ :

~~~
[openbsd]
serveur.example.com

[openbsd:vars]
ansible_python_interpreter=/usr/local/bin/python2.7
~~~

### Ansible Vault via GPG

Afin de ne pas avoir à taper son mot de passe Vault à chaque utilisation, on peut stocker son mot de passe Vault dans un fichier chiffré par [GPG](HowtoGPG). Au préalable, il faut configurer GPG pour utiliser l'[agent GPG](HowtoGPG#agent-gpg).

Ensuite, créer le script suivant dans `~/bin/open_vault.sh`

~~~
#!/bin/sh
gpg --quiet --batch --use-agent --decrypt ~/.ansible/vault.gpg
~~~

Rendre ce script exécutable :

~~~
chmod +x ~/bin/open_vault.sh
~~~

Configurer Ansible pour utiliser ce script comme source du mot de passe Ansible Vault dans `~/.ansible.cfg` :

~~~
[defaults]
vault_password_file= ~/bin/open_vault.sh
~~~

Stocker le mot de passe Ansible Vault dans un fichier chiffré via GPG :

~~~
echo "VAULT_PASSWORD" | gpg -e -o ~/.ansible/vault.gpg
~~~

Ansible va maintenant automatiquement déchiffrer les fichiers Vault via votre agent GPG et le fichier `~/.ansible/vault.gpg`.

### Git diff pour fichier vault

Les diff de fichier chiffrés avec ansible-vault ne sont pas lisibles par défaut car ils s'appliquent sur le contenu chiffré des fichiers et non pas sur le contenu réel.

On peux modifier cela, en modifiant sa config GIT dans son fichier **~/.gitconfig** :

~~~
[diff "ansible-vault"]
        textconv = ansible-vault view
        cachetextconv = false
~~~

Et en appliquant cette config au fichier vault dans ses dépôts Git dans le fichier **.gitattributes** :

~~~
vars/evolinux-secrets.yml diff=ansible-vault
~~~

### Comparer des versions

Dans le cas où on ne veut pas faire la même chose suivant la version
sur lequelle on exécute la tâche, on peut utiliser
[version_compare](https://docs.ansible.com/ansible/latest/playbooks_tests.html#version-comparison).

Un cas concret :

~~~{.yaml}
- name: Install monitoring-plugins on OpenBSD 5.6 and later
  openbsd_pkg:
    name: monitoring-plugins
    state: present
  when: ansible_distribution_version | version_compare("5.6",'>=')

- name: Install nagios-plugins on OpenBSD before 5.6
  openbsd_pkg:
    name: nagios-plugins
    state: present
  when: ansible_distribution_version | version_compare("5.6",'<')
~~~

### Erreur : /usr/local/bin/python2.7: not found

Si vous obtenez une erreur du type :

~~~
$ ansible -m ping foo
foo | FAILED! => {
    "changed": false, 
    "failed": true, 
    "module_stderr": "/bin/sh: 1: /usr/local/bin/python2.7: not found\n", 
    "module_stdout": "", 
    "msg": "MODULE FAILURE"
}
~~~

Pour une raison inconnue, Ansible détecte mal le chemin vers Python.
Vous pouvez le forcer en utilisant l'option `-e 'ansible_python_interpreter=/usr/bin/python2.7'`.

### Export HTML d'un playbook

Pour enregistrer la sortie d'exécution d'un playbook dans un fichier HTML (en gardant les couleurs et les warnings qui vont normalement sur la sortie d'erreur), on peut utiliser le paquet `aha` :

~~~
$ ANSIBLE_FORCE_COLOR=true ansible-playbook playbook.yml 2>&1 | aha --black > output.html
~~~

## Exemples

Voir [/HowtoAnsible/Exemples]().

## Ressources utiles

* [Documentation officielle](http://docs.ansible.com/ansible/) (voir notamment la partie [Best Practices](http://docs.ansible.com/ansible/playbooks_best_practices.html))
* Vidéos [ansible-best-practices](https://www.ansible.com/ansible-best-practices) et [ansible-tips-and-tricks](https://www.ansible.com/ansible-tips-and-tricks)
* [Ansible 101 - on a Cluster of Raspberry Pi 2s](https://www.youtube.com/watch?v=ZNB1at8mJWY)
* Sysadmin Casts (épisodes [43](https://sysadmincasts.com/episodes/43-19-minutes-with-ansible-part-1-4), [45](https://sysadmincasts.com/episodes/45-learning-ansible-with-vagrant-part-2-4), [46](https://sysadmincasts.com/episodes/46-configuration-management-with-ansible-part-3-4) et [47](https://sysadmincasts.com/episodes/47-zero-downtime-deployments-with-ansible-part-4-4))
* [How Twitter uses Ansible](https://www.youtube.com/watch?v=fwGrKXzocg4) (AnsibleFest 2014)
* [Orchestration with Ansible at Fedora Project](http://fr.slideshare.net/AdityaPatawari/ansible-33223245)