8.1 InnoDB ClusterSet Requirements

The basis of an InnoDB ClusterSet deployment is an existing InnoDB Cluster at MySQL 8.0.27 or higher, and a number of standalone MySQL Server instances that can be formed into replica clusters to provide disaster tolerance for this primary cluster. If you want to try out InnoDB ClusterSet, you can use MySQL Shell 8.0.27 or higher to set up a sandbox deployment on your local machine. You will need to install MySQL Server 8.0.27 or higher and MySQL Router 8.0.27 or higher. Using AdminAPI commands in MySQL Shell, you can create sandbox MySQL Server instances, set up an InnoDB Cluster using some of them, then follow the instructions in this section to set up an InnoDB ClusterSet deployment using the others as replica clusters. For instructions to deploy and manage sandbox instances, see Section 6.8, “AdminAPI MySQL Sandboxes”.

Important

It is recommended that you always use the most recent version of MySQL Shell available. The latest version of MySQL Shell can be used with any GA version of MySQL 5.7 or 8.0.

To set up a production deployment of InnoDB ClusterSet, ensure that you have the following components in place:

• Software components

• InnoDB Cluster

• MySQL Server instances

• MySQL Router instances

Software components

MySQL Server 8.0.27 or higher, MySQL Shell 8.0.27 or higher, and MySQL Router 8.0.27 or higher are required to set up an InnoDB ClusterSet deployment. These are the software components required by AdminAPI. See Section 6.2, “Installing AdminAPI Software Components”.

Always use the most recent versions of MySQL Shell and MySQL Router that are available to you, and ensure that their version is the same as or higher than the MySQL Server release. Both products can manage older MySQL Server releases, but older versions cannot manage features in newer MySQL Server releases.

InnoDB Cluster

An existing InnoDB Cluster that is to be the primary cluster. This is the cluster for which the InnoDB ClusterSet deployment provides disaster tolerance. A Group Replication group can be adopted as an InnoDB Cluster. For instructions to set up an InnoDB Cluster or adopt a Group Replication group, see Section 7.4, “Deploying a Production InnoDB Cluster”.

The InnoDB Cluster that is to be the primary cluster must meet these requirements:

• The cluster must not already be part of an InnoDB ClusterSet deployment. An InnoDB Cluster can only participate in one InnoDB ClusterSet deployment.

• All member server instances in the cluster must be at MySQL 8.0.27 or higher.

• The InnoDB Cluster metadata version must be 2.1.0 or higher. When you carry out any operation on a cluster (for example a dba.getCluster() command), AdminAPI warns you if the cluster's metadata needs updating. You can update the metadata to an appropriate version for InnoDB ClusterSet operations by issuing a dba.upgradeMetadata() command in MySQL Shell 8.0.27 or higher. Note that after you upgrade a cluster's metadata, it cannot be administered by older MySQL Shell versions. For more information, see Section 6.11, “Upgrade Metadata Schema”.

• The cluster must be in single-primary mode. An InnoDB Cluster can be in single-primary or multi-primary mode, but InnoDB ClusterSet does not support multi-primary mode. You can use a cluster.switchToSinglePrimaryMode() command in MySQL Shell to convert a cluster in multi-primary mode to single-primary mode, and choose an instance to be the primary server.

• For MySQL Server instances at release 8.0.27 and above, for an InnoDB Cluster that is part of an InnoDB ClusterSet, the group_replication_view_change_uuid system variable must be set with the same value on all the member servers in the cluster to supply an alternative UUID for view change events. From MySQL 8.0.27, an InnoDB Cluster that is created using the dba.createCluster() command gets a value generated and set for the system variable on all the member servers. InnoDB Cluster created before MySQL 8.0.27 might not have the system variable set, but the InnoDB ClusterSet creation process checks for this and fails with a warning if it is absent.

  The Cluster.rescan() command can be used to generate and set a value for group_replication_view_change_uuid on all the member servers in an InnoDB Cluster. Before MySQL Shell 8.0.29, the command does this automatically when scanning a cluster, following which you must reboot the cluster to implement the changes. From MySQL Shell 8.0.29, the command returns a warning message to let you know you must set a value for the system variable, or you can enable the option updateViewChangeUuid to generate and set a value automatically during the scan. When you have rebooted the cluster, you can retry the InnoDB ClusterSet creation process.

• There must be no inbound replication channels on any member server from servers outside the group. The channels created automatically by Group Replication (group_replication_applier and group_replication_recovery) are allowed.

