Configure logical clusters in the ADCM interface

Elena Dvoryadkina

To organize distributed storage and replication of data, as well as to allow executing distributed queries (ON CLUSTER) on multiple ADQM hosts, it is necessary to combine hosts into a logical cluster. You can configure a logical cluster within an ADQM cluster via the ADCM interface — use parameters in the Cluster configuration section on the configuration page of the ADQMDB service.

Auto generate logical cluster on ADQM installation

Before you install an ADQM cluster, specify the Replication factor parameter value to automatically group hosts into a logical cluster.

Set the replication factor
Set the replication factor

This will generate the cluster topology as follows:

  • All ADQM hosts are split into groups — shards.

  • Each host in a shard is a replica. The number of replicas in a shard corresponds to the value of the Replication factor parameter.

  • If the total number of hosts is not exactly divisible by the specified replication factor, then the number of replicas in the last shard is determined as the remainder of the division.

After the ADQM cluster is installed, the default_cluster logical cluster will be added to the remote_servers section of the config.xml configuration file. This topology is created once and does not change when the cluster is further reconfigured.

For example, if an ADQM cluster contains 4 hosts (host-1, host-2, host-3, host-4) and the Replication factor parameter is set to 2, a logical cluster generated based on the specified replication factor will include two shards with two replica hosts in each one:

<remote_servers>
    <default_cluster>
        <shard>
            <internal_replication>true</internal_replication>
            <weight>1</weight>
            <replica>
                <host>host-1</host>
                <port>9000</port>
            </replica>
            <replica>
                <host>host-2</host>
                <port>9000</port>
            </replica>
        </shard>
        <shard>
            <internal_replication>true</internal_replication>
            <weight>1</weight>
            <replica>
                <host>host-3</host>
                <port>9000</port>
            </replica>
            <replica>
                <host>host-4</host>
                <port>9000</port>
            </replica>
        </shard>
    </default_cluster>
</remote_servers>

Information on default_cluster will be added to the system.clusters system table:

SELECT cluster, shard_num, replica_num, host_name FROM system.clusters;
┌─cluster─────────┬─shard_num─┬─replica_num─┬─host_name─┐
│ default_cluster │         1 │           1 │ host-1    │
│ default_cluster │         1 │           2 │ host-2    │
│ default_cluster │         2 │           1 │ host-3    │
│ default_cluster │         2 │           2 │ host-4    │
└─────────────────┴───────────┴─────────────┴───────────┘

When creating a logical cluster, the macros section with shard and replica identifiers for the host is also added to the config.xml configuration file on each host. For example, macros for host-4 are:

<macros>
    <replica>2</replica>
    <shard>2</shard>
</macros>

Macros are used to automatically substitute host-specific shard and replica identifiers when creating replicated tables on a cluster (for an example, see the Typical cluster article).

Add more logical clusters

ADQM hosts can be combined into multiple logical clusters with different topologies (one host can participate in several logical clusters).

To configure a logical cluster, use the Cluster Configuration parameter — add necessary elements using the icon plus one dark plus one light:

  1. Add a new cluster and specify its name.

  2. Specify how many shards the cluster should contain — add items to the shards list.

    For each shard, specify the weight and internal_replication parameters (see the Sharding article for more information on these parameters), and add hosts to be replicas within the shard to the replicas list.

    Configure logical cluster
    Configure logical cluster

  3. Click Save and execute the Reconfig and restart action for the ADQMDB service to save the settings.

    The cluster definition will appear in the remote_servers section of the config.xml file:

    <remote_servers>
    <!-- default_cluster configuration is here -->

    <cluster_2x1>
        <shard>
            <internal_replication>true</internal_replication>
            <weight>1</weight>
            <replica>
                <host>host-1</host>
                <port>9000</port>
            </replica>
        </shard>
        <shard>
            <internal_replication>true</internal_replication>
            <weight>1</weight>
            <replica>
                <host>host-2</host>
                <port>9000</port>
            </replica>
        </shard>
    </cluster_2x1>
</remote_servers>

    Information on the cluster will be also added to the system.clusters table:

    SELECT cluster, shard_num, replica_num, host_name FROM system.clusters;
    ┌─cluster─────────┬─shard_num─┬─replica_num─┬─host_name─┐
│ cluster_2x1     │         1 │           1 │ host-1    │
│ cluster_2x1     │         2 │           1 │ host-2    │
│ default_cluster │         1 │           1 │ host-1    │
│ default_cluster │         1 │           2 │ host-2    │
│ default_cluster │         2 │           1 │ host-3    │
│ default_cluster │         2 │           2 │ host-4    │
└─────────────────┴───────────┴─────────────┴───────────┘

Macros for all clusters except default_cluster are prefixed with <cluster_name>_. For example, for the cluster_2x1 cluster configured above, the following macros will be added to the config.xml configuration file on host-1:

<macros>
    <!-- default_cluster macros are here -->

    <cluster_2x1_replica>1</cluster_2x1_replica>
    <cluster_2x1_shard>1</cluster_2x1_shard>
</macros>
Found a mistake? Seleсt text and press Ctrl+Enter to report it