javigs82.clickhouse

Ansible Clickhouse

Este rol se encarga de configurar e instalar un clúster de Clickhouse con N fragmentos y M réplicas. apt y yum han sido probados con Molecule sobre Vagrant.

El clúster se construye basado en grupos de inventario de Ansible, también conocidos como patrones de inventario. Por lo tanto, los siguientes grupos son obligatorios para ejecutar el clúster:

  • clickhouse: contiene todos los hosts de inventario de Clickhouse. Estos hosts deben establecer su nombre de host como: ch01-shard01-replica01 con una expresión regular como: ^ch\\d{2}-shard\\d{2}-replica\\d{2}
  • zookeeper: contiene todos los hosts de inventario de Zookeeper.

Consulta defaults para ver cómo se calculan los fragmentos y réplicas en función de los nombres de los hosts:

Nota que {{ inventory_hostname }} es la dirección DNS o IP, mientras que {{ ansible_hostname }} es el nombre del host de la máquina.

Para verificar si el nombre del host ({{ ansible_hostname}}) está correctamente configurado, revisa en la máquina host con el siguiente comando:

hostname

Requisitos

Para instalar molecule, utiliza python3.

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

Esta solución se basa en la capacidad de resolver nombres de host en un servidor DNS privado. Por lo tanto, suponiendo que Vagrant no proporciona ninguna solución de DNS, el siguiente software se instala en prepare.yml, proporcionando infraestructura de Vagrant con un resolvedor DNS interno.

---
- name: Preparar
  hosts: all
  tasks:
    - name: Instalar epel-release
      yum:
        name: epel-release
        state: present
  
    - name: Instalar nss-mdns
      yum:
        name: nss-mdns
        state: present

    - name: Detener el servicio cron en debian, si está en ejecución
      systemd:
        name: avahi-daemon
        state: started

Con nss-mdns y avahi, Vagrant puede resolver DNS como .local.

Nota que la resolución de DNS debería ser más sofisticada en un caso de uso del mundo real.

Para configurar correctamente el nombre de host, revisa el siguiente enlace:

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

Arquitectura

Clickhouse-cluster está construida sobre el nombre del host, así que asegúrate de que el nombre del host esté correctamente configurado como

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

donde chX-shardY-replicaZ es la clave que proporciona una manera de descubrir fácilmente qué réplica pertenece a qué fragmento, basado en una expresión regular.

Nota que ansible_hostname no es lo mismo que inventory_hostname:

  • ansible_hostname: Es el nombre en el sistema operativo: haz hostname en la máquina host.
  • inventory_hostname: Es la URL (IP o DNS) del host y debe ser resuelta por otras réplicas del clúster. La dirección IP o el nombre DNS son ambos válidos.

{{ ansible_hostname }} se utilizará para descubrir réplicas, mientras que {{ inventory_hostname}} se utilizará para habilitar las comunicaciones.

Un ejemplo de inventario podría ser:

[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>

donde URL (inventory_hostname) puede ser la IP o el DNS que será resuelto en tiempo de ejecución.

Nota que para construir el clúster, son obligatorios los grupos clickhouse y zookeeper.

Diseño

  • Descarga: Desde el repositorio RPM de Yandex. Se permite la degradación mediante la propiedad clickhouse_allow_downgrade.
  • Configuración: Asegúrate de que el grupo y el usuario de clickhouse existan. Asegúrate de las rutas y archivos de configuración. Descubre réplicas y fragmentos basados en la expresión regular.
  • Instalación: Descarga e instala mediante yum.
  • Usuarios: Lista dinámica para gestionar usuarios. La gestión de contraseñas no está implementada.
  • RBAC: POR IMPLEMENTAR.

Variables por Defecto del Rol

Consulta las variables en defaults.

Definición del Clúster

Utiliza estas variables para establecer la definición principal. Nota que la configuración del clúster depende del nombre del host y, con esto, clickhouse_replica_name y clickhouse_shard_name son relevantes, mientras que clickhouse_hostname_regex es la expresión regular para la definición del nombre del host: ^ch\\d{2}-(shard\\d{2})-replica\\d{2} Consulta vars para más información.

# definición del clúster clickhouse
clickhouse_version: "20.8.7.15"
clickhouse_allow_downgrade: false
clickhouse_cluster_name: "mycluster"

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

# usuario/grupo
clickhouse_group: "clickhouse"
clickhouse_user: "clickhouse"

Soporte para Instalación de Clickhouse

# soporte 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 }}"

# soporte 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 }}"

# rutas
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"

Configuración de Clickhouse

Con estas variables, se configura la configuración principal.

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: []

Redes

Estas variables están relacionadas con la configuración de red.

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

# ver vars para clickhouse_listen_host_default
clickhouse_listen_host: "{{ clickhouse_listen_host_default + clickhouse_listen_host_custom }}"

Nota que clickhouse_listen_host debe permitir que los miembros de ch escuchen.

Usuarios

Utiliza estas variables para personalizar usuarios. Para eliminar un usuario, utiliza los atributos de configuración de Clickhouse: https://clickhouse.tech/docs/en/operations/configuration-files/

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

Zookeeper

La lista de hosts de Zookeeper se basa en los patrones de grupos de inventario.

# zookeeper no es en absoluto obligatorio. Si zookeeper no está instalado, 
# la replicación debe ser realizada por el lado del cliente.
clickhouse_zookeeper_list: "{{ groups['zookeeper'] }}"
clickhouse_zookeeper_port: "2181"

Variables del Rol Vars

Son variables que tienen mayor precedencia que las variables por defecto y las de grupos de inventario. Solo pueden ser anuladas por una precedencia superior, pero normalmente no lo son.

Nota que la configuración del clúster depende del nombre del host y, con esto, clickhouse_replica_name y clickhouse_shard_name son relevantes, mientras que clickhouse_hostname_regex es la expresión regular para la definición del nombre del host: ^ch\\d{2}-(shard\\d{2})-replica\\d{2} Consulta vars para más información.

Consulta las variables en vars.

---
# regex para descubrir fragmentos y réplicas.
clickhouse_hostname_regex: "^ch\\d{2}-(shard\\d{2})-(replica\\d{2})"
# descubrir basado en la 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 lista de fragmentos se calcula a partir de la lista de réplicas. Deben alinearse con regex: ver clickhouse_hostname_regex en 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 lista de réplicas son todos los hosts de un grupo.
clickhouse_replica_list: "{{ groups['clickhouse'] }}"

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

Nunca deben ser anuladas, ya que son el núcleo de cómo el rol descubre y relaciona réplicas con fragmentos.

Etiquetas del Rol

Las siguientes etiquetas son compatibles en este rol:

  • ch:configure: Para ejecutar solo tareas de configuración.
  • ch:install: Para descargar e instalar el software.
  • ch:service: Para gestionar el estado del servicio systemctl.

Dependencias

Clickhouse depende de Zookeeper para lograr consistencia.

Ejemplo de Playbook

Incluyendo un ejemplo de cómo utilizar el rol.

    - 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'] }}"

Referencias

Autor

Agradecimientos

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

Acerca del proyecto

Clickhouse Cluster

Instalar
ansible-galaxy install javigs82.clickhouse
Licencia
mit
Descargas
169
Propietario