Getting started with Tarantool Cluster Manager

Defining the cluster’s connection settings in TCM

A freshly installed TCM has a predefined cluster named Default cluster. It doesn’t have any configuration or topology out of the box. Its initial properties include the etcd and Tarantool connection parameters. Check these properties to find out where TCM sends the cluster configuration that you write.

To view the Default cluster’s properties:

1. Go to Clusters and click Edit in the Actions menu opposite the cluster name.

   

2. Click Next on the General tab.

   

3. Find the connection properties of the configuration storage that the cluster uses. By default, it’s an etcd running on port 2379 (default etcd port) on the same host. The key prefix used for the cluster configuration is /default. Click Next.

   

4. Check the Tarantool user that TCM uses to connect to the cluster instances. It’s guest by default.

   

Configuring a cluster in TCM

TCM provides a web-based editor for writing cluster configurations. It is connected to the configuration storage (etcd in this case): all changes you make in the browser are sent to etcd in one click.

To write the cluster configuration and upload it to the etcd storage:

1. Go to Configuration.

2. Click + and provide an arbitrary name for the configuration file, for example, all.

3. Paste the following YAML configuration into the editor:

   credentials:
     users:
       guest:
         roles: [super]
   groups:
     group-001:
       replicasets:
         replicaset-001:
           replication:
             failover: manual
           leader: instance-001
           instances:
             instance-001:
               iproto:
                 listen:
                 - uri: '127.0.0.1:3301'
                 advertise:
                   client: '127.0.0.1:3301'
             instance-002:
               iproto:
                 listen:
                 - uri: '127.0.0.1:3302'
                 advertise:
                   client: '127.0.0.1:3302'
             instance-003:
               iproto:
                 listen:
                 - uri: '127.0.0.1:3303'
                 advertise:
                   client: '127.0.0.1:3303'
   

   This configuration sets up a cluster of three nodes in one replica set: one leader and two followers.

4. Click Apply to send the configuration to etcd.

   

When the cluster configuration is saved, you can see the cluster topology on the Stateboard page:

However, the cluster instances are offline because they aren’t deployed yet.

Deploying the cluster locally

To deploy a local cluster based on the configuration from etcd:

1. Go to the system terminal you used when setting up Tarantool.

2. Create a new tt environment in a directory of your choice:

   $ mkdir cluster-env
   $ cd cluster-env/
   $ tt init
   

3. Inside the instances.enabled directory of the created tt environment, create the cluster directory.

   $ mkdir instances.enabled/cluster
   $ cd instances.enabled/cluster/
   

4. Inside instances.enabled/cluster, create the instances.yml and config.yaml files:

   • instances.yml specifies instances to run in the current environment. In this example, there are three instances:

     instance-001:
     instance-002:
     instance-003:
     

   • config.yaml instructs tt to load the cluster configuration from etcd. The specified etcd location matches the configuration storage of the Default cluster in TCM:

     config:
       etcd:
         endpoints:
         - http://localhost:2379
         prefix: /default
     

5. Start the cluster from the tt environment root (the cluster-env directory):

   $ tt start cluster
   

   To check how the cluster started, run tt status. This output should look like this:

   $ tt status cluster
   INSTANCE               STATUS      PID
   cluster:instance-001     RUNNING     2058
   cluster:instance-002     RUNNING     2059
   cluster:instance-003     RUNNING     2060
   

Checking cluster state

To check the cluster state in TCM, go to Stateboard. Here you see the overview of the cluster topology, health, memory consumption, and other information.

Connecting to an instance

To view detailed information about an instance, click its name in the instances list on the Stateboard page.

To connect to the instance interactively and execute code on it, go to the Terminal tab.

Creating a space

Go to the terminal of instance-001 (the leader instance) and run the following code to create a formatted space with a primary index in the cluster:

box.schema.space.create('bands')
box.space.bands:format({
    { name = 'id', type = 'unsigned' },
    { name = 'band_name', type = 'string' },
    { name = 'year', type = 'unsigned' }
})
box.space.bands:create_index('primary', { type = "tree", parts = { 'id' } })

Writing data

Since instance-001 is a read-write instance (its box.info.ro is false), the write requests must be executed on it. Run the following code in the instance-001 terminal to write tuples in the space:

box.space.bands:insert { 1, 'Roxette', 1986 }
box.space.bands:insert { 2, 'Scorpions', 1965 }
box.space.bands:insert { 3, 'Ace of Base', 1987 }

Reading data

Check the space’s tuples by running a read request on instance-001:

box.space.bands:select { 3 }

This is how it looks in TCM:

Checking replication

To check that the data is replicated across instances, run the read request on any other instance – instance-002 or instance-003. The result is the same as on instance-001.

Viewing data in TCM

TCM web UI includes a tool for viewing data stored in the cluster. To view the space tuples in TCM:

1. Click an instance name on the Stateboard page.

2. Open the Actions menu in the top-right corner and click Explorer.

   

   This opens the page that lists user-created spaces on the instance.

   

3. Click View in the Actions menu of the space you want to see. The page shows all the tuples added previously.