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(
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
name
)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.
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
operation. For example to create a user named
Cluster
.setupAdminAccount()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.
The dba.createCluster()
operation supports
MySQL Shell's interactive
option. When
interactive
is on, prompts appear in the
following situations:
If the instance belongs to a Group Replication group, and
adoptFromGr: true
is not set as an option, you are asked if you want to adopt the replication group.If
force: true
is not set as an option, you are asked to confirm the creation of a multi-primary cluster.
When you run dba.createCluster()
, and when
you add a further server instance to the InnoDB Cluster by
running
,
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:
Cluster
.addInstance()
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'
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()
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 8.0.14 and later,
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”.
As of MySQL Shell 8.0.33, it is possible to enable or disable
group_replication_paxos_single_leader
using dba.createCluster()
.
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.
When you create a cluster using MySQL Shell 8.0.28 and later,
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'})
As of MySQL Shell 8.0.30, 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”.