community.mysql.mysql_role 模块 – 添加、删除或更新 MySQL 或 MariaDB 角色

注意

此模块是 community.mysql 集合 (版本 3.11.0) 的一部分。

如果您使用的是 ansible 包,则可能已经安装了此集合。它不包含在 ansible-core 中。要检查它是否已安装,请运行 ansible-galaxy collection list

要安装它,请使用: ansible-galaxy collection install community.mysql。您需要其他要求才能使用此模块,请参阅 要求 获取详细信息。

要在剧本中使用它,请指定: community.mysql.mysql_role

community.mysql 2.2.0 中的新增功能

概要

  • 添加、删除或更新 MySQL 或 MariaDB 角色。

  • 从 MySQL 8.0.0 和 MariaDB 10.0.5 开始支持角色。

要求

执行此模块的主机需要以下要求。

  • PyMySQL (Python 2.7 和 Python 3.x)

参数

参数

注释

admin

字符串

受 **MariaDB** 支持。

角色的管理员用户名(默认情况下为 *login_user*)。

append_members

布尔值

将 *members* 选项定义的成员添加到此角色的现有成员中,而不是覆盖它们。

与 *detach_members* 和 *admin* 选项互斥。

选项

  • false ← (默认)

  • true

append_privs

布尔值

将 *priv* 选项定义的权限添加到此角色的现有权限中,而不是覆盖它们。与 *subtract_privs* 互斥。

选项

  • false ← (默认)

  • true

ca_cert

别名:ssl_ca

路径

证书颁发机构 (CA) 证书的路径。如果使用此选项,则必须指定与服务器使用的证书相同的证书。

check_hostname

布尔值

在 community.mysql 1.1.0 中添加

当需要 SSL 连接时是否验证服务器主机名。对应于 MySQL CLI 的 --ssl 开关。

将其设置为 false 将禁用主机名验证。谨慎使用。

需要 pymysql >= 0.7.11。

选项

  • false

  • true

check_implicit_admin

布尔值

在尝试提供的凭据之前,检查 mysql 是否允许以 root/nopassword 身份登录。

如果成功,将忽略传递的 *login_user*/ *login_password*。

选项

  • false ← (默认)

  • true

client_cert

别名:ssl_cert

路径

客户端公钥证书的路径。

client_key

别名:ssl_key

路径

客户端私钥的路径。

column_case_sensitive

布尔值

在 community.mysql 3.8.0 中添加

默认为 false

true 时,模块不会将权限中的字段大写。

false 时,字段名将大写。在引入此功能之前,这是默认设置,但由于 MySQL/MariaDB 区分大小写,因此在大多数情况下应将其设置为 true

选项

  • false

  • true

config_file

路径

指定从中读取用户和密码的配置文件。

如果存在,则即使未指定 *config_file*,也会读取默认配置文件 ~/.my.cnf

如果存在,默认配置文件 ~/.my.cnf 必须包含一个 [client] 部分,这是 MySQL 连接器的要求。

要防止读取默认配置文件,请将 *config_file* 设置为空字符串。

默认值: "~/.my.cnf"

connect_timeout

整数

连接到 MySQL 服务器时的连接超时时间。

默认值: 30

detach_members

布尔值

从角色中分离 *members* 选项定义的成员,而不是覆盖所有当前成员。

与 *append_members* 和 *admin* 选项互斥。

选项

  • false ← (默认)

  • true

login_host

字符串

运行数据库的主机。

在某些情况下,对于本地连接,需要使用 *login_unix_socket=/path/to/mysqld/socket*(通常为 /var/run/mysqld/mysqld.sock),而不是 *login_host=localhost*。

默认值: "localhost"

login_password

字符串

用于身份验证的密码。

login_port

整数

MySQL 服务器的端口。如果使用 login_port,则需要将 *login_host* 定义为 localhost 以外的值。

默认值: 3306

login_unix_socket

字符串

本地连接的 Unix 域套接字的路径。

使用此参数可避免 Please explicitly state intended protocol 错误。

login_user

字符串

用于身份验证的用户名。

members

列表 / 元素=字符串

角色成员列表。

对于用户,使用格式 username@hostname。始终显式指定主机名部分。

对于角色,使用格式 rolename

与 *admin* 互斥。

members_must_exist

布尔值

当值为 yes 时,如果 *members* 中的任何用户不存在,则模块将失败。

当值为 no 时,*members* 中不存在的用户将被简单跳过。

