MySQL Shell 8.0 (part of MySQL 8.0)
This section describes how to use AdminAPI to configure an InnoDB Cluster.
You can check and modify the settings in place for an InnoDB Cluster while the instances are online. To check the current settings of a cluster, use the following operation:
,
which lists the configuration options for the cluster and
its instances. A boolean option Cluster
.options()all
can
also be specified to include information about all Group
Replication system variables in the output.
You can configure the options of an InnoDB Cluster at a cluster level or instance level, while instances remain online. This avoids the need to remove, reconfigure and then again add the instance to change InnoDB Cluster options. Use the following operations:
to change the
settings of all cluster instances globally or cluster
global settings such as Cluster
.setOption(option
,
value
)clusterName
.
to change the
settings of individual cluster instances
Cluster
.setInstanceOption(instance,
option
,
value
)
The way which you use InnoDB Cluster options with the operations listed depends on whether the option can be changed to be the same on all instances or not. These options are changeable at both the cluster (all instances) and per instance level:
autoRejoinTries
: integer value to
define the number of times an instance attempts to rejoin
the cluster after being expelled. See
Configuring Automatic Rejoin of Instances.
exitStateAction
: string value
indicating the Group Replication exit state action. See
Configuring Automatic Rejoin of Instances.
memberWeight
: integer value with a
percentage weight for automatic primary election on
failover. See
Configuring the Election Process.
tag:
:
built-in and user-defined tags to be associated to the
cluster. See Section 6.2.9, “Tagging the Metadata”.
option
These options are changeable at the cluster level only:
clusterName
: string value to define the
cluster name
disableClone
: boolean value used to
disable the clone usage on the cluster. See
dba.createCluster()
and MySQL Clone.
expelTimeout
: integer value to define
the time period in seconds that cluster members should
wait for a non-responding member before evicting it from
the cluster. See Creating the Cluster.
failoverConsistency
: string value
indicating the consistency guarantees that the cluster
provides. See
Configuring Automatic Rejoin of Instances.
This option is changeable at the per instance level only:
label
: a string identifier of the
instance
When you create a cluster and add instances to it, values such
as the group name, the local address, and the seed instances
are configured automatically by AdminAPI. These default
values are recommended for most deployments, but advanced
users can override the defaults by passing the following
options to the dba.createCluster()
and
.
Cluster
.addInstance()
To customize the name of the replication group created by
InnoDB Cluster, pass the groupName
option
to the dba.createCluster()
command. This
sets the
group_replication_group_name
system variable. The name must be a valid UUID.
To customize the address which an instance provides for
connections from other instances, pass the
localAddress
option to the
dba.createCluster()
and
cluster.addInstance()
commands. Specify the
address in the format
.
This sets the
host
:port
group_replication_local_address
system variable on the instance. The address must be
accessible to all instances in the cluster, and must be
reserved for internal cluster communication only. In other
words do not use this address for communication with the
instance.
To customize the instances used as seeds when an instance
joins the cluster, pass the groupSeeds
option to the dba.createCluster()
and
operations. Seed instances are contacted when a new instance
joins a cluster and are used to provide data to the new
instance. The addresses of the seed instances are specified as
a comma separated list such as
Cluster
.addInstance()host1:port1
,host2:port2
.
This configures the
group_replication_group_seeds
system variable. When a new instance is added to a cluster,
the local address of this instance is automatically appended
to the list of group seeds of all online cluster members in
order to allow them to use the new instance to rejoin the
group if necessary.
the instances in the seed list are used according to the order in which they appear in the list. This means that a user specified seed is used first and preferred over automatically added instances.
For more information see the documentation of the system variables configured by these AdminAPI options.
You can optionally configure how a single-primary cluster
elects a new primary, for example to prefer one instance as
the new primary to fail over to. Use the
memberWeight
option and pass it to the
dba.createCluster()
and
Cluster.addInstance()
methods when creating
your cluster. The memberWeight
option
accepts an integer value between 0 and 100, which is a
percentage weight for automatic primary election on failover.
When an instance has a higher precentage number set by
memberWeight
, it is more likely to be
elected as primary in a single-primary cluster. When a primary
election takes place, if multiple instances have the same
memberWeight
value, the instances are then
prioritized based on their server UUID in lexicographical
order (the lowest) and by picking the first one.
Setting the value of memberWeight
configures the
group_replication_member_weight
system variable on the instance. Group Replication limits the
value range from 0 to 100, automatically adjusting it if a
higher or lower value is provided. Group Replication uses a
default value of 50 if no value is provided. See
Single-Primary Mode for
more information.
For example to configure a cluster where
ic-3
is the preferred instance to fail over
to in the event that ic-1
, the current
primary, leaves the cluster unexpectedly use
memberWeight
as follows:
dba.createCluster('cluster1', {memberWeight:35}) var mycluster = dba.getCluster() mycluster.addInstance('icadmin@ic2', {memberWeight:25}) mycluster.addInstance('icadmin@ic3', {memberWeight:50})
Group Replication provides the ability to specify the failover
guarantees (eventual or “read your writes”) if a
primary failover happens in single-primary mode (see
Configuring Transaction Consistency Guarantees).
You can configure the failover guarantees of an
InnoDB Cluster at creation by passing the
consistency
option (prior to version 8.0.16
this option was the failoverConsistency
option, which is now deprecated) to the
dba.createCluster()
operation, which
configures the
group_replication_consistency
system variable on the seed instance. This option defines the
behavior of a new fencing mechanism used when a new primary is
elected in a single-primary group. The fencing restricts
connections from writing and reading from the new primary
until it has applied any pending backlog of changes that came
from the old primary (sometimes referred to as “read
your writes”). While the fencing mechanism is in place,
applications effectively do not see time going backward for a
short period of time while any backlog is applied. This
ensures that applications do not read stale information from
the newly elected primary.
The consistency
option is only supported if
the target MySQL server version is 8.0.14 or later, and
instances added to a cluster which has been configured with
the consistency
option are automatically
configured to have
group_replication_consistency
the same on all cluster members that have support for the
option. The variable default value is controlled by Group
Replication and is EVENTUAL
, change the
consistency
option to
BEFORE_ON_PRIMARY_FAILOVER
to enable the
fencing mechanism. Alternatively use
consistency=0
for
EVENTUAL
and
consistency=1
for
BEFORE_ON_PRIMARY_FAILOVER
.
Using the consistency
option on a
multi-primary InnoDB Cluster has no effect but is allowed
because the cluster can later be changed into single-primary
mode with the
operation.
Cluster
.switchToSinglePrimaryMode()
Instances running MySQL 8.0.16 and later support the Group
Replication automatic rejoin functionality, which enables you
to configure instances to automatically rejoin the cluster
after being expelled. See
Responses to Failure Detection and Network Partitioning for
background information. AdminAPI provides the
autoRejoinTries
option to configure the
number of tries instances make to rejoin the cluster after
being expelled. By default instances do not automatically
rejoin the cluster. You can configure the
autoRejoinTries
option at either the
cluster level or for an individual instance using the
following commands:
dba.createCluster()
Cluster.addInstance()
Cluster.setOption()
Cluster.setInstanceOption()
The autoRejoinTries
option accepts positive
integer values between 0 and 2016 and the default value is 0,
which means that instances do not try to automatically rejoin.
When you are using the automatic rejoin functionality, your
cluster is more tolerant to faults, especially temporary ones
such as unreliable networks. But if quorum has been lost, you
should not expect members to automatically rejoin the cluster,
because majority is required to rejoin instances.
Instances running MySQL version 8.0.12 and later have the
group_replication_exit_state_action
variable, which you can configure using the AdminAPI
exitStateAction
option. This controls what
instances do in the event of leaving the cluster unexpectedly.
By default the exitStateAction
option is
READ_ONLY,
which means that instances which
leave the cluster unexpectedly become read-only. If
exitStateAction
is set to
OFFLINE_MODE
(available from MySQL 8.0.18),
instances which leave the cluster unexpectedly become
read-only and also enter offline mode, where they disconnect
existing clients and do not accept new connections (except
from clients with administrator privileges). If
exitStateAction
is set to
ABORT_SERVER
then in the event of leaving
the cluster unexpectedly, the instance shuts down MySQL, and
it has to be started again before it can rejoin the cluster.
Note that when you are using the automatic rejoin
functionality, the action configured by the
exitStateAction
option only happens in the
event that all attempts to rejoin the cluster fail.
There is a chance you might connect to an instance and try to configure it using the AdminAPI, but at that moment the instance could be rejoining the cluster. This could happen whenever you use any of these operations:
Cluster.status()
dba.getCluster()
Cluster.rejoinInstance()
Cluster.addInstance()
Cluster.removeInstance()
Cluster.rescan()
Cluster.checkInstanceState()
These operations might provide extra information
while the instance is automatically rejoining the cluster. In
addition, when you are using
,
if the target instance is automatically rejoining the cluster
the operation aborts unless you pass in
Cluster
.removeInstance()force:true
.
From version 8.0.23 instances support and enable parallel replication applier threads, sometimes referred to as a multi-threaded replica. Using multiple replica applier threads in parallel improves the throughput of both the replication applier and incremental recovery.
This means that on instances running 8.0.23 and later, the following system variables must be configured:
By default, the number of applier threads (configured by the
slave_parallel_workers
system
variable) is set to 4.
When you upgrade a cluster that has been running a version of
MySQL server and MySQL Shell earlier than 8.0.23, the
instances are not configured to use the parallel replication
applier. If the parallel applier is not enabled, the output of
the
operation shows a message in the
Cluster
.status()instanceErrors
field, for example:
... "instanceErrors": [ "NOTE: The required parallel-appliers settings are not enabled on the instance. Use dba.configureInstance() to fix it." ...
In this situation you should reconfigure your instances, so
that they use the parallel replication applier. For each
instance that belongs to the InnoDB Cluster, update the
configuration by issuing
dba.configureInstance(instance)
. Note that
usually dba.configureInstance()
is used
before adding the instance to a cluster, but in this special
case there is no need to remove the instance and the
configuration change is made while it is online.
Information about the parallel replication applier is
displayed in the output of the
operation. For example, if the parallel replication applier is
enabled, then the Cluster
.status(extended=1)topology
section output
for the instance shows the number of threads under
applierWorkerThreads
. The system variables
configured for the parallel replication applier are shown in
the output of the
operation.
Cluster
.options()
You can configure the number of threads which an instance uses
for the parallel replication applier with the
applierWorkerThreads
option, which defaults
to 4 threads. The option accepts integers in the range of 0 to
1024 and can only be used with the
dba.configureInstance()
and
dba.configureReplicaSetInstance()
operations. For example, to use 8 threads, issue:
mysql-js> dba.configureInstance(instance
, {applierWorkerThreads: 8, restart: true})
The change to the number of threads used by the parallel replication applier only occurs after the instance is restarted and has rejoined the cluster.
To disable the parallel replication applier, set the
applierWorkerThreads
option to 0.
Server instances can be configured to use secure connections. For general information on using secure connections with MySQL see Using Encrypted Connections. This section explains how to configure a cluster to use encrypted connections. An additional security possibility is to configure which servers can access the cluster, see Creating an Allowlist of Servers.
Once you have configured a cluster to use encrypted
connections you must add the servers to the
ipAllowlist
.
When using dba.createCluster()
to set up a
cluster, if the server instance provides encryption then it is
automatically enabled on the seed instance. Pass the
memberSslMode
option to the
dba.createCluster()
method to specify a
different SSL mode. The SSL mode of a cluster can only be set
at the time of creation. The memberSslMode
option is a string that configures the SSL mode to be used, it
defaults to AUTO
. The permitted values are
DISABLED
, REQUIRED
, and
AUTO
. These modes are defined as:
Setting
createCluster({memberSslMode:'DISABLED'})
ensures SSL encryption is disabled for the seed instance
in the cluster.
Setting
createCluster({memberSslMode:'REQUIRED'})
then SSL encryption is enabled for the seed instance in
the cluster. If it cannot be enabled an error is raised.
Setting
createCluster({memberSslMode:'AUTO'})
(the default) then SSL encryption is automatically enabled
if the server instance supports it, or disabled if the
server does not support it.
When using the commercial version of MySQL, SSL is enabled by default and you might need to configure the allowlist for all instances. See Creating an Allowlist of Servers.
When you issue the cluster.addInstance()
and cluster.rejoinInstance()
commands, SSL
encryption on the instance is enabled or disabled based on the
setting found for the seed instance.
When using createCluster()
with the
adoptFromGR
option to adopt an existing
Group Replication group, no SSL settings are changed on the
adopted cluster:
memberSslMode
cannot be used with
adoptFromGR
.
If the SSL settings of the adopted cluster are different from the ones supported by the MySQL Shell, in other words SSL for Group Replication recovery and Group Communication, both settings are not modified. This means you are not be able to add new instances to the cluster, unless you change the settings manually for the adopted cluster.
MySQL Shell always enables or disables SSL for the cluster
for both Group Replication recovery and Group Communication,
see
Securing Group Communication Connections with Secure Socket Layer (SSL).
A verification is performed and an error issued in case those
settings are different for the seed instance (for example as
the result of a dba.createCluster()
using
adoptFromGR
) when adding a new instance to
the cluster. SSL encryption must be enabled or disabled for
all instances in the cluster. Verifications are performed to
ensure that this invariant holds when adding a new instance to
the cluster.
The dba.deploySandboxInstance()
command
attempts to deploy sandbox instances with SSL encryption
support by default. If it is not possible, the server instance
is deployed without SSL support. Use the
ignoreSslError
option set to false to
ensure that sandbox instances are deployed with SSL support,
issuing an error if SSL support cannot be provided. When
ignoreSslError
is true, which is the
default, no error is issued during the operation if the SSL
support cannot be provided and the server instance is deployed
without SSL support.
When using a cluster's
createCluster()
,
addInstance()
, and
rejoinInstance()
methods you can optionally
specify a list of approved servers that belong to the cluster,
referred to as an allowlist. By specifying the allowlist
explicitly in this way you can increase the security of your
cluster because only servers in the allowlist can connect to
the cluster.
Using the ipAllowlist
option (previously
ipWhitelist
, now deprecated) configures the
group_replication_ip_allowlist
system variable on the instance. By default, if not specified
explicitly, the allowlist is automatically set to the private
network addresses that the server has network interfaces on.
To configure the allowlist, specify the servers to add with
the ipAllowlist
option when using the
method. IP addresses must be specified in IPv4 format. Pass
the servers as a comma separated list, surrounded by quotes.
For example:
mysql-js> cluster.addInstance("icadmin@ic-3:3306", {ipAllowlist: "203.0.113.0/24, 198.51.100.110"})
This configures the instance to only accept connections from
servers at addresses 203.0.113.0/24
and
198.51.100.110
. The allowlist can also
include host names, which are resolved only when a connection
request is made by another server.
Host names are inherently less secure than IP addresses in an allowlist. MySQL carries out FCrDNS verification, which provides a good level of protection, but can be compromised by certain types of attack. Specify host names in your allowlist only when strictly necessary, and ensure that all components used for name resolution, such as DNS servers, are maintained under your control. You can also implement name resolution locally using the hosts file, to avoid the use of external components.