7.4.3 Creating an InnoDB Cluster

Once you have prepared your instances, use the dba.createCluster() function to create the cluster, using the instance which MySQL Shell is connected to as the seed instance for the cluster. The seed instance is replicated to the other instances that you add to the cluster, making them replicas of the seed instance. In this procedure the ic-1 instance is used as the seed. When you issue dba.createCluster(name) MySQL Shell creates a classic MySQL protocol session to the server instance connected to the MySQL Shell's current global session. For example, to create a cluster called testCluster and assign the returned cluster to a variable called cluster:

mysql-js> var cluster = dba.createCluster('testCluster')
Validating instance at icadmin@ic-1:3306...
This instance reports its own address as ic-1
Instance configuration is suitable.
Creating InnoDB cluster 'testCluster' on 'icadmin@ic-1:3306'...
Adding Seed Instance...
Cluster successfully created. Use Cluster.addInstance() to add MySQL instances.
At least 3 instances are needed for the cluster to be able to withstand up to
one server failure.

Note

The Cluster's name must be non-empty and no greater than 63 characters long. It can only start with an alphanumeric character or with _ (underscore), and can only contain alphanumeric, _ ( underscore), . (period), or - (hyphen) characters.

This pattern of assigning the returned cluster to a variable enables you to then execute further operations against the cluster using the Cluster object's methods. The returned Cluster object uses a new session, independent from the MySQL Shell's global session. This ensures that if you change the MySQL Shell global session, the Cluster object maintains its session to the instance.

To be able to administer a cluster, you must ensure that you have a suitable user which has the required privileges. The recommended approach is to create an administration user. If you did not create an administration user when configuring your instances, use the Cluster.setupAdminAccount() operation. For example to create a user named icadmin that can administer the InnoDB Cluster assigned to the variable cluster, issue:

mysql-js> cluster.setupAdminAccount("icadmin")

See Configuring InnoDB Cluster Administrator Accounts Manually for more information on InnoDB Cluster administrator accounts.

When you run dba.createCluster(), and when you add a further server instance to the InnoDB Cluster by running Cluster.addInstance(), the following errors are logged to the MySQL server instance's error log. These messages are harmless and relate to the way AdminAPI starts Group Replication:

2020-02-10T10:53:43.727246Z 12 [ERROR] [MY-011685] [Repl] Plugin
group_replication reported: 'The group name option is mandatory'
2020-02-10T10:53:43.727292Z 12 [ERROR] [MY-011660] [Repl] Plugin
group_replication reported: 'Unable to start Group Replication on boot'

Note

If you encounter an error related to metadata being inaccessible you might have the loopback network interface configured. For correct InnoDB Cluster usage disable the loopback interface.

To check the cluster has been created, use the cluster instance's status() function. See Checking a cluster's Status with Cluster.status().

Tip

Once server instances belong to a cluster it is important to only administer them using MySQL Shell and AdminAPI. Attempting to manually change the configuration of Group Replication on an instance once it has been added to a cluster is not supported. Similarly, modifying server variables critical to InnoDB Cluster, such as server_uuid, after an instance is configured using AdminAPI is not supported.

When you create a cluster using MySQL Shell, you can set the amount of time to wait before instances are expelled from the cluster, for example when they become unreachable. Pass the expelTimeout option to the dba.createCluster() operation, which configures the group_replication_member_expel_timeout variable on the seed instance. The expelTimeout option can take an integer value in the range of 0 to 3600. All instances running MySQL server 8.0.13 and later which are added to a cluster with expelTimeout configured are automatically configured to have the same expelTimeout value as configured on the seed instance.

For information on the other options which you can pass to dba.createCluster(), see Section 7.9, “Modifying or Dissolving an InnoDB Cluster”.

It is possible to enable or disable group_replication_paxos_single_leader using dba.createCluster().

Note

This can only be set by MySQL Shell on MySQL Server 8.0.31, or higher, because MySQL Shell requires the information provided by WRITE_CONSENSUS_SINGLE_LEADER_CAPABLE in the replication_group_communication_information table, which was introduced in MySQL 8.0.31.

InnoDB Cluster replicationAllowedHost

When you create a cluster, if you have security requirements that all accounts created automatically by AdminAPI have strict authentication requirements, you can set a value for the replicationAllowedHost cluster configuration option. The replicationAllowedHost option means that all accounts created automatically can only connect from allowed hosts, using strict subnet-based filtering. Previously, the Internal User Accounts Created by InnoDB Cluster, by default, were accessible from anywhere.

The replicationAllowedHost option can take a string value. For example, to create a cluster called testCluster and set the replicationAllowedHost option to 192.0.2.0/24, issue:

mysql-js> dba.createCluster('testCluster', {replicationAllowedHost:'192.0.2.0/24'})

Configuring the Communication Stack

InnoDB Cluster supports the MySQL communication stack introduced for Group Replication in MySQL 8.0.27.

The option, communicationStack: XCOM|MYSQL sets the value of the Group Replication system variable group_replication_communication_stack.

For example:

       mysql-js> dba.createCluster("testCluster", {communicationStack: "xcom"})

The MYSQL communication stack is the default for all new clusters created for MySQL 8.0.27, or higher.

For more information, see Section 7.5.9, “Configuring the Group Replication Communication Stack”.