Filtres d'Encodeur de Configuration

Ceci est un rôle Ansible utilisé pour fournir les filtres d'encodeur de configuration comme dépendance à un autre rôle Ansible.

.. image:: https://travis-ci.org/jtyr/ansible-config_encoder_filters.svg?branch=master :target: https://travis-ci.org/jtyr/ansible-config_encoder_filters

Table des Matières

• Motivation_
• Exemple_
• Utilisation_
• Installation_
• Encodeurs pris en charge_
  • encode_apache_
  • encode_erlang_
  • encode_haproxy_
  • encode_ini_
  • encode_json_
  • encode_logstash_
  • encode_lua_
  • encode_nginx_
  • encode_pam_
  • encode_toml_
  • encode_xml_
  • encode_yaml_
• Utilitaires_
  • template_replace_
• Tests_
• Licence_
• Auteur_

---

.. _Motivation:

Motivation

Ansible Galaxy contient de nombreux rôles utiles. Certains d'entre eux existent en de nombreuses variations qui se distinguent uniquement par leur paramétrage. Le paramétrage est souvent utilisé principalement dans les modèles qui génèrent le fichier de configuration. Un bon exemple de ces problèmes est les rôles pour Nginx dont on peut trouver presque 200 dans Ansible Galaxy.

Nginx peut être configuré de manière infinie, et il est donc presque impossible de créer un fichier modèle Ansible qui saisirait toutes les variations possibles de la configuration. Même si un rôle approprié est trouvé, les utilisateurs souhaitent souvent ajouter des personnalisations supplémentaires. C'est à ce moment que les gens ont tendance à cloner le rôle et à ajouter les paramètres manquants. Certains essaient de réintégrer le changement dans le rôle original en créant une demande de fusion (PR), mais parfois ce changement n'est pas accepté par le mainteneur du rôle original et l'utilisateur finit par maintenir sa propre copie éternellement.

C'est pourquoi les filtres d'encodeur de configuration ont été développés pour faciliter la création de rôles Ansible avec une configuration universelle. La structure du fichier de configuration est décrite comme une structure de données YAML stockée dans une variable. La variable, avec le filtre d'encodeur de configuration, est ensuite utilisée dans le fichier modèle utilisé pour générer le fichier de configuration final. Cette approche permet de changer le paradigme de la pensée sur les fichiers de configuration en les considérant comme des structures de données. La structure de données peut être générée de manière dynamique, ce qui permet de créer une configuration réellement universelle.

.. _Example:

Exemple

Imaginons le fichier INI suivant :

.. code:: ini

[section1]
option11=value11
option12=value12

Ce fichier de configuration peut être décrit comme une structure de données YAML :

.. code:: yaml

myapp_config:
  section1:
    option11: value11
    option12: value12

La variable est ensuite utilisée avec le filtre d'encodeur de configuration encode_ini dans le fichier modèle myapp.cfg.j2 comme suit :

.. code:: jinja2

{{ myapp_config | encode_ini }}

Enfin, le fichier modèle est utilisé dans une tâche comme ceci :

.. code:: yaml

- name: Créer un fichier de configuration
  template:
    src: myapp.cfg.j2
    dest: /etc/myapp/myapp.cfg

Lorsque la tâche est exécutée, elle crée exactement le même fichier que le fichier INI original.

Ainsi, nous pouvons décrire la configuration comme une structure de données qui est ensuite convertie en format de fichier de configuration final avec le filtre d'encodeur de configuration.

Pour modifier la configuration ci-dessus, nous devrions écraser myapp_config, ce qui n'est pas très pratique. Par conséquent, nous divisons la variable monolithique en un ensemble de variables qui nous permettront de changer n'importe quelle partie de la configuration sans avoir besoin de remplacer toute la structure de données :

.. code:: yaml

myapp_config_section1_option11: value11
myapp_config_section1_option12: value12

myapp_config_section1__default:
  option11: "{{ myapp_config_section1_option11 }}"
  option12: "{{ myapp_config_section1_option12 }}"

myapp_config_section1__custom: {}

myapp_config_default:
  section1: "{{
    myapp_config_section1__default | combine(
    myapp_config_section1__custom) }}"

myapp_config__custom: {}

myapp_config: "{{
  myapp_config__default | combine(
  myapp_config__custom) }}"

De cette façon, si nous voulons changer la valeur de option11, nous n'écrasons que la variable myapp_config_section1_option11 :

.. code:: yaml

myapp_config_section1_option11: Ma nouvelle valeur

Si nous voulons ajouter une nouvelle option dans la section1, nous l'ajoutons à la variable myapp_config_section1__custom qui est ensuite fusionnée avec la liste d'options par défaut :

.. code:: yaml

myapp_config_section1__custom:
  section13: value13

Et si nous voulons ajouter une nouvelle section, nous l'ajoutons à la variable myapp_config__custom qui est ensuite fusionnée avec la liste par défaut des sections :

.. code:: yaml

myapp_config__custom:
  section2:
    option21: value21

Ce qui précède montre un exemple pour les fichiers de configuration INI uniquement, mais le même principe peut être utilisé pour tous les encodeurs de configuration pris en charge listés ci-dessous.

.. _Usage:

Utilisation

