Documentation Home
MySQL Shell 8.0
Related Documentation Download this Manual
PDF (US Ltr) - 2.1Mb
PDF (A4) - 2.1Mb

MySQL Shell 8.0  /  MySQL InnoDB Cluster  /  Securing InnoDB Cluster

7.6 Securing InnoDB Cluster

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. For example, when using the commercial version of MySQL, SSL is enabled by default and you need to configure the ipAllowlist option for all instances. See Creating an Allowlist of Servers.

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 following modes are supported:

  • DISABLED: Ensure SSL encryption is disabled for the seed instance in the cluster.

  • AUTO: Automatically enable SSL encryption if the server instance supports it, or disable encryption if the server does not support it.

  • REQUIRED: Enable SSL encryption for the seed instance in the cluster. If it cannot be enabled, an error is raised.

  • (added in version 8.0.24) VERIFY_CA: Like REQUIRED, but additionally verify the server Certificate Authority (CA) certificate against the configured CA certificates. The connection attempt fails if no valid matching CA certificates are found.

  • (added in version 8.0.24) VERIFY_IDENTITY: Like VERIFY_CA, but additionally perform host name identity verification by checking the host name the client uses for connecting to the server against the identity in the certificate that the server sends to the client.

For example, to set the cluster to use REQUIRED, issue:

mysql-js> var myCluster = dba.createCluster({memberSslMode: 'REQUIRED'})

If you choose to use the VERIFY_CA or VERIFY_IDENTITY mode, on each cluster instance you must manually supply the CA certificates using the ssl_ca and/or ssl_capath option. For more information on these modes, see --ssl-mode=mode.

When you use the Cluster.addInstance() and Cluster.rejoinInstance() operations, SSL encryption on the instance is enabled or disabled based on the setting used for the cluster. Use the memberSslMode option with either of these operations to set the instance to use a different mode of encryption.

When using dba.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. See Section 6.8.1, “Deploying Sandbox Instances”.

Creating an Allowlist of Servers

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.

You can also define an allowList on a running cluster, if it uses the XCOM communication stack, using Cluster.setOption() to specify the allowList for all members of the cluster, and Cluster.setInstanceOption() to specify the allowList for an individual member. See Section 7.5.1, “Setting Options for InnoDB 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: ","})

This configures the instance to only accept connections from servers at addresses and 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.