6.4 Creating User Accounts for AdminAPI

The user accounts used to configure and administer a member server instance in an InnoDB Cluster, InnoDB ClusterSet, or InnoDB ReplicaSet deployment must have full read and write privileges on the metadata tables, in addition to full MySQL administrator privileges (SUPER, GRANT OPTION, CREATE, DROP and so on). For more information, see Privileges Provided by MySQL.

You can use the root account on the servers for this purpose, but if you do this, the root account on every member server in the deployment must have the same password. Using the root account is not recommended for security reasons.

Instead, the recommended method is to set up user accounts using AdminAPI's JavaScript dba.configureInstance() and cluster.setupAdminAccount() operations. The format of the user names accepted by these operations follows the standard MySQL account name format, see Specifying Account Names.

If you prefer to set up the user accounts, the required permissions are listed in Configuring InnoDB Cluster Administrator Accounts Manually. If only read operations are needed, for example, for monitoring purposes, you can use an account with more restricted privileges, as detailed in this topic.

Important

Each account used to configure or administer an InnoDB Cluster, InnoDB ClusterSet, or InnoDB ReplicaSet deployment must exist on all the member server instances in the deployment, with the same user name, and the same password.

Server Configuration Account

A server configuration account is required on each server instance that is to join an InnoDB Cluster, InnoDB ClusterSet, or InnoDB ReplicaSet deployment. You set this account up using a dba.configureInstance() JavaScript command or dba.configure_instance() Python command, with the clusterAdmin option.

For better security, specify the password at the interactive prompt, otherwise specify it using the clusterAdminPassword option. Create the same account, with the same user name and password, in the same way on every server instance that will be part of the deployment, both the instance you connect to create the deployment and the instances that will join after that.

You can define a password expiration using the clusterAdminPasswordExpiration option. This option can be set to a number of days, NEVER to never expire, or DEFAULT, to use the system default.

If you are using SSL certificates for authentication, you can add the certificate issuer and subject using the clusterAdminCertIssuer and clusterAdminCertSubject options, respectively.

The server configuration account that you create using the dba.configureInstance() operation is not replicated to other servers in the InnoDB Cluster, InnoDB ClusterSet, or InnoDB ReplicaSet deployment. MySQL Shell disables binary logging for the dba.configureInstance() operation. For this reason, you must create the account on every server instance individually.

The clusterAdmin option must be used with a MySQL Shell connection based on a user which has the privileges to create users with suitable privileges. In this JavaScript example the root user is used:

mysql-js> dba.configureInstance('root@ic-1:3306', {clusterAdmin: "'icadmin'@'ic-1%'"});

Again, in this Python example the root user is used:

mysql-py> dba.configure_instance('root@ic-1:3306', clusterAdmin="'icadmin'@'ic-1%'");

Administrator Accounts

Administrator accounts can be used to administer a deployment after you have completed the configuration process. You can set up more than one of them. To create an administrator account, you issue a cluster.setupAdminAccount() JavaScript command after you have added all the instances to the InnoDB Cluster or InnoDB ReplicaSet. Or issue the Python command: <Cluster>setup_admin_account().

The command creates an account with the user name and password that you specify, with all the required permissions. A transaction to create an account with cluster.setupAdminAccount() is written to the binary log and sent to all the other server instances in the cluster to create the account on them.

To use the setupAdminAccount() operation, you must be connected as a MySQL user with privileges to create users, for example as root. The setupAdminAccount(user) operation also enables you to upgrade an existing MySQL account with the necessary privileges before a dba.upgradeMetadata() JavaScript operation, or the dba.upgrade_metadata() Python operation.

The mandatory user argument is the name of the MySQL account you want to create to be used to administer the deployment. The format of the user names accepted by the setupAdminAccount() operation follows the standard MySQL account name format. For more information, see Specifying Account Names. The user argument format is username[@host] where host is optional and if it is not provided it defaults to the % wildcard character.

For example, to create a user named icadmin to administer an InnoDB Cluster assigned to the variable myCluster using JavaScript, issue:

mysql-js> myCluster.setupAdminAccount('icadmin')

Missing the password for new account icadmin@%. Please provide one.
Password for new account: ********
Confirm password: ********

Creating user icadmin@%.
Setting user password.
Account icadmin@% was successfully created.

Or using Python:

mysql-py> myCluster.setup_admin_account('icadmin')

Missing the password for new account icadmin@%. Please provide one.
Password for new account: ********
Confirm password: ********

Creating user icadmin@%.
Setting user password.
Account icadmin@% was successfully created.

setupAdminAccount() has the following SSL-specific options:

• requireCertIssuer: Optional SSL certificate issuer for the account.

• requireCertSubject: Optional SSL certificate subject for the account.

• passwordExpiration: numberOfDays | Never | Default: Password expiration setting for the account.

Note

If either requireCertIssuer or requireCertSubject are set, or both, the existing password becomes optional.

Updating Old Accounts

If you have a server configuration account or administrator account created with a version prior to MySQL Shell 8.0.20, use the update option with the setupAdminAccount() operation to upgrade the privileges of the existing user. This is relevant during an upgrade, to ensure that the user accounts are compatible. For example, to upgrade the user named icadmin, using JavaScript, issue:

mysql-js> myCluster.setupAdminAccount('icadmin', {'update':1})
Updating user icadmin@%.
Account icadmin@% was successfully updated.

Or using Python:

mysql-py> myCluster.setup_admin_account('icadmin',update=1})
Updating user icadmin@%.
Account icadmin@% was successfully updated.

This is a special use of the cluster.setupAdminAccount() command that is not written to the binary log.