Les filtres d'encodeur de configuration peuvent être utilisés dans n'importe quel rôle Ansible en ajoutant le rôle config_encoder_filters à la liste des dépendances dans le fichier meta/main.yml :

.. code:: yaml

dependencies:
  - config_encoder_filters

L'utilisation directement depuis un Playbook nécessite d'ajouter le config_encoder_filters à la liste des rôles :

.. code:: yaml

- name: Mon test Play
  hosts: all
  roles:
    - config_encoder_filters
  tasks:
    - name: Créer un fichier de configuration
      template:
        src: my.conf.j2
        dest: /tmp/my.conf

.. _Installation:

Installation

Le rôle peut être téléchargé soit via la commande Ansible Galaxy :

.. code:: shell

$ ansible-galaxy install jtyr.config_encoder_filters,master,config_encoder_filters

ou via le fichier des exigences d'Ansible Galaxy :

.. code:: shell

$ cat ./requirements.yaml
---

- src: https://github.com/jtyr/ansible-config_encoder_filters.git
  name: config_encoder_filters
$ ansible-galaxy -r ./requirements.yaml

ou via Git :

.. code:: shell

$ git clone https://github.com/jtyr/ansible-config_encoder_filters.git config_encoder_filters

.. _Supported encoders:

Encodeurs pris en charge

Voici la liste des filtres d'encodeur de configuration pris en charge. Chaque filtre nécessite une structure de données spéciale comme entrée. Chaque filtre a également un ensemble de paramètres qui peuvent modifier son comportement.

.. _encode-apache:

encode_apache ^^^^^^^^^^^^^

Ce filtre aide à créer une configuration au format utilisé par le serveur web Apache. La structure de données attendue est la suivante :

.. code:: yaml

my_apache_vhost:
  content:
    - sections:
      - name: VirtualHost
        param: "*:80"
        content:
          - options:
            - DocumentRoot: /www/example1
            - ServerName: www.example.com
            - ErrorLog: /var/log/httpd/www.example.com-error_log
            - CustomLog:
              - /var/log/httpd/www.example.com-access_log
              - common
            - "#": Autres directives ici ...

La variable commence par content qui peut contenir une liste de sections ou options. Les sections contiennent ensuite une liste de sections individuelles avec les paramètres name, param et content. Le content peut à nouveau contenir une liste de sections ou options.

La variable ci-dessus peut être utilisée dans le fichier modèle comme suit :

.. code:: jinja2

{{ my_apache_vhost | encode_apache }}

La sortie d'un tel modèle serait :

.. code:: apache

<VirtualHost *:80>
  DocumentRoot /www/example1
  ServerName www.example.com
  ErrorLog /var/log/httpd/www.example.com-error_log
  CustomLog /var/log/httpd/www.example.com-access_log common
  # "Autres directives ici ..."
</VirtualHost>

Le filtre peut avoir les paramètres suivants :

• convert_bools=false

  Indique si les valeurs booléennes présentées sous forme de chaîne doivent être converties en une véritable valeur booléenne. Par exemple, var1: 'True' serait représenté sous forme de chaîne mais en utilisant convert_bools=true, il sera converti en booléen comme s'il était défini comme var1: true.

• convert_nums=false

  Indique si les nombres présentés sous forme de chaîne doivent être convertis en nombres. Par exemple, var1: '123' serait représenté sous forme de chaîne mais en utilisant convert_nums=true, il sera converti en nombre comme s'il était défini comme var1: 123. Il est également possible d'utiliser le typage YAML pour convertir une chaîne en nombre (par exemple, !!int "1234", !!float "3.14").

• indent=" "

  Définit l'unité d'indentation.

• level=0

  Indique le niveau initial de l'indentation. Une valeur 0 commence à indentuer depuis le début de la ligne. Si la valeur est supérieure à 0, le contenu est indenté par indent * level.

• quote_all_nums=false

  Les valeurs numériques ne sont pas mises entre guillemets par défaut. Ce paramètre obligera à mettre toutes les valeurs numériques entre guillemets.

• quote_all_strings=false

  Les valeurs de chaîne sont mises entre guillemets uniquement si elles contiennent un espace. Ce paramètre obligera à mettre toutes les chaînes entre guillemets, qu'elles contiennent ou non l'espace.

.. _encode-erlang:

encode_erlang ^^^^^^^^^^^^^

Ce filtre aide à créer une configuration au format Erlang. La structure de données attendue est la suivante :

.. code:: yaml

my_rabbitmq_config:
  - rabbit:
    - tcp_listeners:
      - '"127.0.0.1"': 5672
    - ssl_listeners:
      - 5671
    - ssl_options:
      - cacertfile: /path/to/testca/cacert.pem
      - certfile: /path/to/server/cert.pem
      - keyfile: /path/to/server/key.pem
      - verify: :verify_peer
      - fail_if_no_peer_cert: true
    - cluster_nodes:
        ::
          -
            - :"'rabbit@node1'"
            - :"'rabbit@node2'"
          - :disc

