s9s-cluster

Create, manage, and manipulate clusters.

Usage

s9s cluster {command} {options}

Command

Options

Cluster List

Using the --list and --long command-line options a detailed list of the clusters can be printed. Here is an example of such a list:

$ s9s cluster --list --long
ID STATE TYPE OWNER GROUP NAME COMMENT
1 STARTED replication pipas users mysqlrep All nodes are operational.
Total: 1

The list contains the following fields:

Node List

The list of nodes or hosts is enumerated in a special string using a semicolon as a field separator (e.g. 192.168.1.1;192.168.1.2). The strings in the node list are URLs that can have the following protocols:

Cluster Format

The string controls the format of the printed information about clusters. When this command-line option is used, the specified information will be printed instead of the default columns. The format string uses the % character to mark variable fields and flag characters as they are specified in the standard printf() C library functions. The % specifiers are ended by field name letters to refer to various properties of the clusters.

The %+12I format string for example has the +12 flag characters in it with the standard meaning: the field will be 12 characters wide and the + or - the sign will always be printed with the number. The properties of the message are encoded by letters. The in the%-5I for example the letterI encodes the “cluster ID” field, so the numerical ID of the cluster will be substituted. Standard  \ a notation is also available, \n for example encodes a new-line character.

The s9s-tools support the following fields:

Cluster Tagging

The concept is very similar to the hash-tags used by popular services such as Twitter and Instagram. A cluster can be created with tags, by using --with-tags the option:

$ s9s cluster --create \
        --cluster-name="MyMariaDBGaleraCluster" \
        --cluster-type=galera \
        --provider-version="10.5" \
        --vendor=mariadb  \
        --nodes="mysql://10.10.10.10?hostname_internal=2323" \
        --os-user=vagrant \
        --os-key-file=~/.ssh/id_rsa \
        --with-tags="MDB;DC1;PRODUCTION" \
        --log \
        --print-request

Multiple values are supported using a semi-colon as a delimiter. The tag values are case-sensitive.

An existing cluster can be tagged with --add-tag and --tag options under by specifying the CMON tree path, retrievable using the tree command. To retrieve the “tree path”, one has to list out the CMON object tree and look for column “NAME”, as shown in the following example:

$ s9s tree --list --long
MODE       SIZE OWNER   GROUP   NAME
crwxrwx--- -    system  admins  MariaDB Replication 10.3
srwxrwxrwx -    system  admins  localhost
drwxrwxr-- 1, 0 system  admins  groups
urwxr--r-- -    admin   admins  admin
urwxr--r-- -    nobody  admins  nobody
urwxr--r-- -    system  admins  system

Then, specify the tree path as / + tree name (“MariaDB Replication 10.4”), as shown in the following:

$ s9s tree --add-tag --tag="REPLICATION;PRODUCTION" "/MariaDB Replication 10.4"
Tag is added.

To show all clusters having a certain tag:

$ s9s cluster --list --long --with-tags="PRODUCTION"

Show all cluster that does not have a certain tag:

$ s9s cluster --list --long --without-tags="PRODUCTION"

To filter using multiple tag values:

$ s9s cluster --list --long --with-tags="PRODUCTION;DEV"

Examples

Create a three-node Percona XtraDB Cluster 5.7 cluster, with OS user vagrant:

$ s9s cluster --create \
        --cluster-type=galera \
        --nodes="10.10.10.10;10.10.10.11;10.10.10.12" \
        --vendor=percona \
        --provider-version=8.0 \
        --db-admin-passwd='pa$$word' \
        --os-user=vagrant \
        --os-key-file=/home/vagrant/.ssh/id_rsa \
        --cluster-name='Percona XtraDB Cluster 5.7'

Create a three-node MongoDB Replica Set 5.0 by MongoDB Inc (formerly 10gen) and use the default /root/.ssh/id_rsa as the SSH key, and let the deployment job run in the foreground:

$ s9s cluster --create \
        --cluster-type=mongodb \
        --nodes="10.0.0.148;10.0.0.189;10.0.0.219" \
        --vendor=10gen \
        --provider-version='5.0' \
        --os-user=root \
        --db-admin='admin' \
        --db-admin-passwd='MyS3cr3tPass' \
        --cluster-name='MongoDB ReplicaSet 5.0' \
        --wait

An example for creating a MongoDB Sharded Cluster with 3 mongos, 3 mongo config, and one shard consists of a three-node replica set called ‘replset2’:

