Documentation Home
MySQL Shell 8.4
Download this Manual
PDF (US Ltr) - 2.2Mb
PDF (A4) - 2.3Mb

MySQL Shell 8.4  /  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.


If you are using the XCOM communication stack, 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.

  • 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.

  • 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”.

Securing Communications Between Cluster Members

It is possible to configure clusters and replica clusters to use SSL to encrypt replication channels, and enable replicas to verify host identity and use SSL certificates for authentication.

When creating a cluster with dba.createCluster() you can define the authentication type used for the internal replication accounts with the memberAuthType option. This option takes one of the following values:

  • PASSWORD: Account authenticates with password only.

  • CERT_ISSUER: Account authenticates with a client certificate, which must match the expected issuer. This value is equivalent to VERIFY_CA.

  • CERT_SUBJECT: Account authenticates with a client certificate, which must match the expected issuer and subject. This value is equivalent to VERIFY_IDENTITY.

  • CERT_ISSUER_PASSWORD: Account authenticates with a combination of PASSWORD and CERT_ISSUER values.

  • CERT_SUBJECT_PASSWORD: Account authenticates with a combination of PASSWORD and CERT_SUBJECT values.


ClusterSets inherit the memberAuthType defined on the primary cluster. All replica clusters in a ClusterSet will also use the memberAuthType defined on the primary.

SSL certificates are defined using the following options:

  • CERT_ISSUER: Defines the certificate issuer required by all replication accounts in the topology if memberAuthType contains CERT_ISSUER or CERT_SUBJECT.

  • CERT_SUBJECT: Defines the certificate subject of the instance. Required if memberAuthType contains CERT_SUBJECT.


It is not possible to use adoptFromGR=true with any option except memberAuthType=password.

The following example creates a cluster, cluster1 which sets client SSL connections and connections opened by Group Replication from one server to another to VERIFY_IDENTITY, and sets the authentication of the internal replication accounts to require a client certificate:

        cluster = dba.createCluster("cluster1", { "memberSslMode": "VERIFY_IDENTITY", "memberAuthType":"CERT_SUBJECT", 
        "certIssuer":"/CN=MyCertAuthority", "certSubject": "/CN=mysql-1.local"});

The following example shows how to add an instance to a cluster using "memberAuthType":"CERT_SUBJECT":

        cluster.addInstance("mysql-2.local", {"certSubject": "/CN=mysql-2.local"});

For more information on replication and encrypted connections, see Setting Up Replication to Use Encrypted Connections.

Creating an Allowlist of Servers


This applies only to the XCOM communication stack.

createCluster(), addInstance(), and rejoinInstance() methods enable you to optionally specify a list of approved servers, 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, 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 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.