选项

  • false

  • true ← (默认)

名称

字符串 / 必填

要添加或删除的角色名称。

权限

任意

MySQL 权限字符串,格式为:db.table:priv1,priv2

您可以通过使用正斜杠分隔每个权限来指定多个权限:db.table:priv/db.table:priv

此格式基于 MySQL GRANT 语句。

数据库和表名可以使用 MySQL 风格的引号。

如果使用列权限,则 priv1,priv2 部分必须与 SHOW GRANT 语句返回的结果完全相同。如果不遵循此规则,模块将始终报告更改。它包括按权限分组列 (SELECT(col1,col2) 而不是 SELECT(col1,SELECT(col2)))。

可以作为字典传递(参见示例)。

支持过程和函数的 GRANT(有关 community.mysql.mysql_user 模块的示例,请参见示例)。

set_default_role_all

布尔值

MariaDB 不支持此选项,在使用 MariaDB 时将静默忽略。

如果为 yes,则在更改时对每个 *members* 运行 **SET DEFAULT ROLE ALL TO**。

如果您想避免此行为,请显式将此选项设置为 no

选项

  • false

  • true ← (默认)

状态

字符串

如果为 present 且角色不存在,则创建该角色。

如果为 present 且角色存在,则不执行任何操作或更新其属性。

如果为 absent,则删除该角色。

选项

  • "absent"

  • "present" ← (默认)

subtract_privs

布尔值

在 community.mysql 3.2.0 中添加

撤销由 *priv* 选项定义的权限并保留其他现有权限。如果设置了此选项,则会忽略 *priv* 中无效的权限。与 *append_privs* 互斥。

选项

  • false ← (默认)

  • true

属性

属性

支持

描述

check_mode

支持:完全支持

可以在 check_mode 下运行,并在不修改目标的情况下返回更改状态预测。

备注

注意

  • 从 MySQL 8.0.0 和 MariaDB 10.0.5 开始支持角色。

  • 请注意,当状态发生更改时,模块默认会对所有传递的 *members* 运行 SET DEFAULT ROLE ALL TO。如果您想避免此行为,请将 *set_default_role_all* 设置为 no

  • 需要在远程主机上安装 PyMySQL (Python 2.7 和 Python 3.X) 包。可以使用 apt-get install python-pymysql (Ubuntu;参见 ansible.builtin.apt) 或 yum install python2-PyMySQL (RHEL/CentOS/Fedora;参见 ansible.builtin.yum) 安装 Python 包。对于较新的 Fedora 版本,您还可以使用 dnf install python2-PyMySQL;参见 ansible.builtin.dnf

  • 确保 Ansible 检测到的 Python 解释器在目标机器上安装了 PyMySQL 库。例如,如果 Ansible 检测到并使用 Python 3,则需要安装 PyMySQL 的 Python 3 版本。如果 Ansible 检测到并使用 Python 2,则需要安装 PyMySQL 的 Python 2 版本。

  • 如果遇到问题,可以通过指定 ansible_python_interpreter 来强制 Ansible 使用所需的 Python 解释器,这可能会有所帮助。有关更多信息,请参见 https://docs.ansible.org.cn/ansible/latest/reference_appendices/interpreter_discovery.html

  • 当您传递凭据时,login_passwordlogin_user 都是必需的。如果没有,模块将尝试从 ~/.my.cnf 读取凭据,最后回退到使用 MySQL 默认登录名“root”且不使用密码。

  • 如果本地连接出现问题,使用 *login_unix_socket=/path/to/mysqld/socket* 而不是 *login_host=localhost* 可能会有所帮助。例如,10.4 及更高版本的 MariaDB 默认安装使用 unix_socket 身份验证插件,如果不使用 *login_unix_socket=/var/run/mysqld/mysqld.sock*(默认路径),则会导致错误“主机‘127.0.0.1’不允许连接到此 MariaDB 服务器”。

  • 如果不需要配置文件(例如 /root/.my.cnf)中的凭据来连接到数据库服务器,但该文件存在并且在任何其他有效指令之前不包含 [client] 部分,它将被读取,这将导致连接失败,为避免这种情况,请将其设置为空字符串(例如 config_file: '')。

  • 为避免 Please explicitly state intended protocol 错误,请使用 *login_unix_socket* 参数,例如 login_unix_socket: /run/mysqld/mysqld.sock

  • 或者,为避免在每次调用时都使用 *login_unix_socket* 参数,您可以使用目标主机上的 MySQL 配置文件(通常为 ~/.my.cnf)中的 `socket` 选项指定套接字路径,例如 socket=/var/lib/mysql/mysql.sock

