javigs82.clickhouse

Ansible Clickhouse

Ce rôle est chargé de configurer et d'installer un cluster Clickhouse avec N shards et M répliques. apt et yum ont été testés avec Molecule sur Vagrant.

Le cluster est construit sur la base des groupes d'inventaire Ansible, appelés modèles d'inventaire, donc les groupes suivants sont obligatoires pour faire fonctionner le cluster :

clickhouse : contient tous les hôtes d'inventaire Clickhouse. Ces hôtes doivent définir leur nom d'hôte comme : ch01-shard01-replica01 avec une regex comme : ^ch\\d{2}-shard\\d{2}-replica\\d{2}
zookeeper : contient tous les hôtes d'inventaire Zookeeper.

Consultez defaults pour voir comment les shards et les répliques sont calculés en fonction des noms d'hôtes :

Remarque que {{ inventory_hostname }} est l'adresse DNS ou IP tandis que {{ ansible_hostname }} est le nom d'hôte de la machine.

Pour vérifier si le nom d'hôte ({{ ansible_hostname}}) est correctement défini, vérifiez sur la machine hôte avec la commande suivante :

hostname

Exigences

Vagrant avec VirtualBox (voir https://www.vagrantup.com/intro)
ansible => 2.10
python3
pip3
Molecule (voir https://molecule.readthedocs.io/en/latest/installation.html)

Pour installer molecule, utilisez python3.

python3 -m pip install --user "molecule"
python3 -m pip install --user "molecule-vagrant"

Cette solution repose sur la capacité de résoudre le nom d'hôte dans un serveur DNS privé. Donc, en supposant que Vagrant ne fournit aucune solution DNS, le logiciel suivant est installé dans prepare.yml, fournissant une infrastructure Vagrant avec un résolveur DNS interne.

---
- name: Prepare
  hosts: all
  tasks:
    - name: Installer epel-release
      yum:
        name: epel-release
        state: present
  
    - name: Installer nss-mdns
      yum:
        name: nss-mdns
        state: present

    - name: Arrêter le service cron sur debian, s'il est en cours d'exécution
      systemd:
        name: avahi-daemon
        state: started

Avec nss-mdns et avahi, Vagrant est capable de résoudre DNS comme .local.

Remarque que la résolution DNS supposée est plus sophistiquée dans un cas d'utilisation réel.

Pour configurer correctement le nom d'hôte, consultez le lien suivant :

https://www.vagrantup.com/docs/networking/basic_usage#setting-hostname

Architecture

Clickhouse-cluster est construit sur la base du nom d'hôte, donc assurez-vous que le nom d'hôte est correctement défini comme suit :

^ch\\d{2}-shard\\d{2}-replica\\d{2}

où chX-shardY-replicaZ est la clé permettant de découvrir facilement quelle réplique appartient à quel shard en fonction de la regex.

Remarque que ansible_hostname n'est pas le même que inventory_hostname :

ansible_hostname : C'est le nom dans le système d'exploitation : faites hostname dans la machine hôte
inventory_hostname : C'est l'URL (IP ou DNS) de l'hôte et doit être résolu par d'autres répliques du cluster. L'adresse IP ou le DNS sont tous deux valides.

{{ ansible_hostname }} sera utilisé pour découvrir les répliques tandis que {{ inventory_hostname}} pour activer les communications.

Un exemple d'inventaire pourrait être :

[clickhouse]
<URL-ch01-shard01-replica01> ansible_host=<ip>
<URL-ch01-shard01-replica02> ansible_host=<ip>
...
<URL-ch01-shard02-replica01> ansible_host=<ip>
<URL-ch01-shard02-replica02> ansible_host=<ip>
...
<URL-chX-shardY-replicaZ> ansible_host=<ip>

[zookeeper]
<URL-zookeeper01> ansible_host=<ip>
...
<URL-zookeeperN> ansible_host=<ip>

où URL (inventory_hostname) peut être l'IP ou le DNS qui sera résolu à l'exécution.

Remarque que pour construire le cluster, le groupe clickhouse et le groupe zookeeper sont obligatoires.

Design

Téléchargement : Depuis le dépôt rpm de yandex. Le retour en arrière est autorisé grâce à la propriété clickhouse_allow_downgrade.
Configuration : Assurez-vous du groupe et de l'utilisateur clickhouse. Assurez les chemins et les fichiers de configuration. Découvrez les répliques et les shards basés sur la regex.
Installation : Téléchargez et installez par yum
Utilisateurs : Liste dynamique pour gérer les utilisateurs. La gestion des mots de passe n'est pas implémentée.
RBAC : À IMPLEMENTER.

Variables par défaut du rôle

Consultez les variables dans defaults.

Définition du cluster

Utilisez ces variables pour établir la définition principale. Remarque que la configuration du cluster repose sur le nom d'hôte et avec cela, clickhouse_replica_name et clickhouse_shard_name prennent de l'importance, tandis que clickhouse_hostname_regex est la regex de la définition du nom d'hôte : ^ch\\d{2}-(shard\\d{2})-replica\\d{2}. Voir vars pour plus d'informations.

# définition du cluster clickhouse
clickhouse_version: "20.8.7.15"
clickhouse_allow_downgrade: false
clickhouse_cluster_name: "mycluster"

clickhouse_service_name: "clickhouse-server"
clickhouse_service_status: "started"

# utilisateur/groupe
clickhouse_group: "clickhouse"
clickhouse_user: "clickhouse"

Support d'installation Clickhouse

# support yum 
clickhouse_yum_repo: "https://repo.clickhouse.tech/rpm/stable/x86_64/"
clickhouse_yum_repo_key: "https://repo.clickhouse.tech//CLICKHOUSE-KEY.GPG"
clickhouse_yum_package:
  - "clickhouse-client-{{ clickhouse_version }}"
  - "clickhouse-common-static-{{ clickhouse_version }}"
  - "clickhouse-server-{{ clickhouse_version }}"

# support apt
clickhouse_apt_repo: "deb https://repo.clickhouse.tech/deb/stable/ main/"
clickhouse_apt_repo_keyserver: "keyserver.ubuntu.com"
clickhouse_apt_repo_key: "E0C56BD4"
clickhouse_apt_package:
  - "clickhouse-client={{ clickhouse_version }}"
  - "clickhouse-common-static={{ clickhouse_version }}"
  - "clickhouse-server={{ clickhouse_version }}"

# chemin
clickhouse_path_config: "/etc/clickhouse-server"
clickhouse_path_config_d: "{{ clickhouse_path_config }}/config.d"
clickhouse_path_log: "/var/log/clickhouse-server"
clickhouse_path_data: "/var/lib/clickhouse"

Configuration Clickhouse

Avec ces variables, la configuration principale est mise en place.

clickhouse_config:
  max_connections: 2048
  keep_alive_timeout: 3
  max_concurrent_queries: 100
  uncompressed_cache_size: 8589934592
  mark_cache_size: 5368709120
  builtin_dictionaries_reload_interval: 3600
  max_session_timeout: 3600
  default_session_timeout: 60
  mlock_status: false
  merge_tree_config: []

Réseautage

Ces variables sont liées à la configuration réseau.

clickhouse_http_port: 8123
clickhouse_https_port: 8443
clickhouse_tcp_port: 9000
clickhouse_tcp_secure_port: 9440
clickhouse_interserver_http: 9009

# voir vars pour clickhouse_listen_host_default
clickhouse_listen_host: "{{ clickhouse_listen_host_default + clickhouse_listen_host_custom }}"

Remarque que clickhouse_listen_host doit permettre aux membres ch d'écouter.

Utilisateurs

Utilisez ces variables pour personnaliser les utilisateurs. Pour supprimer un utilisateur, utilisez les attributs de configuration Clickhouse : https://clickhouse.tech/docs/en/operations/configuration-files/

# utilisateurs ch : https://clickhouse.tech/docs/en/operations/configuration-files/
clickhouse_users_list:
  - { user_name: "default",
      profile: "default",
      networks: ["::/1"],
      quota: "default" }

Zookeeper

La liste des hôtes Zookeeper est basée sur le modèle des groupes d'inventaire.

# zookeeper n'est pas du tout obligatoire. Si zookeeper n'est pas installé, 
# la réplication doit être réalisée du côté client.
clickhouse_zookeeper_list: "{{ groups['zookeeper'] }}"
clickhouse_zookeeper_port: "2181"

Variables par défaut du rôle

Ce sont des variables qui ont une priorité plus élevée que les valeurs par défaut et celles des groupes d'inventaire. Elles ne peuvent être remplacées que par une priorité encore plus élevée, mais en général, elles ne le sont pas.

Remarque que la configuration du cluster repose sur le nom d'hôte et avec cela, clickhouse_replica_name et clickhouse_shard_name prennent de l'importance, tandis que clickhouse_hostname_regex est la regex de la définition du nom d'hôte : ^ch\\d{2}-(shard\\d{2})-replica\\d{2}. Voir vars pour plus d'informations.

Consultez les variables dans vars.

---
# regex pour découvrir les shards et les répliques
clickhouse_hostname_regex: "^ch\\d{2}-(shard\\d{2})-(replica\\d{2})"
# découvrir basé sur regex
clickhouse_shard_name: "{{ ansible_hostname | regex_search(clickhouse_hostname_regex, '\\1') | first }}"
clickhouse_replica_name: "{{ ansible_hostname | regex_search(clickhouse_hostname_regex, '\\2') | first }}"

# la liste des shards est calculée par la liste des répliques. Elles doivent respecter la regex : voir clickhouse_hostname_regex dans vars/main.yml
clickhouse_shard_list: "{{ clickhouse_replica_list | map('extract', hostvars, 'ansible_hostname') | map('regex_search', clickhouse_hostname_regex, '\\1') | unique | map ('first') }}"
# la liste des répliques est tous les hôtes d'un groupe
clickhouse_replica_list: "{{ groups['clickhouse'] }}"

clickhouse_listen_host_default:
  - "{{ inventory_hostname }}"
  - "127.0.0.1"
  - "::1"

Elles ne doivent JAMAIS être remplacées car elles sont la clé de la manière dont le rôle découvre et relie les répliques avec les shards.

Tags du rôle

Les tags suivants sont pris en charge dans ce rôle :

ch:configure : Pour exécuter uniquement des tâches de configuration.
ch:install : Pour télécharger et installer le logiciel.
ch:service : Pour gérer l'état du service systemctl.

Dépendances

Clickhouse dépend de Zookeeper pour assurer la cohérence.

Exemple de Playbook

Voici un exemple d'utilisation du rôle.

    - hosts: my_clickhouse_group
      tasks:
        - include_role:
            name: javigs82.clickhouse
          vars:
            clickhouse_cluster_name: "e-commerce"
            clickhouse_replica_list: "{{ groups['my_clickhouse_group'] }}"
            clickhouse_zookeeper_list: "{{ groups['my_zookeeper_group'] }}"