La variable consiste en des listes de dictionnaires. La valeur de la paire clé-valeur peut être une autre liste ou une simple valeur comme une chaîne ou un nombre. Les tuples Erlang peuvent être imposés en préfixant la valeur avec le caractère spécial spécifié dans atom_value_indicator. L'ordre dans le tuple peut être obtenu en utilisant la construction spéciale comme montré pour le tuple cluster_nodes dans l'exemple ci-dessus. L'indicateur commençant cette construction spéciale peut être défini avec le paramètre ordered_tuple_indicator.

La variable ci-dessus peut être utilisée dans le fichier modèle comme suit :

.. code:: jinja2

{{ my_rabbitmq_config | encode_erlang }}

La sortie d'un tel modèle serait :

.. code:: erlang

[
  {rabbit, [
      {tcp_listeners, [
          {"127.0.0.1", 5672}
      ]},
      {ssl_listeners, [
        5671
      ]},
      {ssl_options, [
          {cacertfile, "/path/to/testca/cacert.pem"},
          {certfile, "/path/to/server/cert.pem"},
          {keyfile, "/path/to/server/key.pem"},
          {verify, verify_peer},
          {fail_if_no_peer_cert, true}
      ]},
      {cluster_nodes,
        {[
          'rabbit@node1',
          'rabbit@node2'
        ], disc}}
  ]}
].

Le filtre peut avoir les paramètres suivants :

• atom_value_indicator=":"

  La valeur de ce paramètre indique la chaîne qui doit être ajoutée à une valeur chaîne pour être traitée comme une valeur d'atome.

• convert_bools=false

  Indique si les valeurs booléennes présentées sous forme de chaîne doivent être converties en une véritable valeur booléenne. Par exemple, var1: 'True' serait représenté sous forme de chaîne mais en utilisant convert_bools=true, il sera converti en booléen comme s'il était défini comme var1: true.

• convert_nums=false

  Indique si les nombres présentés sous forme de chaîne doivent être convertis en nombres. Par exemple, var1: '123' serait représenté sous forme de chaîne mais en utilisant convert_nums=true, il sera converti en nombre comme s'il était défini comme var1: 123. Il est également possible d'utiliser le typage YAML pour convertir une chaîne en nombre (par exemple, !!int "1234", !!float "3.14").

• indent=" "

  Définit l'unité d'indentation.

• level=0

  Indique le niveau initial de l'indentation. Une valeur 0 commence à indentuer depuis le début de la ligne. Si la valeur est supérieure à 0, le contenu est indenté par indent * level.

• ordered_tuple_indicator=":"

  Indicateur utilisé pour commencer la construction spéciale avec tuple ordonné.

.. _encode-haproxy:

encode_haproxy ^^^^^^^^^^^^^^

Ce filtre aide à créer une configuration au format utilisé par Haproxy. La structure de données attendue est la suivante :

.. code:: yaml

my_haproxy_config:
  - global:
    - daemon
    - maxconn 256
  - "# Ceci est la section par défaut"
  - defaults:
    - mode http
    - timeout:
        - connect 5000ms
        - client 50000ms
        - server 50000ms
  - frontend http-in:
    - "# Ceci est l'adresse/port de liaison"
    - bind *:80
    - default_backend servers
    - backend servers
    - server server1 127.0.0.1:8000 maxconn 32

La variable est une liste qui peut contenir une simple valeur chaîne ou un dictionnaire indiquant une section.

La variable ci-dessus peut être utilisée dans le fichier modèle comme suit :

.. code:: jinja2

{{ my_haproxy_config | encode_haproxy }}

La sortie d'un tel modèle serait :

.. code:: haproxy

global
  daemon
  maxconn 256

# Ceci est la section par défaut
defaults
  mode http
  timeout connect 5000ms
  timeout client 50000ms
  timeout server 50000ms

frontend http-in
  # Ceci est l'adresse/port de liaison
  bind *:80
  default_backend servers
  backend servers
  server server1 127.0.0.1:8000 maxconn 32

Le filtre peut avoir le paramètre suivant :

• indent=" "

  Définit l'unité d'indentation.

.. _encode-ini:

encode_ini ^^^^^^^^^^

Ce filtre aide à créer une configuration au format INI. La structure de données attendue est la suivante :

.. code:: yaml

my_rsyncd_config:
  uid: nobody
  gid: nobody
  use chroot: no
  max connections: 4
  syslog facility: local5
  pid file: /run/rsyncd.pid
  ftp:
    path: /srv/ftp
    comment: ftp area

La variable se compose de dictionnaires qui peuvent être imbriqués. Si la valeur de la paire clé-valeur au premier niveau est d'un type simple (chaîne, nombre, booléen), cette paire est considérée comme globale et traitée en premier. Si la valeur de la paire clé-valeur au premier niveau est un autre dictionnaire, la clé est considérée comme le nom de la section et le dictionnaire interne comme les propriétés de la section.

La variable ci-dessus peut être utilisée dans le fichier modèle comme suit :

.. code:: jinja2

{{ my_rsyncd_config | encode_ini }}

La sortie d'un tel modèle serait :

.. code:: ini

gid=nobody
max connections=4
pid file=/run/rsyncd.pid
syslog facility=local5
uid=nobody
use chroot=False

[ftp]
comment=ftp area
path=/srv/ftp

La valeur spéciale :code:!!!null peut être utilisée pour créer une clé sans valeur. Ceci doit être enveloppé entre guillemets pour éviter d'être évalué comme une étiquette YAML.

