community.clickhouse.clickhouse_grants module – Manage grants for ClickHouse users and roles

Note

This module is part of the community.clickhouse collection (version 2.4.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_grants.

New in community.clickhouse 0.9.0

Synopsis

• Grants, updates, or revokes privileges for ClickHouse users and roles.

• This module uses the clickhouse-driver client interface.

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	The name of the cluster where the row policy is defined. If not provided, the row policy will be managed on the local server.
exclusive boolean	If set to false (the default), the module will append the privileges specified in privileges to the privileges the grantee already has. If set to true, the module will revoke all current privileges from the grantee before granting the new ones. It only applies to privileges, so privileges must be set when this is true. It has no effect on partial_revokes. To remove all privileges, use state=absent instead. Choices: false ← (default) true
grantee string / required	A user or a role to grant, update, or revoke privileges for.
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.
partial_revokes list / elements=dictionary added in community.clickhouse 2.4.0	A list of privileges to partial revoke from the grantee. At this moment this works only with state present. State absent will not grant any privileges. A privilege is only revoked when the grantee actually holds it, either from an earlier run or because it is granted by privileges in the same task. Removing an entry from this list does not grant the privilege back. Add it to privileges to restore it. Partial revokes are not represented in the diff return value.
object string / required	The database object to revoke privileges from. Use *.* for global privileges, database.* for all tables in a database, and database.table for a specific table. When passed single element like *, POSTGRES access_object will be used ex. privs READ .
privs list / elements=string / required	A list of privileges to revoke. Each privilege can be specified with or without column restrictions. Elements can be passed as separate entries in the list or as a single comma-separated string.
privileges list / elements=dictionary	Privileges to grant. This option is required when state is present, unless partial_revokes is specified. It’s a list of dictionaries, where each dictionary specifies a set of privileges on a database object.
grant_option boolean	A boolean that applies to all privileges in this set. If specified, it overrides any individual grant option settings within privs. Choices: false true
object string / required	The database object to grant privileges on. Use *.* for global privileges, database.* for all tables in a database, and database.table for a specific table.
privs dictionary / required	A dictionary of privileges. Keys are privilege names, like CREATE USER or SELECT(column1, column2). Values are booleans indicating whether to grant the privilege with the WITH GRANT OPTION. Alternatively, you can use the grant_option parameter to apply the same setting to all privileges in this set.
state string	If present, the module will grant or update privileges. If absent, the module will revoke all privileges from the grantee. Choices: "present" ← (default) "absent"
success_on list / elements=integer added in community.clickhouse 2.2.0	List of server error codes that will be treated as success, otherwise throw errors. Default: [497]

Attributes

Attribute	Support	Description
check_mode	Support: full	Supports check_mode.
idempotent	Support: full	At second run will not change anything.

Notes

Note

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

Examples

- name: Grant global privileges to a user
  community.clickhouse.clickhouse_grants:
    grantee: alice
    privileges:
      - object: '*.*'
        privs:
          "ALTER USER": true       # With grant option
          "CREATE DATABASE": false # Without grant option
          "CREATE USER": false     # Without grant option

- name: Grant privileges on a specific database
  community.clickhouse.clickhouse_grants:
    grantee: bob
    privileges:
      - object: 'infra.*'
        privs:
          "SELECT": true  # With grant option
          "INSERT": false # Without grant option

- name: Grant privileges on a cluster
  community.clickhouse.clickhouse_grants:
    grantee: bob
    cluster: test_cluster
    privileges:
      - object: 'infra.*'
        privs:
          "SELECT": true  # With grant option
          "INSERT": false # Without grant option

- name: Grant SELECT on specific columns of a table
  community.clickhouse.clickhouse_grants:
    grantee: carol
    privileges:
      - object: 'sales.customers'
        privs:
          "SELECT(name, email)": false # Without grant option

- name: Replace all existing privileges for a user
  community.clickhouse.clickhouse_grants:
    grantee: david
    exclusive: true
    privileges:
      - object: 'bar.*'
        privs:
          "SELECT": false  # Without grant option

- name: Revoke all privileges from a user
  community.clickhouse.clickhouse_grants:
    grantee: eve
    state: absent

- name: Partially revoke a single table from a database-wide grant
  community.clickhouse.clickhouse_grants:
    grantee: david
    partial_revokes:
      - object: 'bar.foo'
        privs:
          - SELECT

- name: Partially revoke single columns
  community.clickhouse.clickhouse_grants:
    grantee: david
    partial_revokes:
      - object: 'bar.foo'
        privs:
          - SELECT(a,b)

- name: Partially revoke more than one statement
  community.clickhouse.clickhouse_grants:
    grantee: david
    partial_revokes:
      - object: 'bar.foo'
        privs:
          - SELECT, INSERT

- name: Partially revoke more than one statement passed as separate entries
  community.clickhouse.clickhouse_grants:
    grantee: david
    partial_revokes:
      - object: 'bar.foo'
        privs:
          - SELECT
          - INSERT

- name: Grant a whole database and partially revoke one table in the same task
  community.clickhouse.clickhouse_grants:
    grantee: david
    privileges:
      - object: 'bar.*'
        privs:
          "SELECT": false
    partial_revokes:
      - object: 'bar.foo'
        privs:
          - SELECT

Return Values

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

Key	Description
diff dictionary	Differences between the previous and current state. Only returned when diff mode is enabled (with --diff or in check_mode). Reflects the privileges option only. Partial revokes made through partial_revokes are not represented, so a run that only changes them reports the same before and after state. Returned: when diff mode is enabled or check_mode is true
after dictionary	Grants after the change. Returned: always Sample: {"*.*": {"CREATE USER": false}, "foo.*": {"DELETE": true, "INSERT": false, "SELECT": true}}
before dictionary	Grants before the change. Returned: always Sample: {"*.*": {"CREATE USER": false}, "foo.*": {"INSERT": false, "SELECT": true}}
executed_statements list / elements=string	Data-modifying executed statements. Returned: on success Sample: ["GRANT SELECT ON foo.* TO alice", "REVOKE INSERT ON foo.* FROM alice"]

Authors

• Andrew Klychkov (@Andersson007)

• Fabian Kohn (@fako1024)

• Rafal Kozlowski (@rkozlo)

Collection links

• Issue Tracker
• Repository (Sources)
• Report an issue
• Communication