$ s9s cluster --create \
        --cluster-type=mongodb \
        --vendor=10gen \
        --provider-version=5.0 \
        --db-admin=adminuser \
        --db-admin-passwd=adminpwd \
        --os-user=root \
        --os-key-file=/root/.ssh/id_rsa \
        --nodes="mongos://192.168.1.11;mongos://192.168.1.12;mongos://192.168.1.12;mongocfg://192.168.1.11;mongocfg://192.168.1.12;mongocfg://192.168.1.13;192.168.1.14?priority=5.0;192.168.1.15?arbiter_only=true;192.168.1.16?priority=2;192.168.1.17?rs=replset2;192.168.1.18?rs=replset2&arbiter_only=yes;192.168.1.19?rs=replset2&slave_delay=3&priority=0"

Import and existing Percona XtraDB Cluster 8.0 and let the deployment job running in the foreground (provided passwordless SSH from ClusterControl node to all database nodes have been set up correctly):

$ s9s cluster --register \
        --cluster-type=galera \
        --nodes="192.168.100.34;192.168.100.35;192.168.100.36" \
        --vendor=percona \
        --provider-version=8.0 \
        --db-admin="root" \
        --db-admin-passwd="root123" \
        --os-user=root \
        --os-key-file=/root/.ssh/id_rsa \
        --cluster-name="My DB Cluster" \
        --wait

Create a MySQL 8.0 replication cluster by Oracle with multiple master and slaves (note the ? sign to identify the node’s role in the --nodes parameter):

$ s9s cluster --create \
        --cluster-type=mysqlreplication \
        --nodes="192.168.1.117?master;192.168.1.113?slave;192.168.1.115?slave;192.168.1.116?master;192.168.1.118?slave;192.168.1.119?slave;" \
        --vendor=oracle \
        --db-admin="root" \
        --db-admin-passwd="root123" \
        --cluster-name=ft_replication_23986 \
        --provider-version=8.0 \
        --log

Create a Redis Cluster v7 with six Redis nodes:

$s9s cluster --create \
        --cluster-type=redis-sharded \
        --redis-port=6379 
        --redis-bus-port=16579 \
        --vendor=redis \
        --provider-version=7 \
        --node-timeout-ms=5000 \
        --replica-validity-factor=10 \
        --db-admin=s9s-user \
        --db-admin-pass=s9ss9s \
        --nodes="redis-primary://rlc2:6479;redis-replica://rlc3:6479;redis-primary://rlc4:6479;redis-replica://rlc5:6479;redis-primary://rlc6;redis-replica://rlc7" \
        --os-user=root \
        --os-key-file=/root/.ssh/id_rsa \
        --cluster-name="My Redis Cluster v7" \
        --log \
        --print-request

Create a Redis Sentinel v6 with one master and two slaves:

$s9s cluster --create \
        --cluster-type=redis \
        --nodes="redis://rlc2;redis://rlc3;redis://rlc4;redis-sentinel://rlc2;redis-sentinel://rlc3;redis-sentinel://rlc4" \
        --os-user=root \
        --os-key-file=/root/.ssh/id_rsa \
        --vendor=redis \
        --provider-version=6  \
        --log \
        --print-request \
        --cluster-name="My Redis Sentinel v6"

Import and existing Redis Cluster and let the deployment job run in the foreground (provided passwordless SSH from ClusterControl node to all database nodes have been set up correctly):

$ s9s cluster --register \
        --cluster-type=redis-sharded \
        --redis-port=6379 \
        --db-admin=s9s-user \
        --db-admin-passwd=s9ss9s \
        --os-user=root \
        --os-key-file=/root/.ssh/id_rsa \
        --nodes="redis-primary://rlc3:6479" \
        --vendor=redis \
        --log \
        --cluster-name="My Redis Cluster" \
        --print-request \
        --wait

Create a PostgreSQL 12 streaming replication cluster with one master and two slaves (note the ? sign to identify the node’s role in the --nodes parameter):

$ s9s cluster --create \
        --cluster-type=postgresql \
        --nodes="192.168.1.81?master;192.168.1.82?slave;192.168.1.83?slave;" \
        --db-admin="postgres" \
        --db-admin-passwd="mySuperStongP455w0rd" \
        --cluster-name=ft_replication_23986 \
        --os-user=vagrant \
        --os-key-file=/home/vagrant/.ssh/id_rsa \
        --provider-version=12 \
        --log

List all clusters with more details:

$ s9s cluster --list --long