Prenons la structure de données suivante :

.. code:: yaml

config:
  myconf:
    key: value
    keyWithoutValue: '!!!null'

Cela deviendrait :

.. code:: ini

[myconf]
key=value
keyWithoutValue

Le filtre peut avoir les paramètres suivants :

• comment="#"

  Sign utilisé pour commenter des lignes lorsque section_is_comment=true.

• delimiter="="

  Signal séparant la propriété et la valeur. Par défaut, il est défini sur '=', mais peut également être défini par exemple sur ' = '.

• indent=""

  Indente les clés avec la chaîne spécifiée. Par exemple, indent="\t".

• quote=""

  Définit le formatage de la valeur. Utilisez quote="'" ou quote='"'.

• section_is_comment=false

  Si ce paramètre est défini sur true, la valeur de la section sera utilisée comme commentaire pour les propriétés suivantes de la section.

• ucase_prop=false

  Indique si la propriété doit être mise en majuscule.

.. _encode-json:

encode_json ^^^^^^^^^^^

Ce filtre aide à créer une configuration au format JSON. La structure de données attendue est la suivante :

.. code:: yaml

my_sensu_client_config:
  client:
    name: localhost
    address: 127.0.0.1
    subscriptions:
      - test

Parce que le JSON est très similaire au YAML, la variable se compose de dictionnaires dont la valeur peut être soit un type simple (nombre, chaîne, booléen), soit une liste ou un autre dictionnaire. Tout peut être imbriqué à n'importe quel niveau.

La variable ci-dessus peut être utilisée dans le fichier modèle comme suit :

.. code:: jinja2

{{ my_sensu_client_config | encode_json }}

La sortie d'un tel modèle serait :

.. code:: json

{
  "client": {
    "address": "127.0.0.1",
    "name": "localhost",
    "subscriptions": [
      "test"
    ]
  }
}

Le filtre peut avoir les paramètres suivants :

• convert_bools=false

  Indique si les valeurs booléennes présentées sous forme de chaîne doivent être converties en une véritable valeur booléenne. Par exemple, var1: 'True' serait représenté sous forme de chaîne mais en utilisant convert_bools=true, il sera converti en booléen comme s'il était défini comme var1: true.

• convert_nums=false

  Indique si les nombres présentés sous forme de chaîne doivent être convertis en nombres. Par exemple, var1: '123' serait représenté sous forme de chaîne mais en utilisant convert_nums=true, il sera converti en nombre comme s'il était défini comme var1: 123. Il est également possible d'utiliser le typage YAML pour convertir une chaîne en nombre (par exemple, !!int "1234", !!float "3.14").

• indent=" "

  Définit l'unité d'indentation.

• level=0

  Indique le niveau initial de l'indentation. Une valeur 0 commence à indentuer depuis le début de la ligne. Si la valeur est supérieure à 0, le contenu est indenté par indent * level.

.. _encode-logstash:

encode_logstash ^^^^^^^^^^^^^^^

Ce filtre aide à créer une configuration au format utilisé par Logstash. La structure de données attendue est la suivante :

.. code:: yaml

my_logstash_config:
  - :input:
      - :file:
          path: /var/log/httpd/access_log
          start_position: beginning
  - :filter:
      - ':if [path] =~ "access"':
          - :mutate:
              replace:
                type: apache_access
          - :grok:
              match:
                message: "%{COMBINEDAPACHELOG}"
          - :date:
              match:
                - timestamp
                - dd/MMM/yyyy:HH:mm:ss Z
      - ':else if [path] =~ "error"':
          - :mutate:
              replace:
                type: "apache_error"
      - ':else':
          - :mutate:
              replace:
                type: "random_logs"
  - :output:
      - :elasticsearch:
          hosts:
            - localhost:9200
      - :stdout:
          codec: rubydebug

La variable consiste en une liste de sections où chaque section est préfixée par un caractère spécial spécifié par le section_prefix (: par défaut). La valeur des sections de premier niveau peut être soit une autre section, soit un dictionnaire. La valeur du dictionnaire peut être une valeur simple, une liste ou un autre dictionnaire.

La variable ci-dessus peut être utilisée dans le fichier modèle comme suit :

.. code:: jinja2

{{ my_logstash_config | encode_logstash }}

La sortie d'un tel modèle serait :

.. code:: logstash

input {
  file {
    path => "/var/log/httpd/access_log"
    start_position => "beginning"
  }
}
filter {
  if [path] =~ "access" {
    mutate {
      replace => {
        "type" => "apache_access"
      }
    }
    grok {
      match => {
        "message" => "%{COMBINEDAPACHELOG}"
      }
    }
    date {
      match => [
        "timestamp",
        "dd/MMM/yyyy:HH:mm:ss Z"
      ]
    }
  }
  else if [path] =~ "error" {
    mutate {
      replace => {
        "type" => "apache_error"
      }
    }
  }
  else {
    mutate {
      replace => {
        "type" => "random_logs"
      }
    }
  }
}
output {
  elasticsearch {
    hosts => [
      "localhost:9200"
    ]
  }
  stdout {
    codec => "rubydebug"
  }
}

