README.md

Clickhouse Ansible role

This ansible role installs Clickhouse in a Debian environment. It has been tested for Debian bullseye.

This role has been generated using the cookiecutter tool, you can generate a similar role that fits your needs using the this cookiecutter template.

• Getting Started
  • Prerequisites
  • Installing
• Usage
• Testing
• Built With
• Versioning
• Authors
• License
• Contributing

Getting Started 🏁

These instructions will get you a copy of the role for your Ansible playbook. Once launched, it will install Clickhouse in a Debian system.

Prerequisites ☑️

Ansible 5.x.x version installed.

Molecule 3.x.x version installed.

For testing purposes, Molecule with Docker as driver and Goss as verifier.

Installing 📥

Create or add to your roles dependency file (e.g requirements.yml):

- src: idealista.clickhouse_role
  scm: git
  version: 3.2.0
  name: clickhouse_role

Install the role with ansible-galaxy command:

ansible-galaxy install -p roles -r requirements.yml -f

Use in a playbook:

---
- hosts: someserver
  roles:
    - role: clickhouse_role

Usage 🏃

Look to the defaults properties file to see the possible configuration properties, it is very likely that you will not need to override any variables but don't forget to set your Admin user 🦸

• main.yml for superset general purpose vars.

👉 Don't forget

• 🦸 To set your Admin user and use a secure 🔑 password.
• 📝 To set the clickhouse_custom_config_file_path and / or clickhouse_custom_users_file_path if you are going to use custom config files.
  • 👉 See the ClickHouse doc.
• ☑️ To enable or disable using clickhouse_role_manage_X vars what things the role should manage.
• 📝 To set users, quotas, profiles, grants, databases to create.
  • ℹ️ Or to unset if you want to DROP things.
  • 👉 See the default molecule scenario group_vars for more

❗ You must know

• ❗ To make us of the 'EXCEPT' clauses for quota assignation or user grantees for example, you can add a minus or dash ( - ) before the name.
• ❗ When setting password_type for users, it should be one of this
• ❗ When setting keyed for quota, it should be one of this
• ❗ In case you're using LDAP or Kerberos, set each with their own property ldap_server or 'kerberos' so password_type is not required
• ⚠️ clickhouse_replicated_tables_macros is deprecated, please use clickhouse_macros var

Users and roles

• ⚠️ Note that are two ways to set users for ClickHouse, users.xml or via SQL-query, to distinguish both methods note that in this role we use clickhouse_custom_users_xml and clickhouse_custom_users respectively (SQL recommended).
• ⚠️ When granting, you must know:
  • When performing the GRANT actions to maintain the perms & privs clean a "general" REVOKE is performed before GRANTing
  • There is an option to disable that before "GRANTS" clean up: clickhouse_custom_grants_previous_cleanup
  • When granting permissions and privileges the order of the items in definition list takes precedence, is recommended to do this grant from less to the most restrictive.
    • 👉 See example below, more at the default molecule scenario group_vars for more.
  • Statements Aliases are valid, but not handled at "ansible level" so this results in task making comparisions like privileges: [DELETE] vs system.grants access_type = ALTER DELETE (from ClickHouse), so we recommend set "un-aliased" perms and privs.
  • When performing REVOKE or GRANT if a problem occurs may be result in unexpected / removed perms & privs in the ClickHouse DB ¡¡Be extra careful!!
  • You can GRANT a role to a role, or roles to users with clickhouse_custom_grant_roles.

Custom user definition example:

clickhouse_custom_users:
  - user:
    name: "Takumi"
    password_type: plaintext_password
    password: "AE86"
    networks:
      - "IP '::/0'"
    settings:
      - "max_memory_usage = 10000000000"
    role:
      - projectd_members
      - tofu_shop
    profile:
      - default
    grantees:
      - projectd_members
    quota: "default"
    databases: [ProjectD]
    # ldap_server: project.d
    # kerberos: ""

clickhouse_custom_grants:
- on:
  databases: [Akina]
  tables: ["*"]
  privileges: [SELECT]
  to: [initial_d]
- on:
  # cluster:
  databases: ["Akina"]
  tables: [calendar, records]
  # columns: [Notes]
  privileges: [ALL]
  to: [Takumi, Iketani]
  with_grant_option: True
- on:
  # cluster:
  databases: ["Akina"]
  tables: [records]
  privileges: [SELECT, UPDATE]
  to: [Iketani]
  with_grant_option: False

clickhouse_custom_grant_roles:
  - roles: [initial_d]
    to: [Takumi, Iketani]
    # cluster:

Testing 🧪

Install dependencies

pipenv install -r test-requirements.txt

For more information read the pipenv docs.

Testing

$ pipenv run molecule test

Built With 🏗️

Versioning 🗃️

For the versions available, see the tags on this repository.

Additionaly you can see what change in each version in the CHANGELOG.md file.

Authors 🦸

• Idealista - Work with - idealista

See also the list of contributors who participated in this project.

License 🗒️

This project is licensed under the Apache 2.0 license - see the LICENSE file for details.

Contributing 👷

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.