Delete a cluster with cluster ID 1:

$ s9s cluster --delete --cluster-id=1

Add a new database node on Cluster ID 1:

$ s9s cluster --add-node \
        --nodes=10.10.10.14 \
        --cluster-id=1 \
        --wait

Delete a database from the cluster name galera_001.

$ s9s cluster \
        --delete-database \
        --print-request \
        --cluster-name="galera_001" \
        --db-name="my_database" \
        --log

Add a data node to an existing MongoDB Sharded Cluster with cluster ID 12 having replica set name ‘replset2’:

$ s9s cluster --add-node \
        --cluster-id=12 \
        --nodes="mongodb://192.168.1.20?rs=replset2"

Create an HAProxy load balancer, 192.168.55.198 on cluster ID 1:

$ s9s cluster --add-node \
        --cluster-id=1 \
        --nodes="haproxy://192.168.55.198" \
        --wait

Remove a database node from cluster ID 1 as a background job:

$ s9s cluster --remove-node \
        --nodes=10.10.10.13 \
        --cluster-id=1

Check if the hosts are part of other cluster and accessible from ClusterControl:

$ s9s cluster --check-hosts \
        --nodes="10.0.0.148;10.0.0.189;10.0.0.219"

Schedule a rolling restart of the cluster 20 minutes from now:

$ s9s cluster --rolling-restart \
        --cluster-id=1 \
        --schedule="$(date -d 'now + 20 min')"

Create a database on the cluster with the given name:

$ s9s cluster --create-database \
        --cluster-id=2 \
        --db-name=my_shopping_db

Create a database account on the cluster and also create a new database to be used by the new user. Grant all access to the new database for the new user:

$ s9s cluster --create-account \
        --cluster-id=1 \
        --account="john:[email protected]" \
        --with-database

Create a cluster and tag it using the –with-tags option:

$ s9s cluster --create \
        --cluster-name="TAGGED_MDB" \
        --cluster-type=galera \
        --provider-version="10.4" \
        --vendor=mariadb \
        --nodes="mysql://10.10.10.14:3306" \
        --os-user=vagrant \
        --with-tags="MDB;DC1;PRODUCTION" \
        --log

List all databases for every cluster:

$ s9s cluster --list-databases --long
SIZE      #TBL #ROWS   OWNER  GROUP  CLUSTER              DATABASE
        0    0       - system admins MySQL Rep Oracle 8.0 sys
381681664    7  690984 system admins MySQL Rep Oracle 8.0 db5
381681664    7  690984 system admins MySQL Rep Oracle 8.0 db4
599785472   11 1083295 system admins MySQL Rep Oracle 8.0 db3
272629760    5  493560 system admins MySQL Rep Oracle 8.0 db2
381681664    7  690984 system admins MySQL Rep Oracle 8.0 db1
  7340032    2       0 system admins PostgreSQL 13        postgres
  7340032    0       0 system admins PostgreSQL 13        template1
  7340032    0       0 system admins PostgreSQL 13        template0
  7340032    0       0 system admins PostgreSQL 13        db1
  7340032    0       0 system admins PostgreSQL 13        db2
Total: 11 databases, 2059403264, 39 tables.

Show all clusters having a certain tag (an existing cluster can be tagged using s9s tree), with multiple tags separated by a semi-colon:

$ s9s cluster --list \
        --long \
        --with-tags="PRODUCTION;big_cluster"

List out CMON configuration options for cluster ID 2:

$ s9s cluster --list-config --cluster-id=2

Change a CMON configuration option called diskspace_warning for cluster ID 2 (the configuration change will be applied on CMON runtime and configuration file, /etc/cmon.d/cmon_2.cnf):

$ s9s cluster --change-config \
        --cluster-id=2 \
        --opt-name=diskspace_warning \
        --opt-value=70

Upgrade cluster packages while keeping the major version for cluster ID 1.

$ s9s cluster \
        --upgrade-cluster \
        --cluster-id=1 \
        --nodes="192.168.0.84:5433;192.168.0.85" \
        --wait

Upgrade cluster packages to a newer major version for cluster ID 1.

$ s9s cluster \
        --upgrade-cluster \
        --upgrade-to-version=12 \
        --cluster-id=1\
        -- log

Upgrade cluster packages to a newer major version for cluster ID 1 with a specific upgrade method.

$ s9s cluster \
        --upgrade-cluster \
        --upgrade-to-version=12 \
        --upgrade-method=link \
        --cluster-id=1\
        -- log