• You need to know the InnoDB Cluster server configuration account user name and password for the cluster (see Section 8.3, “User Accounts for InnoDB ClusterSet”). This is the account that was set up using dba.configureInstance on the member servers in the InnoDB Cluster. You will need to create this account on the MySQL Server instances that will form the replica clusters, and use it to set them up.

  Note

  You cannot use an InnoDB Cluster administrator account (set up using cluster.setupAdminAccount()) to set up the standalone MySQL Server instances for the replica cluster. cluster.setupAdminAccount() is not available on a standalone instance, and if you create one of those accounts on the standalone instances using dba.configureInstance or manually, it will subsequently be replicated from the primary cluster, causing replication to stop with an error.

• At the time when you create the InnoDB ClusterSet deployment, the InnoDB Cluster must be online and healthy, and its primary member server must be reachable using MySQL Shell.

MySQL Server instances

A number of standalone MySQL Server instances which you can make into one or more replica clusters. A minimum of three member servers in each replica cluster is recommended for fault tolerance, although the InnoDB ClusterSet deployment can include replica clusters consisting of a single server instance. In a production deployment for disaster tolerance, each replica cluster would be in an alternate location, such as a different datacenter.

Each of the MySQL Server instances that you use in the replica clusters must meet these requirements:

• The server is not already part of an InnoDB ClusterSet deployment, InnoDB ClusterSet, or InnoDB ReplicaSet.

• You do not need the data on the server. If the server has previously been used for processing transactions, the data will be overwritten when it is made into a member of the replica cluster (unless the transactions happen to be a subset of those on the primary cluster).

• The server is not part of a currently running Group Replication group (even if the individual server has left the group). You cannot adopt an existing Group Replication group or a current or ex-member of it as a replica cluster. If you want to use server instances that are currently in a replication group, issue STOP GROUP_REPLICATION on all the members of the group, so that the group is fully offline. The separate server instances can then be made into a replica cluster using AdminAPI.

  Important

  Exercise caution over using former Group Replication group members as members of an InnoDB ClusterSet replica cluster, especially if you made a lot of changes to the Group Replication configuration options, or if the group was created in a much earlier release and you made configuration changes based on the situation in that release.

  The InnoDB ClusterSet replica cluster creation process overwrites any existing persisted Group Replication configuration options for which you specify new settings on the command. It also always overwrites the following system variables, even if you do not specify them on the command: group_replication_group_name, group_replication_group_seeds, group_replication_local_address, group_replication_view_change_uuid, and group_replication_enforce_update_everywhere_checks. However, other Group Replication configuration options that you have changed are left as they were. These custom settings could potentially interfere with the running or performance of InnoDB ClusterSet, which expects the MySQL 8.0.27 defaults to be used for Group Replication configuration options that are not changed during the InnoDB ClusterSet replica cluster creation process.

  If you do want to use a configured Group Replication server, check and remove any customizations if possible, in particular checking that the group_replication_single_primary_mode system variable is set to the default of ON. The safest option for an ex-Group Replication group member in this situation is to reinstall MySQL Server, rather than upgrading the installation to MySQL 8.0.27.

• The server is at MySQL 8.0.27 or higher. If you want to provision further member servers for the replica cluster by cloning, all the servers must be at the same release and on the same operating system.

• The server has a server ID (server_id system variable) and server UUID (server_uuid system variable) that are unique in the entire InnoDB ClusterSet, including any offline or unreachable member servers.

• No inbound replication channels are configured on the server. Only the Group Replication channels (group_replication_applier and group_replication_recovery) are allowed.

• The server can connect to the primary cluster in the InnoDB ClusterSet, and the primary cluster can connect to it.

• At the time when you create the InnoDB ClusterSet deployment, the server must be online and healthy, and reachable using MySQL Shell.

The required user account credentials, InnoDB ClusterSet metadata, and Group Replication configuration will be set up during the InnoDB ClusterSet replica cluster creation process.

MySQL Router instances

One or more MySQL Router instances to route client application traffic to the appropriate clusters in the InnoDB ClusterSet deployment. The recommended deployment of MySQL Router is on the same host as the client application.

Important

If you are using an existing InnoDB Cluster as the primary cluster in your InnoDB ClusterSet deployment, and you bootstrapped MySQL Router against that cluster already, bootstrap it again using the --force option against the InnoDB ClusterSet, then stop and restart MySQL Router. The settings in the MySQL Router instance's static configuration file need to be updated for InnoDB ClusterSet. Follow the process described in Section 8.5, “Integrating MySQL Router With InnoDB ClusterSet” to do this.