Le filtre peut avoir les paramètres suivants :

• backslash_ignore_prefix='@@@'

  Ce paramètre définit un ensemble de caractères qui peuvent être ajoutés à une chaîne pour empêcher les barres obliques d'être échappées dans la configuration résultante (par exemple, "@@@sshd(?:\[%{POSINT:[system][auth][pid]}\])?:" deviendra "sshd(?:\[%{POSINT:[system][auth][pid]}\])?:" au lieu de "sshd(?:\\[%{POSINT:[system][auth][pid]}\\])?:").

• convert_bools=false

  Indique si les valeurs booléennes présentées sous forme de chaîne doivent être converties en une véritable valeur booléenne. Par exemple, var1: 'True' serait représenté sous forme de chaîne mais en utilisant convert_bools=true, il sera converti en booléen comme s'il était défini comme var1: true.

• convert_nums=false

  Indique si les nombres présentés sous forme de chaîne doivent être convertis en nombres. Par exemple, var1: '123' serait représenté sous forme de chaîne mais en utilisant convert_nums=true, il sera converti en nombre comme s'il était défini comme var1: 123. Il est également possible d'utiliser le typage YAML pour convertir une chaîne en nombre (par exemple, !!int "1234", !!float "3.14").

• indent=" "

  Définit l'unité d'indentation.

• level=0

  Indique le niveau initial de l'indentation. Une valeur 0 commence à indentuer depuis le début de la ligne. Si la valeur est supérieure à 0, le contenu est indenté par indent * level.

• section_prefix=":"

  Ce paramètre spécifie quel caractère sera utilisé pour identifier la section Logstash.

.. _encode-lua:

encode_lua ^^^^^^^^^^

Ce filtre aide à créer une configuration dans un format compatible avec Lua. La structure de données attendue est la suivante :

.. code:: yaml

my_lua_config:
  fork: false
  external_addresses:
    - 1.2.3.4
    - 5.6.7.8
  admins:
    - [email protected]
  contact_info:
    abuse: [email protected]
    admin: [email protected]

Lua est un petit langage de script, souvent intégré dans des applications C/C++. Cet encodeur fait un effort pour correspondre aux fichiers de configuration vus dans la pratique, tout en permettant à l'utilisateur de personnaliser davantage la façon dont la sortie finale est rendue.

La variable ci-dessus peut être utilisée dans le fichier modèle comme suit :

.. code:: jinja2

{{ my_lua_config | encode_lua }}

La sortie d'un tel modèle serait :

.. code:: lua

fork = false;
external_addresses = {
    "1.2.3.4";
    "5.6.7.8";
}
admins = {
    "[email protected]";
}
contact_info = {
    abuse = "[email protected]";
    admin = "[email protected]";
}

Le filtre peut avoir les paramètres suivants :

• convert_bools=false

  Indique si les valeurs booléennes présentées sous forme de chaîne doivent être converties en une véritable valeur booléenne. Par exemple, var1: 'True' serait représenté sous forme de chaîne mais en utilisant convert_bools=true, il sera converti en booléen comme s'il était défini comme var1: true.

• convert_nums=false

  Indique si les nombres présentés sous forme de chaîne doivent être convertis en nombres. Par exemple, var1: '123' serait représenté sous forme de chaîne mais en utilisant convert_nums=true, il sera converti en nombre comme s'il était défini comme var1: 123. Il est également possible d'utiliser le typage YAML pour convertir une chaîne en nombre (par exemple, !!int "1234", !!float "3.14").

• sort_keys=false

  Indique si les clés doivent être triées lorsque la sortie est générée, ou laissées à la gestion implicite de l'ordre des dictionnaires par Python.

• indent=" "

  Définit l'unité d'indentation.

• level=0

  Indique le niveau initial de l'indentation. Une valeur 0 commence à indentuer depuis le début de la ligne. Si la valeur est supérieure à 0, le contenu est indenté par indent * level.

.. _encode-nginx:

encode_nginx ^^^^^^^^^^^^

Ce filtre aide à créer une configuration au format utilisé par le serveur web Nginx. La structure de données attendue est la suivante :

.. code:: yaml

my_nginx_vhost_config:
  - server:
    - listen 80
    - server_name $hostname
    - "location /":
      - root /srv/www/myapp
      - index index.html

Comme la configuration de Nginx est sensible à l'ordre, toute la configuration est définie comme une liste imbriquée. Comme il serait difficile de reconnaître combien d'éléments chaque définition de configuration contient, la valeur de l'élément de liste n'est pas davantage séparée en dictionnaire clé/valeur. Chaque ligne de la configuration est traitée soit comme une clé indiquant une autre liste imbriquée, soit simplement comme une chaîne.

La variable ci-dessus peut être utilisée dans le fichier modèle comme suit :

.. code:: jinja2

{{ my_nginx_vhost | encode_nginx }}

La sortie d'un tel modèle serait :

.. code:: nginx

server {
  listen 80;
  server_name $hostname;

  location / {
    root /srv/www/myapp;
    index index.html;
  }
}

Le filtre peut avoir les paramètres suivants :

• block_semicolon=false

  Permet d'ajouter un point-virgule à la fin de chaque bloc.

• indent=" "

  Définit l'unité d'indentation.

