community.mysql.mysql_user 模块 – 向 MySQL 或 MariaDB 数据库添加或删除用户

注意

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

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

要安装它，请使用：ansible-galaxy collection install community.mysql。您需要其他要求才能使用此模块，请参阅需求以了解详情。

要在 playbook 中使用它，请指定：community.mysql.mysql_user。

概要 

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

需求 

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

PyMySQL (Python 2.7 和 Python 3.x)

参数 

参数	注释
append_privs 布尔值	将由 priv 定义的权限附加到此用户的现有权限，而不是覆盖现有权限。与 subtract_privs 互斥。选项 `false` ← (默认) `true`
attributes 字典在 community.mysql 3.9.0 中添加	创建、更新或删除用户的属性（任意的“键：值”注释）。 MySQL 服务器必须支持 INFORMATION_SCHEMA.USER_ATTRIBUTES 表。自 MySQL 8.0 起提供。要删除现有属性，请将其值设置为 null。
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 8 及更高版本在权限中使用区分大小写的字段名。选项 `false` `true`
config_file 路径	指定从中读取用户名和密码的配置文件。如果存在，则即使未指定 config_file，也会读取默认配置文件 `~/.my.cnf`。如果存在，默认配置文件 `~/.my.cnf` 必须包含一个 `[client]` 节，这是 MySQL 连接器的要求。要阻止读取默认配置文件，请将 config_file 设置为空字符串。默认值： `"~/.my.cnf"`
connect_timeout 整数	连接到 MySQL 服务器时的连接超时。默认值： `30`
encrypted 布尔值	指示“password”字段是 `mysql_native_password` 哈希。选项 `false` ← (默认) `true`
force_context 布尔值在 community.mysql 3.1.0 中添加	将 С(mysql) 系统数据库设置为执行语句的上下文（它将用作要连接到的数据库）。如果您在 MySQL 中使用 binlog/复制过滤器，这很有用，因为默认情况下，语句无法被 binlog/复制过滤器捕获，它们需要设置数据库才能工作，否则复制可能会中断。有关 binlog 过滤器如何工作（在主服务器上进行过滤）的说明，请参阅 https://dev.mysqlserver.cn/doc/refman/8.0/en/replication-options-binary-log.html#option_mysqld_binlog-ignore-db。有关复制过滤器如何工作（在副本上进行过滤）的说明，请参阅 https://dev.mysqlserver.cn/doc/refman/8.0/en/replication-options-replica.html#option_mysqld_replicate-ignore-db。选项 `false` ← (默认) `true`
host 字符串	MySQL 用户名的“主机”部分。默认值： `"localhost"`
host_all 布尔值	覆盖 host 选项，使 ansible 将更改应用于给定用户的全部主机名。创建用户时不能使用此选项。选项 `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 字符串	用于身份验证的用户名。
name 别名：user 字符串 / 必填	要添加或删除的用户（角色）名称。
password 字符串	设置用户的密码。仅适用于`mysql_native_password`身份验证。对于其他身份验证插件，请参见plugin、plugin_hash_string、plugin_auth_string的组合。
password_expire 字符串在 community.mysql 3.9.0 中添加	`never` - password 永不过期。 `default` - password 使用全局系统变量default_password_lifetime设置定义。 `interval` - password 将在password_expire_interval中定义的天数后过期。 `now` - password 将立即过期。选项 `"now"` `"never"` `"default"` `"interval"`
password_expire_interval 整数在 community.mysql 3.9.0 中添加	password 将过期的天数。需要password_expire=interval。
plugin 字符串在 community.mysql 0.1.0 中添加	用户的身份验证插件（``CREATE USER user IDENTIFIED WITH plugin``）。
plugin_auth_string 字符串在 community.mysql 0.1.0 中添加	用户的插件 auth_string（``CREATE USER user IDENTIFIED WITH plugin BY plugin_auth_string``）。如果plugin为``pam``（MariaDB）或``auth_pam``（MySQL），则可以使用可选的plugin_auth_string来选择特定的PAM服务。你需要定义一个salt，才能在使用``caching_sha2_password``和``sha256_password``插件更改密码时具有幂等性。
plugin_hash_string 字符串在 community.mysql 0.1.0 中添加	用户的插件哈希字符串（``CREATE USER user IDENTIFIED WITH plugin AS plugin_hash_string``）。
priv any	MySQL 权限字符串，格式为：`db.table:priv1,priv2`。此外，表和权限之间不能有空格，因为这将产生非幂等的检查模式。可以使用正斜杠分隔多个权限：`db.table1:priv/db.table2:priv`。此格式基于 MySQL `GRANT` 语句。数据库和表名可以使用 MySQL 风格的引号。如果使用列权限，则`priv1,priv2`部分必须与`SHOW GRANT`语句返回的结果完全相同。如果不遵循此规则，模块将始终报告更改。它包括按权限分组列（`SELECT(col1,col2`）而不是`SELECT(col1`,SELECT(col2))）。可以作为字典传递（参见示例）。支持针对过程和函数的 GRANT（参见示例）。注意：如果将相同的`db.table`组合多次传递给此参数，但权限不同，例如`'.:SELECT/.:SHOW VIEW'`，则只应用最后一个，在本例中，将分别应用`SHOW VIEW`。请使用`'.:SELECT,SHOW VIEW'`来同时应用两者。
resource_limits 字典在 community.mysql 0.1.0 中添加	限制用户对某些服务器资源的使用。自 MySQL 5.6 / MariaDB 10.2 起提供。可用选项为`MAX_QUERIES_PER_HOUR: num`、`MAX_UPDATES_PER_HOUR: num`、`MAX_CONNECTIONS_PER_HOUR: num`、`MAX_USER_CONNECTIONS: num`、`MAX_STATEMENT_TIME: num`（自集合版本 3.7.0 起仅支持 MariaDB）。在state=present时使用，否则忽略。
salt 字符串在 community.mysql 3.10.0 中添加	用于从plugin_auth_string生成密码哈希的盐。盐长度必须为 20 个字符。盐仅支持``caching_sha2_password``或``sha256_password``身份验证plugin。
session_vars 字典在 community.mysql 3.6.0 中添加	以`variable: value`形式的会话变量字典，在模块执行开始时设置。不能用于设置全局变量，请改用community.mysql.mysql_variables模块。
sql_log_bin 布尔值	是否应为连接启用或禁用二进制日志记录。选项 `false` `true` ← (默认)
state 字符串	用户是否应该存在。当`absent`时，删除用户。选项 `"absent"` `"present"` ← (默认)
subtract_privs 布尔值在 community.mysql 3.2.0 中添加	撤销由priv选项定义的权限，并保留其他现有权限。如果设置了此选项，则忽略priv中的无效权限。与append_privs互斥。选项 `false` ← (默认) `true`
tls_requires 字典在 community.mysql 1.0.0 中添加	将安全传输的要求设置为需求字典（参见示例）。有效要求为 SSL、X509、SUBJECT、ISSUER、CIPHER。 SUBJECT、ISSUER 和 CIPHER 是互补的，并且与 SSL 和 X509 互斥。 https://mariadb.com/kb/en/securing-connections-for-client-and-server/#requiring-tls.
update_password 字符串	`always` 将在密码不同时更新密码。这会影响password以及plugin、plugin_hash_string、plugin_auth_string的组合。 `on_create` 仅为新创建的用户设置密码或plugin、plugin_hash_string、plugin_auth_string的组合。 `on_new_username` 的作用类似于`on_create`，但它尝试重用现有密码：如果存在具有相同用户名但不同的用户，或者存在具有相同用户名和相等的`plugin`和`authentication_string`属性的多个不同用户，则现有`plugin`和`authentication_string`将用于新用户，而不是password、plugin、plugin_hash_string或plugin_auth_string参数。选项 `"always"` ← (默认) `"on_create"` `"on_new_username"`

属性 

属性	支持	描述
check_mode	支持：完全支持	可以在check_mode下运行，并在不修改目标的情况下返回更改状态预测。

备注 

注意

兼容 MySQL 或 MariaDB。
MySQL 服务器安装使用默认的login_user为root且无密码。为了将此用户作为幂等剧本的一部分进行保护，你必须至少创建两个任务：1) 更改 root 用户的密码，不提供任何login_user/login_password详细信息；2) 删除包含新 root 凭据的~/.my.cnf文件。随后运行剧本将通过从文件中读取新的凭据而成功。
目前，只支持mysql_native_password加密密码哈希模块。
需要在远程主机上安装 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，则需要安装 Python 3 版本的 PyMySQL。如果 ansible 检测到并使用 Python 2，则需要安装 Python 2 版本的 PyMySQL。
如果遇到问题，通过指定ansible_python_interpreter来强制 Ansible 使用所需的 Python 解释器可能会有所帮助。有关更多信息，请参见https://docs.ansible.org.cn/ansible/latest/reference_appendices/interpreter_discovery.html。
当你传递凭据时，login_password和login_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`（默认路径），则会导致错误“Host ‘127.0.0.1’ is not allowed to connect to this MariaDB server”。
如果不需要配置文件（例如，/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_info: 收集关于MySQL或MariaDB服务器的信息。
MySQL访问控制和账户管理参考: MySQL访问控制和账户管理文档的完整参考。
MySQL提供的权限参考: MySQL提供的权限文档的完整参考。

示例 

# If you encounter the "Please explicitly state intended protocol" error,
# use the login_unix_socket argument
- name: Removes anonymous user account for localhost
  community.mysql.mysql_user:
    name: ''
    host: localhost
    state: absent
    login_unix_socket: /run/mysqld/mysqld.sock

- name: Removes all anonymous user accounts
  community.mysql.mysql_user:
    name: ''
    host_all: true
    state: absent

- name: Create database user with name 'bob' and password '12345' with all database privileges
  community.mysql.mysql_user:
    name: bob
    password: 12345
    priv: '*.*:ALL'
    state: present

- name: Create database user using hashed password with all database privileges
  community.mysql.mysql_user:
    name: bob
    password: '*EE0D72C1085C46C5278932678FBE2C6A782821B4'
    encrypted: true
    priv: '*.*:ALL'
    state: present

# Set session var wsrep_on=off before creating the user
- name: Create database user with password and all database privileges and 'WITH GRANT OPTION'
  community.mysql.mysql_user:
    name: bob
    password: 12345
    priv: '*.*:ALL,GRANT'
    state: present
    session_vars:
      wsrep_on: off

- name: Create user with password, all database privileges and 'WITH GRANT OPTION' in db1 and db2
  community.mysql.mysql_user:
    state: present
    name: bob
    password: 12345dd
    priv:
      'db1.*': 'ALL,GRANT'
      'db2.*': 'ALL,GRANT'

# Use 'PROCEDURE' instead of 'FUNCTION' to apply GRANTs for a MySQL procedure instead.
- name: Grant a user the right to execute a function
  community.mysql.mysql_user:
    name: readonly
    password: 12345
    priv:
      FUNCTION my_db.my_function: EXECUTE
    state: present

- name: Modify user attributes, creating the attribute 'foo' and removing the attribute 'bar'
  community.mysql.mysql_user:
    name: bob
    attributes:
      foo: "foo"
      bar: null

- name: Modify user to require TLS connection with a valid client certificate
  community.mysql.mysql_user:
    name: bob
    tls_requires:
      x509:
    state: present

- name: Modify user to require TLS connection with a specific client certificate and cipher
  community.mysql.mysql_user:
    name: bob
    tls_requires:
      subject: '/CN=alice/O=MyDom, Inc./C=US/ST=Oregon/L=Portland'
      cipher: 'ECDHE-ECDSA-AES256-SHA384'

- name: Modify user to no longer require SSL
  community.mysql.mysql_user:
    name: bob
    tls_requires:

- name: Ensure no user named 'sally'@'localhost' exists, also passing in the auth credentials
  community.mysql.mysql_user:
    login_user: root
    login_password: 123456
    name: sally
    state: absent

# check_implicit_admin example
- name: >
    Ensure no user named 'sally'@'localhost' exists, also passing in the auth credentials.
    If mysql allows root/nopassword login, try it without the credentials first.
    If it's not allowed, pass the credentials
  community.mysql.mysql_user:
    check_implicit_admin: true
    login_user: root
    login_password: 123456
    name: sally
    state: absent

- name: Ensure no user named 'sally' exists at all
  community.mysql.mysql_user:
    name: sally
    host_all: true
    state: absent

- name: Specify grants composed of more than one word
  community.mysql.mysql_user:
    name: replication
    password: 12345
    priv: "*.*:REPLICATION CLIENT"
    state: present

- name: Revoke all privileges for user 'bob' and password '12345'
  community.mysql.mysql_user:
    name: bob
    password: 12345
    priv: "*.*:USAGE"
    state: present

# Example privileges string format
# mydb.*:INSERT,UPDATE/anotherdb.*:SELECT/yetanotherdb.*:ALL

- name: Example using login_unix_socket to connect to server
  community.mysql.mysql_user:
    name: root
    password: abc123
    login_unix_socket: /var/run/mysqld/mysqld.sock

- name: Example of skipping binary logging while adding user 'bob'
  community.mysql.mysql_user:
    name: bob
    password: 12345
    priv: "*.*:USAGE"
    state: present
    sql_log_bin: false

- name: Create user 'bob' authenticated with plugin 'AWSAuthenticationPlugin'
  community.mysql.mysql_user:
    name: bob
    plugin: AWSAuthenticationPlugin
    plugin_hash_string: RDS
    priv: '*.*:ALL'
    state: present

- name: Create user 'bob' authenticated with plugin 'caching_sha2_password' and static salt
  community.mysql.mysql_user:
    name: bob
    plugin: caching_sha2_password
    plugin_auth_string: password
    salt: 1234567890abcdefghij

- name: Limit bob's resources to 10 queries per hour and 5 connections per hour
  community.mysql.mysql_user:
    name: bob
    resource_limits:
      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: true
    priv:
      'db1.*': DELETE

# Example .my.cnf file for setting the root password
# [client]
# user=root
# password=n<_665{vS43y

作者

Jonathan Mainguy (@Jmainguy)
Benjamin Malynovytch (@bmalynovytch)
Lukasz Tomaszkiewicz (@tomaszkiewicz)
kmarse (@kmarse)
Laurent Indermühle (@laurent-indermuehle)