ansible.mysql.mysql_clone module – Clone a MySQL instance from a donor server

Note

This module is part of the ansible.mysql collection (version 5.2.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 ansible.mysql. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: ansible.mysql.mysql_clone.

New in ansible.mysql 5.1.0

Synopsis

• Starts a MySQL remote clone operation on the recipient server and waits until the clone reaches a terminal state.

• Validates MySQL Clone plugin prerequisites on the recipient server but does not install or manage the plugin.

• The module is limited to MySQL Clone plugin behavior and fails on MariaDB.

Requirements

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

• PyMySQL (Python 2.7 and Python 3.x)

Parameters

Parameter	Comments
ca_cert aliases: ssl_ca path	The path to a Certificate Authority (CA) certificate. This option, if used, must specify the same certificate as used by the server.
check_hostname boolean added in ansible.mysql 1.1.0	Whether to validate the server host name when an SSL connection is required. Corresponds to MySQL CLIs --ssl switch. Setting this to false disables hostname verification. Use with caution. Requires pymysql >= 0.7.11. Choices: false true
client_cert aliases: ssl_cert path	The path to a client public key certificate.
client_key aliases: ssl_key path	The path to the client private key.
config_file path	Specify a config file from which user and password are to be read. The default config file, ~/.my.cnf, if it exists, will be read, even if config_file is not specified. The default config file, ~/.my.cnf, if it exists, must contain a [client] section as a MySQL connector requirement. To prevent the default config file from being read, set config_file to be an empty string. Default: "~/.my.cnf"
connect_timeout integer	The connection timeout when connecting to the MySQL server. Default: 30
donor_host string / required	Hostname or IP address of the donor MySQL server.
donor_password string / required	Password used by the recipient to connect to the donor for clone. The password is sent to MySQL as part of the CLONE INSTANCE FROM ... statement.
donor_port integer	TCP port of the donor MySQL server. Default: 3306
donor_user string / required	User account used by the recipient to connect to the donor for clone.
login_host string	Host running the database. In some cases for local connections the login_unix_socket=/path/to/mysqld/socket, that is usually /var/run/mysqld/mysqld.sock, needs to be used instead of login_host=localhost. Default: "localhost"
login_password string	The password used to authenticate with.
login_port integer	Port of the MySQL server. Requires login_host be defined as other than localhost if login_port is used. Default: 3306
login_unix_socket string	The path to a Unix domain socket for local connections. Use this parameter to avoid the Please explicitly state intended protocol error.
login_user string	The username used to authenticate with.
poll_interval integer	Number of seconds to wait between reconnect and status polling attempts. Default: 5
require_ssl boolean	Whether to append REQUIRE SSL or REQUIRE NO SSL to the clone statement. If omitted, no SSL clause is added and MySQL server defaults apply. Choices: false true
wait_timeout integer	Maximum number of seconds to wait for the recipient to reconnect and the clone to reach a terminal state. Default: 1800

Attributes

Attribute	Support	Description
check_mode	Support: partial In check mode the module does not start clone, but it still validates static recipient-side prerequisites.	Can run in check_mode and return changed status prediction without modifying target.
idempotent	Support: partial The module is not idempotent because each successful invocation starts a new clone operation.	When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. This assumes that the system controlled/queried by the module has not changed in a relevant way.

Notes

Note

• MySQL Clone plugin must already be installed and active on the recipient server.

• Recipient-side clone variables such as clone_valid_donor_list must be configured before running the module.

• The module is not idempotent. Running it again starts a new clone operation if MySQL accepts it.

• In check mode the module validates static prerequisites and reports that clone would be started, but does not execute clone.

• MariaDB is not supported. Use backup and replication workflows instead.

• Requires the PyMySQL (Python 2.7 and Python 3.X) package installed on the remote host. The Python package may be installed with apt-get install python-pymysql (Ubuntu; see ansible.builtin.apt) or yum install python2-PyMySQL (RHEL/CentOS/Fedora; see ansible.builtin.yum). You can also use dnf install python2-PyMySQL for newer versions of Fedora; see ansible.builtin.dnf.

• Be sure you have PyMySQL library installed on the target machine for the Python interpreter Ansible discovers. For example if ansible discovers and uses Python 3, you need to install the Python 3 version of PyMySQL. If ansible discovers and uses Python 2, you need to install the Python 2 version of PyMySQL.

• If you have trouble, it may help to force Ansible to use the Python interpreter you need by specifying ansible_python_interpreter. For more information, see https://docs.ansible.com/ansible/latest/reference_appendices/interpreter_discovery.html.

• Both login_password and login_user are required when you are passing credentials. If none are present, the module will attempt to read the credentials from ~/.my.cnf, and finally fall back to using the MySQL default login of ‘root’ with no password.

• If there are problems with local connections, using login_unix_socket=/path/to/mysqld/socket instead of login_host=localhost might help. As an example, the default MariaDB installation of version 10.4 and later uses the unix_socket authentication plugin by default that without using login_unix_socket=/var/run/mysqld/mysqld.sock (the default path) causes the error ``Host ‘127.0.0.1’ is not allowed to connect to this MariaDB server``.

• If credentials from the config file (for example, /root/.my.cnf) are not needed to connect to a database server, but the file exists and does not contain a [client] section, before any other valid directives, it will be read and this will cause the connection to fail, to prevent this set it to an empty string, (for example config_file: '').

• To avoid the Please explicitly state intended protocol error, use the login_unix_socket argument, for example, login_unix_socket: /run/mysqld/mysqld.sock.

• Alternatively, to avoid using login_unix_socket argument on each invocation you can specify the socket path using the `socket` option in your MySQL config file (usually ~/.my.cnf) on the destination host, for example socket=/var/lib/mysql/mysql.sock.

See Also

See also

ansible.mysql.mysql_variables

Manage MySQL or MariaDB global variables.

ansible.mysql.mysql_replication

Manage MySQL or MariaDB replication.

Examples

- name: Configure recipient donor allow-list separately
  ansible.mysql.mysql_variables:
    variable: clone_valid_donor_list
    value: "192.0.2.10:3306"
    mode: persist

- name: Start clone and wait for completion
  ansible.mysql.mysql_clone:
    donor_host: 192.0.2.10
    donor_port: 3306
    donor_user: clone_user
    donor_password: supersecret
    login_unix_socket: /run/mysqld/mysqld.sock

- name: Preview clone action in check mode
  check_mode: true
  ansible.mysql.mysql_clone:
    donor_host: 192.0.2.10
    donor_user: clone_user
    donor_password: supersecret
    login_unix_socket: /run/mysqld/mysqld.sock

Return Values

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

Key	Description
clone_progress list / elements=dictionary	Rows from performance_schema.clone_progress collected when the clone reaches a terminal state. Returned: on success or on clone failure after status was collected
clone_status dictionary	Final row from performance_schema.clone_status for the current or last clone operation. Returned: on success or on clone failure after status was collected
query string	Clone statement executed or predicted, with the password redacted. Returned: always Sample: "CLONE INSTANCE FROM 'clone_user'@'192.0.2.10':3306 IDENTIFIED BY '********'"

Authors

• Ron Gershburg (@rgershbu)

Collection links

• Issue Tracker
• Repository (Sources)