community.clickhouse.clickhouse_user module – Creates or removes a ClickHouse user using the clickhouse-driver Client interface

Note

This module is part of the community.clickhouse collection (version 2.0.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.clickhouse. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.clickhouse.clickhouse_user.

New in community.clickhouse 0.4.0

Synopsis 

Creates or removes a ClickHouse user using the clickhouse-driver Client interface.
The module can only create and delete users, without any additional parameters. New features will be added in the future.

Requirements 

The below requirements are needed on the host that executes this module.

clickhouse-driver

Parameters 

Parameter	Comments
client_kwargs dictionary	Any additional keyword arguments you want to pass to the Client interface when instantiating its object. Default: `{}`
cluster string	Run the command on all cluster hosts. If the cluster is not configured, the command will crash with an error.
default_roles list / elements=string added in community.clickhouse 0.6.0	Sets specified roles as default for the user. The roles must be explicitly granted to the user whether manually before using this argument or by using the `roles` argument in the same task. To append or remove roles, use the `default_roles_mode` argument. To unset all roles as default, pass an empty list (`[]`) and `default_roles_mode=listed_only`.
default_roles_mode string added in community.clickhouse 0.6.0	When `listed_only` (default), sets only roles specified in `default_roles` as user default roles. It will unset all other roles as default roles. When `append`, appends roles specified in `default_roles` to existing user default roles. default roles instead of unsetting not specified ones. When `remove`, removes roles specified in `default_roles` from user default roles. Ignored without `default_roles` set. Choices: `"append"` `"listed_only"` ← (default) `"remove"`
login_db string	The same as the `Client(database='...')` argument. If not passed, relies on the driver’s default argument value.
login_host string	The same as the `Client(host='...')` argument. Default: `"localhost"`
login_password string	The same as the `Client(password='...')` argument. If not passed, relies on the driver’s default argument value.
login_port integer	The same as the `Client(port='...')` argument. If not passed, relies on the driver’s default argument value.
login_user string	The same as the `Client(user='...')` argument. If not passed, relies on the driver’s default argument value. Be sure your the user has permissions to read the system tables listed in the RETURN section.
name string / required	User name to add or remove.
password string	Set the user’s password. Password can be passed unhashed or hashed.
roles list / elements=string added in community.clickhouse 0.6.0	Grants specified roles to the user. To append or remove roles, use the `roles_mode` argument. To revoke all roles, pass an empty list (`[]`) and `default_roles_mode=listed_only`.
roles_mode string added in community.clickhouse 0.6.0	When `listed_only` (default), makes the user a member of only roles specified in `roles`. It will remove the user from all other roles. When `append`, appends roles specified in `roles` to existing user roles. When `remove`, removes roles specified in `roles` from user roles. The argument is ignored without `roles` set. Choices: `"append"` `"listed_only"` ← (default) `"remove"`
settings list / elements=string added in community.clickhouse 0.5.0	Settings with their constraints applied by default at user login. You can also specify the profile from which the settings will be inherited. When specified for an existing user, settings will only be updated if they differ from current settings. The module fetches current settings from `system.settings_profile_elements` for comparison.
state string	User state. If `present`, will create the user if not exists. If `absent`, will drop the user if exists. Choices: `"present"` ← (default) `"absent"`
type_password string	The type of password being transmitted(plaintext_password, sha256_password, sha256_hash…). For more details, see https://clickhouse.com/docs/en/sql-reference/statements/create/user. Default: `"sha256_password"`
update_password string	If `on_create`, will set the password only for newly created users. If the user already exists, a `password` value will be ignored. If `always`, will always update the password. This option is not idempotent and will update the password even if it is the same in the database. If in future ClickHouse will allow to retrieve password hashes and other necessary details, this behavior will be changed. Choices: `"always"` `"on_create"` ← (default)
user_hosts list / elements=dictionary added in community.clickhouse 1.0.0	Host restrictions to apply to the user. It’s a list of dictionaries, where each dictionary specifies the type of restriction to apply to which hosts or pattern.
hosts list / elements=string	A list of hosts or patterns from which the user will be allowed to connect. This is required if `user_hosts.type` is not `ANY` or `LOCAL`.
type string / required	The method used to validate which hosts that users are allowed to connect from (`ANY`, `LOCAL`, `IP`, `LIKE`, `NAME`, `REGEXP`). When specified for an existing user the previous host type and hosts will be updated. For more details, see https://clickhouse.com/docs/en/sql-reference/statements/create/user.

Attributes 

Attribute	Support	Description
check_mode	Support: full	Supports check_mode.

Notes 

Note

See the clickhouse-driver documentation for more information about the driver interface.

Examples 

- name: Create user granting roles and setting default role
  community.clickhouse.clickhouse_user:
    login_host: localhost
    login_user: alice
    login_db: foo
    login_password: my_password
    name: test_user
    password: qwerty
    type_password: sha256_password
    roles:
    - accountant
    - manager
    default_roles:
    - accountant

- name: Append the sales role to test_user's roles
  community.clickhouse.clickhouse_user:
    login_host: localhost
    login_user: alice
    login_db: foo
    login_password: my_password
    name: test_user
    roles:
    - sales
    roles_mode: append

- name: Unset all test_user's default roles
  community.clickhouse.clickhouse_user:
    login_host: localhost
    login_user: alice
    login_db: foo
    login_password: my_password
    name: test_user
    default_roles: []

- name: Revoke all roles from test_user
  community.clickhouse.clickhouse_user:
    login_host: localhost
    login_user: alice
    login_db: foo
    login_password: my_password
    name: test_user
    roles: []

- name: If user exists, update password
  community.clickhouse.clickhouse_user:
    login_host: localhost
    login_user: alice
    login_db: foo
    login_password: my_password
    name: test_user
    password: qwerty123
    update_password: always

- name: Update user settings (idempotent - only updates if different)
  community.clickhouse.clickhouse_user:
    login_host: localhost
    login_user: alice
    login_db: foo
    login_password: my_password
    name: test_user
    settings:
      - max_memory_usage = 20000 READONLY
      - max_threads = 8

- name: Create user with specific settings
  community.clickhouse.clickhouse_user:
    login_host: localhost
    login_user: alice
    login_db: foo
    login_password: my_password
    name: test_user
    password: 9e69e7e29351ad837503c44a5971edebc9b7e6d8601c89c284b1b59bf37afa80
    type_password: sha256_hash
    cluster: test_cluster
    settings:
      - max_memory_usage = 15000 MIN 15000 MAX 16000 READONLY
      - PROFILE 'restricted'
    state: present

- name: Create a user that can only connect from a specified host
  community.clickhouse.clickhouse_user:
    login_host: localhost
    login_user: alice
    login_db: foo
    login_password: my_password
    name: test_user
    user_hosts:
      - type: NAME
        hosts:
          - 'host1'

- name: Update user host restrictions. Any previous host restrictions will be replaced. (idempotent - only updates if different)
  community.clickhouse.clickhouse_user:
    login_host: localhost
    login_user: alice
    login_db: foo
    login_password: my_password
    name: test_user
    user_hosts:
      - type: LIKE
        hosts:
          - '%.example.com'

- name: Drop user
  community.clickhouse.clickhouse_user:
    login_host: localhost
    login_user: alice
    login_db: foo
    login_password: my_password
    name: test_user
    state: absent

Return Values 

Common return values are documented here, the following are the fields unique to this module:

Key	Description
executed_statements list / elements=string	Data-modifying executed statements. Returned: on success Sample: `["CREATE USER test_user IDENTIFIED WITH *** BY '***'"]`

Authors

Aleksandr Vagachev (@aleksvagachev)
Andrew Klychkov (@Andersson007)

community.clickhouse.clickhouse_user module – Creates or removes a ClickHouse user using the clickhouse-driver Client interface

Synopsis

Requirements

Parameters

Attributes

Notes

Examples

Return Values