10.3 Creating an InnoDB ReplicaSet

Once you have configured your instances, create an InnoDB ReplicaSet by completing the following steps:

1. Connect to an instance and use dba.createReplicaSet() to create a managed ReplicaSet that uses MySQL asynchronous replication, rather than MySQL Group Replication used by InnoDB Cluster. The MySQL instance, which MySQL Shell is connected to, is used as the initial primary of the ReplicaSet.

   The dba.createReplicaSet() operation performs several checks to ensure that the instance state and configuration are compatible with a managed ReplicaSet, and if so, a metadata schema is initialized on the instance.

   If the ReplicaSet is created successfully, a ReplicaSet object is returned. Therefore, it is best practice to assign the returned ReplicaSet to a variable. This enables you to work with the ReplicaSet, for example by calling the <ReplicaSet>status() operation. To create a ReplicaSet named example on instance rs-1 and assign it to the rs variable, issue:

   mysql-js> \connect root@rs-1:3306
   ...
   mysql-js> var rs = dba.createReplicaSet("example")
   A new replicaset with instance 'rs-1:3306' will be created.
   
   * Checking MySQL instance at rs-1:3306
   
   This instance reports its own address as rs-1:3306
   rs-1:3306: Instance configuration is suitable.
   
   * Updating metadata...
   
   ReplicaSet object successfully created for rs-1:3306.
   Use rs.addInstance() to add more asynchronously replicated instances to this replicaset
   and rs.status() to check its status.

   Note

   The ReplicaSet'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.

2. Use the returned ReplicaSet object to verify that the operation was successful. For example, this provides the ReplicaSet.status() operation, which displays information about the ReplicaSet. The returned ReplicaSet is already assigned to the variable rs, so issue:

   mysql-js> rs.status()
   {
       "replicaSet": {
           "name": "example",
           "primary": "rs-1:3306",
           "status": "AVAILABLE",
           "statusText": "All instances available.",
           "topology": {
               "rs-1:3306": {
                   "address": "rs-1:3306",
                   "instanceRole": "PRIMARY",
                   "mode": "R/W",
                   "status": "ONLINE"
               }
           },
           "type": "ASYNC"
       }
   }

   This output shows that the ReplicaSet named example has been created, and that the primary is rs-1. Currently, there is only one instance, and the next task is to add more instances to the ReplicaSet.

ReplicaSet Encryption and Authentication

Replicas can verify the identity of the source and use client SSL certificates for authentication. The following options were added to dba.createReplicaSet:

• memberAuthType: defines the authentication type used for the internal replication accounts. 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.

• certIssuer: Defines the certificate issuer required for authentication if memberAuthType contains CERT_ISSUER or CERT_SUBJECT.

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

• replicationSslMode: Defines the authentication type of the replication channels in the replicaSet. This option takes one of the following values:

  • DISABLED: TLS encryption is disabled for the replication channel.

  • REQUIRED: TLS encryption is enabled for the replication channel.

  • VERIFY_CA: The same as REQUIRED, but additionally verifies the peer server TLS certificate against the configured Certificate Authority (CA) certificates.

  • VERIFY_IDENTITY: The same as VERIFY_CA, but additionally verifies that the peer server certificate matches the host to which the connection is attempted.

  • AUTO: TLS encryption is enabled if supported by the instance. Disabled if the instance does not support TLS.

For example:

mysql-js> myreplicaset = dba.createReplicaSet("replicaSet1", 
  { "replicationSslMode": "VERIFY_IDENTITY", "memberAuthType":"CERT_SUBJECT", 
  "certIssuer":"/CN=MyCertAuthority", "certSubject": "/CN=mysql-5.local"});

Note

All new replication channels are created with SSL enabled.

InnoDB ReplicaSet replicationAllowedHost

When creating an InnoDB ReplicaSet, if you have security requirements that want all accounts created automatically by AdminAPI to have strict authentication requirements, you can set a value for the replicationAllowedHost configuration option of the ReplicaSet. The replicationAllowedHost MySQL Shell option allows you to set internally managed replication accounts for a ReplicaSet to a strict subnet based filter instead of the default wildcard value of %.The replicationAllowedHost option can take a string value. For example, to set the replicationAllowedHost to 192.0.2.0/24, issue:

mysql-js> var rs = dba.createReplicaSet('example', {replicationAllowedHost:'192.0.2.0/24'})
        A new replicaset with instance 'rs-1:3306' will be created.

* Checking MySQL instance at rs-1:3306

This instance reports its own address as rs-1:3306
rs-1:3306: Instance configuration is suitable.

* Updating metadata...

ReplicaSet object successfully created for rs-1:3306.
Use rs.addInstance() to add more asynchronously replicated instances to this replicaset 
and rs.status() to check its status.

An InnoDB ReplicaSet can be modified after creation to set the variable replicationAllowedHost through the setOption configuration option, by issuing:

mysql-js> rs.setOption('replicationAllowedHost', '192.0.2.0/24')