• level=0

  Indique le niveau initial de l'indentation. Une valeur 0 commence à indentuer depuis le début de la ligne. Si la valeur est supérieure à 0, le contenu est indenté par indent * level.

• semicolon=';'

  Caractère de point-virgule. Définissez ceci sur une chaîne vide pour ignorer tous les points-virgules.

• semicolon_ignore_postfix='!;'

  Si la ligne se termine par !;, alors n'ajoutez pas le point-virgule final.

.. _encode-pam:

encode_pam ^^^^^^^^^^

Ce filtre aide à créer une configuration au format utilisée par les Modules d'Authentification Pluggables de Linux (PAM). La structure de données attendue est la suivante :

.. code:: yaml

my_system_auth_config:
  aa:
    type: auth
    control: required
    path: pam_unix.so
    args:
      - try_first_pass
      - nullok
  bb:
    type: auth
    control: optional
    path: pam_permit.so
  cc:
    type: auth
    control: required
    path: pam_env.so
  dd:
    type: account
    control: required
    path: pam_unix.so
  ee:
    type: account
    control: optional
    path: pam_permit.so
  ff:
    type: account
    control: required
    path: pam_time.so
  gg:
    type: password
    control: required
    path: pam_unix.so
    args:
      - try_first_pass
      - nullok
      - sha512
      - shadow
  hh:
    type: password
    control: optional
    path: pam_permit.so
    args:
  ii:
    type: session
    control: required
    path: pam_limits.so
  jj:
    type: session
    control: required
    path: pam_unix.so
  kk:
    type: session
    control: optional
    path: pam_permit.so

La variable est un dictionnaire dont la clé est un label et la valeur est la règle PAM. Le label est utilisé pour ordonner les règles PAM. L'utilisation de labels avec un nombre pair de caractères permet d'insérer une autre règle entre deux règles.

La variable ci-dessus peut être utilisée dans le fichier modèle comme suit :

.. code:: jinja2

{{ my_system_auth_config | encode_pam }}

La sortie d'un tel modèle serait :

.. code:: pam

auth  required  pam_unix.so  try_first_pass nullok
auth  optional  pam_permit.so
auth  required  pam_env.so

account  required  pam_unix.so
account  optional  pam_permit.so
account  required  pam_time.so

password  required  pam_unix.so  try_first_pass nullok sha512 shadow
password  optional  pam_permit.so

session  required  pam_limits.so
session  required  pam_unix.so
session  optional  pam_permit.so

Le filtre peut avoir les paramètres suivants :

• print_label=false

  Imprimer les labels comme commentaire dans la sortie.

• separate_types=true

  Ajoutez une nouvelle ligne entre les groupes de types.

• separator=" "

  Séparateur entre la collection de tokens.

.. _encode-toml:

encode_toml ^^^^^^^^^^^

Ce filtre aide à créer une configuration au format TOML. La structure de données attendue est la suivante :

.. code:: yaml

my_grafana_ldap_config:
  verbose_logging: false
  servers:
    - host: 127.0.0.1
      port: 389
      use_ssl: no
      start_tls: no
      ssl_skip_verify: no
      bind_dn: cn=admin,dc=grafana,dc=org
      bind_password: grafana
      search_filter: (cn=%s)
      search_base_dns:
        - dc=grafana,dc=org
    - attributes:
        name: givenName
        surname: sn
        username: cn
        member_of: memberOf
        email: email
    - group_mappings:
        - group_dn: cn=admins,dc=grafana,dc=org
          org_role: Admin
        - group_dn: cn=users,dc=grafana,dc=org
          org_role: Editor
        - group_dn: "*"
          org_role: Viewer

La variable est un dictionnaire dont la valeur peut être soit d'un type simple (nombre, chaîne, booléen), soit une liste ou un autre dictionnaire. Les dictionnaires et les listes peuvent être imbriqués.

La variable ci-dessus peut être utilisée dans le fichier modèle comme suit :

.. code:: jinja2

{{ my_grafana_ldap_config | encode_toml }}

La sortie d'un tel modèle serait :

.. code:: toml

verbose_logging = false

[[servers]]
host = "127.0.0.1"
port = 389
use_ssl = false
start_tls = false
ssl_skip_verify = false
bind_dn = "cn=admin,dc=grafana,dc=org"
bind_password = 'grafana'
search_filter = "(cn=%s)"
search_base_dns = ["dc=grafana,dc=org"]

[servers.attributes]
name = "givenName"
surname = "sn"
username = "cn"
member_of = "memberOf"
email =  "email"

[[servers.group_mappings]]
group_dn = "cn=admins,dc=grafana,dc=org"
org_role = "Admin"

[[servers.group_mappings]]
group_dn = "cn=users,dc=grafana,dc=org"
org_role = "Editor"

[[servers.group_mappings]]
group_dn = "*"
org_role = "Viewer"

Le filtre peut avoir les paramètres suivants :

• convert_bools=false

  Indique si les valeurs booléennes présentées sous forme de chaîne doivent être converties en une véritable valeur booléenne. Par exemple, var1: 'True' serait représenté sous forme de chaîne mais en utilisant convert_bools=true, il sera converti en booléen comme s'il était défini comme var1: true.

