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
- Vagrant con VirtualBox (ver https://www.vagrantup.com/intro)
- ansible => 2.10
- python3
- pip3
- Molecule (ver https://molecule.readthedocs.io/en/latest/installation.html)
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
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 serviciosystemctl
.
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
- https://clickhouse.tech/docs/en/getting-started
- https://docs.ansible.com/ansible/latest/user_guide/intro_patterns.html
Autor
- javigs82 github
Agradecimientos
- https://github.com/AlexeySetevoi/ansible-clickhouse
- https://github.com/nl2go/ansible-role-clickhouse
- https://github.com/idealista/clickhouse_role
Licencia
Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.
ansible-galaxy install javigs82.clickhouse