另请参见

另请参见

community.mysql.mysql_user

向 MySQL 或 MariaDB 数据库添加或删除用户。

MySQL 角色参考

MySQL 角色文档的完整参考。

示例

# If you encounter the "Please explicitly state intended protocol" error,
# use the login_unix_socket argument, for example, login_unix_socket: /run/mysqld/mysqld.sock

# Example of a .my.cnf file content for setting a root password
# [client]
# user=root
# password=n<_665{vS43y
#
# Example of a privileges dictionary passed through the priv option
# priv:
#   'mydb.*': 'INSERT,UPDATE'
#   'anotherdb.*': 'SELECT'
#   'yetanotherdb.*': 'ALL'
#
# You can also use the string format like in the community.mysql.mysql_user module, for example
# mydb.*:INSERT,UPDATE/anotherdb.*:SELECT/yetanotherdb.*:ALL
#
# For more examples on how to specify privileges, refer to the community.mysql.mysql_user module

# Create a role developers with all database privileges
# and add alice and bob as members.
# The statement 'SET DEFAULT ROLE ALL' to them will be run.
- name: Create role developers, add members
  community.mysql.mysql_role:
    name: developers
    state: present
    priv: '*.*:ALL'
    members:
    - 'alice@%'
    - 'bob@%'

- name: Same as above but do not run SET DEFAULT ROLE ALL TO each member
  community.mysql.mysql_role:
    name: developers
    state: present
    priv: '*.*:ALL'
    members:
    - 'alice@%'
    - 'bob@%'
    set_default_role_all: false

# Assuming that the role developers exists,
# add john to the current members
- name: Add members to an existing role
  community.mysql.mysql_role:
    name: developers
    state: present
    append_members: true
    members:
    - 'joe@localhost'

# Create role readers with the SELECT privilege
# on all tables in the fiction database
- name: Create role developers, add members
  community.mysql.mysql_role:
    name: readers
    state: present
    priv: 'fiction.*:SELECT'

# Assuming that the role readers exists,
# add the UPDATE privilege to the role on all tables in the fiction database
- name: Create role developers, add members
  community.mysql.mysql_role:
    name: readers
    state: present
    priv: 'fiction.*:UPDATE'
    append_privs: true

- name: Create role with the 'SELECT' and 'UPDATE' privileges in db1 and db2
  community.mysql.mysql_role:
    state: present
    name: foo
    priv:
      'db1.*': 'SELECT,UPDATE'
      'db2.*': 'SELECT,UPDATE'

- name: Remove joe from readers
  community.mysql.mysql_role:
    state: present
    name: readers
    members:
    - 'joe@localhost'
    detach_members: true

- name: Remove the role readers if exists
  community.mysql.mysql_role:
    state: absent
    name: readers

- name: Example of using login_unix_socket to connect to the server
  community.mysql.mysql_role:
    name: readers
    state: present
    login_unix_socket: /var/run/mysqld/mysqld.sock

# Pay attention that the admin cannot be changed later
# and will be ignored if a role currently exists.
# To change members, you need to run a separate task using the admin
# of the role as the login_user.
- name: On MariaDB, create the role readers with alice as its admin
  community.mysql.mysql_role:
    state: present
    name: readers
    admin: 'alice@%'

- name: Create the role business, add the role marketing to members
  community.mysql.mysql_role:
    state: present
    name: business
    members:
    - marketing

- name: Ensure the role foo does not have the DELETE privilege
  community.mysql.mysql_role:
    state: present
    name: foo
    subtract_privs: true
    priv:
      'db1.*': DELETE

- name: Add some members to a role and skip not-existent users
  community.mysql.mysql_role:
    state: present
    name: foo
    append_members: true
    members_must_exist: false
    members:
    - 'existing_user@localhost'
    - 'not_existing_user@localhost'

- name: Detach some members from a role and ignore not-existent users
  community.mysql.mysql_role:
    state: present
    name: foo
    detach_members: true
    members_must_exist: false
    members:
    - 'existing_user@localhost'
    - 'not_existing_user@localhost'

作者

  • Andrew Klychkov (@Andersson007)

  • Felix Hamme (@betanummeric)

  • kmarse (@kmarse)

  • Laurent Indermühle (@laurent-indermuehle)