The Cluster Tool

The cluster tool is a command line utility that allows you as an administrator of the Terracotta Server Array to perform a variety of tasks in the area of cluster management. Examples are:

Configure a named cluster using the Terracotta configuration files for one or more stripes.

The script to run the cluster tool is located in tools/cluster-tool/bin under the installation directory. On Windows platforms, the script is cluster-tool.bat, and on Linux platforms it is cluster-tool.sh.

The cluster tool offers online help. See the section The "help" Command below for details. All parameters of the cluster tool are mandatory unless explicitly indicated otherwise.

The typical usage flow when setting up and using a cluster is:

1. Create Terracotta configuration files for each stripe in the deployment. See the section The Terracotta Configuration File for details.

2. Start up the servers in each stripe. See the section Starting and Stopping the Terracotta Server for details.

4. Configure the cluster using the configure command of the cluster tool. This lets the servers know about the configuration of the entire cluster. The cluster configuration is used by scripts or features that perform cluster-level operations. See the section The "configure" Command below for details.

5. During cluster operation, you may wish to check the current status of the cluster. You can do this using the dump command of the cluster tool. See the section The "dump" Command below for details.

6. If you wish to stop all servers in the cluster, use the stop command of the cluster tool. See the section The "stop" Command below for details.

The configure command creates a cluster from the provided Terracotta configuration files and associates it with the given cluster name.

The cluster association gets saved on all the servers of the configured cluster, so that other commands (dump, stop) can use this information later.

The command also ensures that the configurations provided in all of the configuration files are consistent across all the stripes, otherwise the command fails.

The following items are validated within the plugins section of the configuration files:

1. config: the generic configuration required by the server. Currently these configuration items are validated:

offheap-resources: resource names and corresponding size should match across configuration files.

data-directories: directory IDs should match across configuration files.

2. service: a service used by the server and corresponding configuration

frs-platform-persistence: If this is present in one configuration file it should be present in all configuration files, as it ensures platform-persistence is enabled across stripes.

cluster-tool.sh configure -n <cluster-name> <tc-config> [<tc-config> ...]

cluster-name: The name that you want to assign to the newly-created cluster.

tc-config: The name of a Terracotta configuration file that describes a stripe to be added to the cluster. You can supply several tc-config files, where each such file describes a different stripe.

Note:

The command only configures the cluster once. Currently the reconfiguration of a running cluster is not supported.

cluster-tool.sh configure -n cluster1 ~/tc-config1.xml
Configure called: cluster1, [/home/username/tc-config1.xml]
Connection successfully established to server at 127.0.0.1:9510
Command completed successfully

cluster-tool.sh configure -n cluster1 ~/tc-config1.xml ~/tc-config2.xml
Configure called: cluster1, [/home/tc-config1.xml, /home/tc-config2.xml]
Error Occurred: Mismatched off heap: [
[primary-server-resource: 64M, secondary-server-resource: 64M],
[primary-server-resource: 32M, secondary-server-resource: 64M]]

The dump command dumps the state of the entire cluster (configured with the provided cluster name) in the Terracotta logs of the respective servers.

cluster-tool.sh dump -n <cluster-name> <host>:<port>

<host>:<port> : The host and port of one of the active servers in the configured cluster. This is required so that we can identify all the servers in the configured cluster by connecting to one of the active servers.

Note:

If there is a problem accessing the given server (for example, a slow network connection or an unknown server), the command times out after 60 seconds.

cluster-tool.sh dump -n cluster1 localhost:9510
Dump called: cluster1, localhost, 9510
Connection successfully established to server at 127.0.0.1:9510
Dump State Cluster command was executed with result.
Command successfully executed : DUMP_STATE_CLUSTER
Command completed successfully

The stop command forcefully stops all the servers in the cluster that are configured with the provided cluster name.

cluster-tool.sh stop -n <cluster-name> <host>:<port>

<host>:<port> : The host and port of one of the active servers in the configured cluster. It is required so that we can identify all the servers in the configured cluster by connecting to one of the active servers.

Note:

If there is a problem accessing the given server (for example, a slow network connection or an unknown server), the command times out after 60 seconds.

cluster-tool.sh stop -n cluster1 localhost:9510
Stop called: cluster1, localhost, 9510
Connection successfully established to server at 127.0.0.1:9510
Stop Cluster command was executed with result.
Command successfully executed : STOPS_CLUSTER
Command completed successfully

The Help command displays the available commands accepted by the cluster tool, and provides a short description of each command.

cluster-tool.sh help

cluster-tool.sh help

Usage: cluster-tool [OPTIONS] <COMMAND>

OPTIONS:
-v - Enable verbose mode
<COMMAND>:
help - Prints this help
configure - Configures/Reconfigure the cluster
stop - Stop the cluster nodes
dump - Dump the cluster state