mysql_user, mysql_role: add argument subtract_privs to revoke privileges explicitly (#333)

* add option subtract_privs to mysql_role and mysql_user

see https://github.com/ansible-collections/community.mysql/issues/331

* add integration tests for subtract_privs for mysql_role and mysql_user

* add changelog fragment for PR #333

* mysql_role, mysql_user: when subtract_privileges, don't grant unwanted privileges and don't revoke USAGE implicitly

* fix integration tests

* mysql_role, mysql_user: invalid privileges are ignored when subtract_privs is true -> document that and fix integration tests

* fix mysql_role integration tests

* fix mysql_role, mysql_user integration tests

* formatting

make the PEP8 check happy

* mysql_user and mysql_role: fix granting privileges when only the GRANT OPTION needs to be added

* mysql_user and mysql_role: log some updated privileges; explain integration test blind spot

* mysql_user and mysql_role: don't grant too much privileges

If only the grant option needs to be granted, at least one privilege needs to be granted to get valid syntax. USAGE is better for that than the existing privileges, because unwanted privileges would be re-added after revokation.

* mysql_user and mysql_role: fix type error

* Update changelogs/fragments/333-mysql_user-mysql_role-add-subtract_privileges-argument.yml

Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>

* Update plugins/modules/mysql_role.py

Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>

* Update plugins/modules/mysql_user.py

Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>

Co-authored-by: Felix Hamme <felix.hamme@ionos.com>
Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>

plugins/modules/mysql_user.py

@@ -63,7 +63,15 @@ options:
   append_privs:
     description:
       - Append the privileges defined by priv to the existing ones for this
-        user instead of overwriting existing ones.
+        user instead of overwriting existing ones. Mutually exclusive with I(subtract_privs).
+    type: bool
+    default: no
+  subtract_privs:
+    description:
+      - Revoke the privileges defined by the I(priv) option and keep other existing privileges.
+        If set, invalid privileges in I(priv) are ignored.
+        Mutually exclusive with I(append_privs).
+    version_added: '3.2.0'
     type: bool
     default: no
   tls_requires:
@@ -306,6 +314,13 @@ EXAMPLES = r'''
       MAX_QUERIES_PER_HOUR: 10
       MAX_CONNECTIONS_PER_HOUR: 5
 
+- name: Ensure bob does not have the DELETE privilege
+  community.mysql.mysql_user:
+    name: bob
+    subtract_privs: yes
+    priv:
+      'db1.*': DELETE
+
 # Example .my.cnf file for setting the root password
 # [client]
 # user=root
@@ -352,6 +367,7 @@ def main():
         priv=dict(type='raw'),
         tls_requires=dict(type='dict'),
         append_privs=dict(type='bool', default=False),
+        subtract_privs=dict(type='bool', default=False),
         check_implicit_admin=dict(type='bool', default=False),
         update_password=dict(type='str', default='always', choices=['always', 'on_create'], no_log=False),
         sql_log_bin=dict(type='bool', default=True),
@@ -364,6 +380,7 @@ def main():
     module = AnsibleModule(
         argument_spec=argument_spec,
         supports_check_mode=True,
+        mutually_exclusive=(('append_privs', 'subtract_privs'),)
     )
     login_user = module.params["login_user"]
     login_password = module.params["login_password"]
@@ -379,6 +396,7 @@ def main():
     connect_timeout = module.params["connect_timeout"]
     config_file = module.params["config_file"]
     append_privs = module.boolean(module.params["append_privs"])
+    subtract_privs = module.boolean(module.params['subtract_privs'])
     update_password = module.params['update_password']
     ssl_cert = module.params["client_cert"]
     ssl_key = module.params["client_key"]
@@ -427,7 +445,7 @@ def main():
             mode = get_mode(cursor)
         except Exception as e:
             module.fail_json(msg=to_native(e))
-        priv = privileges_unpack(priv, mode)
+        priv = privileges_unpack(priv, mode, ensure_usage=not subtract_privs)
 
     if state == "present":
         if user_exists(cursor, user, host, host_all):
@@ -435,11 +453,11 @@ def main():
                 if update_password == "always":
                     changed, msg = user_mod(cursor, user, host, host_all, password, encrypted,
                                             plugin, plugin_hash_string, plugin_auth_string,
-                                            priv, append_privs, tls_requires, module)
+                                            priv, append_privs, subtract_privs, tls_requires, module)
                 else:
                     changed, msg = user_mod(cursor, user, host, host_all, None, encrypted,
                                             plugin, plugin_hash_string, plugin_auth_string,
-                                            priv, append_privs, tls_requires, module)
+                                            priv, append_privs, subtract_privs, tls_requires, module)
 
             except (SQLParseError, InvalidPrivsError, mysql_driver.Error) as e:
                 module.fail_json(msg=to_native(e))
@@ -447,6 +465,8 @@ def main():
             if host_all:
                 module.fail_json(msg="host_all parameter cannot be used when adding a user")
             try:
+                if subtract_privs:
+                    priv = None  # avoid granting unwanted privileges
                 changed = user_add(cursor, user, host, host_all, password, encrypted,
                                    plugin, plugin_hash_string, plugin_auth_string,
                                    priv, tls_requires, module.check_mode)