Migrating from older Terracotta versions to 10.7

A major feature of the 10.7 release is dynamic configuration of the Terracotta cluster, which changes cluster startup and configuration mechanisms. This documents briefly lists the new concepts, tooling information, and the steps to be followed to migrate from an earlier 10.x to a 10.7 cluster.

Before proceeding with this document, please make sure that you have familiarized yourself with the material presented in Configuration Terms and Concepts.

start-tc-server.(bat|sh) does not support a tc-config XML file anymore. Several new options have been added to this script. More information can be found in the startup script section.

Cluster configuration can no more be specified using tc-config XML files. The old tc-configs can be migrated to the new configuration format using config converter tool.

The cluster tool configure command has been removed in favor of the config tool activate command. The cluster tool reconfigure command has been removed in favor of the config tool set command.

The config converter tool can be used to convert from tc-config XML files used with Terracotta versions up to 10.5 to the new configuration format. The tool can be located under tools/upgrade/bin in the product installation directory, and has the following usage:

> config-converter.(bat|sh) convert -tc-config <tc-config>,<tc-config>... [ -stripe-names <foo>,<bar>,<baz>... ]
( -format directory [-license-file <license-file>] -new-cluster-name <new-cluster-name> |
-format properties [-new-cluster-name <new-cluster-name>])
[-destination <destination-dir>] [-force]

Warning:
Do not forget to assign stripe names in the same order of the xml config files, otherwise random default names will be generated for you.

When the output format is config directory (i.e. -format directory, or no -format specification), a license file can be supplied.

Note:
In a fresh install of Terracotta using the Software AG installer, the license file can be found under the Terracotta installation root.

This way, the generated config directory will be ready-for-use by Terracotta clients. This is the recommended output format. Note that there is no change in the license file, or the licensing policies. Thus, existing Terracotta licenses will continue to work with 10.7 until their expiration.

When the output format is config properties (i.e. -format properties), the generated config file contains information from all the tc-config XML files, and can also be used to start up the nodes. However, an additional cluster activation step will be required after the migrated cluster is started using this config file.

If you want to use old data with 10.7 server, you need to run the create permanent entities tool. One host-port per stripe needs to be specified so that the tool can connect to all the stripes.

> create-permanent-entities.(bat|sh) -connect-to <hostname[:port]>,...

The start-tc-server script does not support tc-config XML files anymore. Instead, it supports several options which let you specify a node's configuration via the command itself.

See the section Starting and Stopping the Terracotta Server for details.

1. Shut down all Terracotta clients and ensure no critical operations (like backup) are running on the cluster. Note down the hosts the nodes are running on.

2. Use the cluster tool shutdown command to shut down the Terracotta cluster.

3. Use the config converter tool to convert tc-config.xml files to config directory format.

4. Copy the config directories generated from the step above to the hosts from the first step.

5. Start the nodes using the startup script with option -config-dir, supplying the config directory path.

6. Use the create-permanent-entity-tool if you want to use the old data with the 10.7 server. Ensure that you run this script before connecting any clients.

7. Replace the old client jars with 10.7 jars in the client classpath.