• convert_nums=false

  Indique si les nombres présentés sous forme de chaîne doivent être convertis en nombres. Par exemple, var1: '123' serait représenté sous forme de chaîne mais en utilisant convert_nums=true, il sera converti en nombre comme s'il était défini comme var1: 123. Il est également possible d'utiliser le typage YAML pour convertir une chaîne en nombre (par exemple, !!int "1234", !!float "3.14").

• quote='"'

  Définit le formatage de la valeur. Utilisez quote="'" ou quote='"'.

.. _encode-xml:

encode_xml ^^^^^^^^^^

Ce filtre aide à créer une configuration au format XML. La structure de données attendue est la suivante :

.. code:: yaml

my_oddjob_config:
  - oddjobconfig:
    - service:
      - ^name: com.redhat.oddjob
      - object:
        - ^name: /com/redhat/oddjob
        - interface:
          - ^name: com.redhat.oddjob
          - method:
            - ^name: listall
            - allow:
              - ^min_uid: 0
              - ^max_uid: 0
          - method:
            - ^name: list
            - allow: ''
          - method:
            - ^name: quit
            - allow:
              - ^user: root
          - method:
            - ^name: reload
            - allow:
              - ^user: root
    - include:
      - ^ignore_missing: "yes"
      - /etc/oddjobd.conf.d/*.conf
    - include:
      - ^ignore_missing: "yes"
      - /etc/oddjobd-local.conf

La variable peut être une liste de dictionnaires, de listes ou de chaînes. Cet encodeur de configuration ne gère pas très bien le contenu mixte, donc la façon la plus sûre d'inclure du contenu mixte est de le définir comme une chaîne et d'utiliser le paramètre escape_xml=false. Cet encodeur de configuration ne produit également aucune déclaration XML. Toute déclaration XML ou DOCTYPE doit faire partie du fichier modèle.

La variable ci-dessus peut être utilisée dans le fichier modèle comme suit :

.. code:: jinja2

{{ my_oddjob_config | encode_xml }}

La sortie d'un tel modèle serait :

.. code:: xml

<oddjobconfig>
  <service name="com.redhat.oddjob">
    <object name="/com/redhat/oddjob">
      <interface name="com.redhat.oddjob">
        <method name="listall">
          <allow min_uid="0" max_uid="0" />
        </method>
        <method name="list">
          <allow />
        </method>
        <method name="quit">
          <allow user="root" />
        </method>
        <method name="reload">
          <allow user="root" />
        </method>
      </interface>
    </object>
  </service>
  <include ignore_missing="yes">/etc/oddjobd.conf.d/*.conf</include>
  <include ignore_missing="yes">/etc/oddjobd-local.conf</include>
</oddjobconfig>

Le filtre peut avoir les paramètres suivants :

• attribute_sign="^"

  Indicateur d'attribut XML.

• indent=" "

  Définit l'unité d'indentation.

• level=0

  Indique le niveau initial de l'indentation. Une valeur 0 commence à indentuer depuis le début de la ligne. Si la valeur est supérieure à 0, le contenu est indenté par indent * level.

.. _encode-yaml:

encode_yaml ^^^^^^^^^^^

Ce filtre aide à créer une configuration au format YAML. La structure de données attendue est la suivante :

.. code:: yaml

my_mongodb_config:
  systemLog:
    destination: file
    logAppend: true
    path: /var/log/mongodb/mongod.log
  storage:
    dbPath: /var/lib/mongo
    journal:
      enabled: true
  processManagement:
    fork: true
    pidFilePath: /var/run/mongodb/mongod.pid
  net:
    port: 27017
    bindIp: 127.0.0.1

La variable est un YAML ordinaire. Le seul but de cet encodeur de filtre est de pouvoir convertir une structure de données YAML en chaîne dans un fichier modèle de manière unifiée, compatible avec les autres encodeurs de configuration.

La variable ci-dessus peut être utilisée dans le fichier modèle comme suit :

.. code:: jinja2

{{ my_mongodb_config | encode_yaml }}

La sortie d'un tel modèle serait :

.. code:: yaml

net:
  bindIp: "127.0.0.1"
  port: 27017
processManagement:
  fork: true
  pidFilePath: "/var/run/mongodb/mongod.pid"
storage:
  dbPath: "/var/lib/mongo"
  journal:
    enabled: true
systemLog:
  destination: "file"
  logAppend: true
  path: "/var/log/mongodb/mongod.log"

Le filtre peut avoir les paramètres suivants :

• block_prefix=';;;'

  Permet de maintenir les signes de bloc dans la sortie.

  .. code:: yaml

  aaa: |-
    ;;;|-
    bbb = ccc
    ddd = eee
  

• convert_bools=false

  Indique si les valeurs booléennes présentées sous forme de chaîne doivent être converties en une véritable valeur booléenne. Par exemple, var1: 'True' serait représenté sous forme de chaîne mais en utilisant convert_bools=true, il sera converti en booléen comme s'il était défini comme var1: true.

• convert_nums=false

  Indique si les nombres présentés sous forme de chaîne doivent être convertis en nombres. Par exemple, var1: '123' serait représenté sous forme de chaîne mais en utilisant convert_nums=true, il sera converti en nombre comme s'il était défini comme var1: 123. Il est également possible d'utiliser le typage YAML pour convertir une chaîne en nombre (par exemple, !!int "1234", !!float "3.14").

• indent=" "

  Définit l'unité d'indentation.

• level=0

  Indique le niveau initial de l'indentation. Une valeur 0 commence à indentuer depuis le début de la ligne. Si la valeur est supérieure à 0, le contenu est indenté par indent * level.

• quote='"'

  Définit le formatage de la valeur. Utilisez quote="'" ou quote='"'.

.. _Utilities:

Utilitaires

Voici une liste des utilitaires qui peuvent être utilisés en conjonction avec les filtres de l'encodeur de configuration.

.. _template-replace:

template_replace ^^^^^^^^^^^^^^^^

Ce filtre permet d'utiliser une couche de modélisation supplémentaire qui est traitée pendant le traitement du fichier modèle. Cela peut être utile s'il est nécessaire de créer des définitions répétitives mais légèrement différentes dans le fichier modèle.

La couche de modélisation supplémentaire est représentée par une variable de modélisation qui contient des variables spécialement décorées qui seront remplacées par leur valeur réelle au moment du traitement du fichier modèle. La variable de modèle peut être composée dynamiquement, ce qui offre une flexibilité supplémentaire qui devrait sinon être codée en dur dans le fichier modèle.

Regardons un exemple d'utilisation :

.. code:: yaml

# La variable utilisée comme remplacement dans la variable de modèle
my_clients:
  - host: myclient01
    jobdefs: Default
    password: Passw0rd1
    file_retention: 30 jours
  - host: myclient02
    jobdefs: HomeOnly
    password: Passw0rd2
    file_retention: 90 jours

# La variable de modèle utilisée dans le fichier modèle
bacula_director_config_job_client:
  # Première variable modèle contenant les variables spécialement décorées
  - template:
      - Job:
        - Name = Job-{[{ item['jobdefs'] }]}-{[{ item['host'] }]}
        - Client = {[{ item['host'] }]}-fd
        - JobDefs = {[{ item['jobdefs'] }]}
    # Variable utilisée pour remplacer les variables spécialement décorées
    items: "{{ my_clients }}"
  # Deuxième modèle et ses éléments
  - template:
      - Client:
        - Name = {[{ item['host'] }]}-fd
        - Address = {[{ item['host'] }]}
        - FD Port = 9102
        - Catalog = Default
        - Password = {[{ item['password'] }]}
        - File Retention = {[{ item['file_retention'] }]}
        - Job Retention = 3 mois
        - AutoPrune = oui
    items: "{{ my_clients }}"

La variable ci-dessus peut être utilisée avec le filtre template_replace dans le fichier modèle (bacula-dir.conf.j2) comme suit :

.. code:: jinja2

{% for record in bacula_director_config_job_client %}
  {%- for item in record['items'] -%}
    {{ record['template'] | template_replace(item) | encode_nginx }}{{ "\n" }}
  {%- endfor -%}
{% endfor %}

Le fichier modèle peut être appelé depuis le playbook/rôle comme ceci :

.. code:: yaml

- name: Configurer Bacula Director
  template:
    src: bacula-dir.conf.j2
    dest: /etc/bacula/bacula-dir.conf

Et le résultat d'une telle utilisation est le suivant :

.. code:: nginx

Job {
  Name = Job-Default-myclient01;
  Client = myclient01-fd;
  JobDefs = Default;
}

Job {
  Name = Job-HomeOnly-myclient02;
  Client = myclient02-fd;
  JobDefs = HomeOnly;
}

Client {
  Name = myclient01-fd;
  Address = myclient01;
  FD Port = 9102;
  Catalog = Default;
  Password = Passw0rd1;
  File Retention = 30 jours;
  Job Retention = 3 mois;
  AutoPrune = oui;
}

Client {
  Name = myclient02-fd;
  Address = myclient02;
  FD Port = 9102;
  Catalog = Default;
  Password = Passw0rd2;
  File Retention = 90 jours;
  Job Retention = 3 mois;
  AutoPrune = oui;
}

.. _Testing:

Tests

Tous les encodeurs ont un ensemble de tests unitaires automatisés via tox <http://tox.readthedocs.io>_. Le test complet peut être exécuté comme suit :

.. code:: shell

$ tox

Un encodeur individuel peut être testé comme suit :

.. code:: shell

$ tox -- python -m unittest tests.test_config_encoders.TestYaml

Des tests individuels peuvent être exécutés comme ceci :

.. code:: shell

$ tox -- python -m unittest tests.test_config_encoders.TestYaml.test_string

Les tests sont une excellente source d'exemples avancés sur la manière d'utiliser chacun des encodeurs. Explorez-les dans le répertoire tests/files. Le contenu des fichiers .in doit être attribué à une variable lors de son utilisation dans Ansible. La sortie dans les fichiers .out peut dépendre des paramètres supplémentaires utilisés dans le fichier tests/test_config_encoders.py. Les tests via Ansible peuvent être exécutés comme suit :

.. code:: shell

$ ansible-playbook -i localhost, tests/test_config_encoders.yaml

.. _License:

Licence

GPLv3

.. _Author:

Auteur

Jiri Tyr