Managing ClickHouse® Keeper hosts

Written by

Yandex Cloud

Updated at July 6, 2026

View in Markdown

Getting a list of cluster hosts
Creating a ClickHouse® Keeper host
Changing ClickHouse® Keeper settings
Restarting a host
Converting non-replicated tables to replicated ones
Deleting a ClickHouse® Keeper host

When managing ClickHouse® Keeper hosts, you can do the following:

For more information about ClickHouse® Keeper hosts, see ClickHouse® Keeper.

Getting a list of cluster hosts

Management console

CLI

REST API

gRPC API

In the management console, select the folder containing the cluster.
Navigate to Managed Service for ClickHouse.
Click the name of your cluster and select the Hosts tab.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder used by default is the one specified when creating the CLI profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also specify a different folder for any command using --folder-name or --folder-id. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

To get a list of cluster hosts, run this command:

yc managed-clickhouse host list \
   --cluster-name=<cluster_name>

+----------------------------+--------------+---------+--------+---------------+
|            NAME            |  CLUSTER ID  |  ROLE   | HEALTH |    ZONE ID    |
+----------------------------+--------------+---------+--------+---------------+
| rc1b...mdb.yandexcloud.net | c9qp71dk1... | MASTER  | ALIVE  | ru-central1-b |
| rc1a...mdb.yandexcloud.net | c9qp71dk1... | REPLICA | ALIVE  | ru-central1-a |
+----------------------------+--------------+---------+--------+---------------+

You can get the cluster name with the list of clusters in the folder.

Get an IAM token for API authentication and put it into an environment variable:
```
export IAM_TOKEN="<IAM_token>"
```

Call the Cluster.ListHosts method, e.g., via the following cURL request:

curl \
    --request GET \
    --header "Authorization: Bearer $IAM_TOKEN" \
    --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/clusters/<cluster_ID>/hosts'

You can get the cluster ID with the list of clusters in the folder.

View the server response to make sure your request was successful.

Get an IAM token for API authentication and put it into an environment variable:
```
export IAM_TOKEN="<IAM_token>"
```
Clone the cloudapi repository:
```
cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
```
Below, we assume that the repository contents reside in the ~/cloudapi/ directory.

Call the ClusterService.ListHosts method, e.g., via the following gRPCurl request:

grpcurl \
    -format json \
    -import-path ~/cloudapi/ \
    -import-path ~/cloudapi/third_party/googleapis/ \
    -proto ~/cloudapi/yandex/cloud/mdb/clickhouse/v1/cluster_service.proto \
    -rpc-header "Authorization: Bearer $IAM_TOKEN" \
    -d '{
            "cluster_id": "<cluster_ID>"
        }' \
    mdb.api.cloud.yandex.net:443 \
    yandex.cloud.mdb.clickhouse.v1.ClusterService.ListHosts

You can get the cluster ID with the list of clusters in the folder.

View the server response to make sure your request was successful.

Creating a ClickHouse® Keeper host

Management console

In the management console, navigate to the folder dashboard and select Managed Service for ClickHouse.
Click the cluster name and navigate to the Hosts tab.
Click Create ClickHouse Keeper host in the top-right corner of the page.
Select the availability zone and a subnet inside it.
Click Save.

Changing ClickHouse® Keeper settings

Management console

In the management console, navigate to the folder dashboard and select Managed Service for ClickHouse.
Select the cluster and click Edit in the top panel.
Under Clickhouse Keeper host class, select the platform, VM type, and required ClickHouse® Keeper host class.
Under ClickHouse Keeper storage size, specify the disk type and storage size, and set up automatic storage size increase.
Click Save changes.

Restarting a host

You may need to restart hosts to promptly address such issues as:

Resource overutilization
Memory leak
Request deadlock
Unresponsive ClickHouse® operations and internal processes

Management console

CLI

REST API

gRPC API

To restart a single host:

In the management console, select the folder containing the cluster.
Navigate to Managed Service for ClickHouse.
Click the cluster name and navigate to the Hosts tab.
In the host row, click and select Restart.
In the window that opens, enable I am restarting host and click Confirm.

To restart multiple hosts in one go:

In the management console, select the folder containing the cluster.
Navigate to Managed Service for ClickHouse.
Click the cluster name and navigate to the Hosts tab.
Select the hosts you want to restart and click Restart at the bottom of the screen.
In the window that opens, click Confirm.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

To restart one or multiple hosts, run the command below providing their names. Use the space character as a separator.

Here is the command to restart a single host:

yc managed-clickhouse host restart <host_name> \
   --cluster-name=<cluster_name>

You can get the host name with the list of cluster hosts, and the cluster name, with the list of clusters in the folder.

Get an IAM token for API authentication and put it into an environment variable:
```
export IAM_TOKEN="<IAM_token>"
```

Call the Cluster.RestartHosts method, e.g., via the following cURL request:

curl \
    --request POST \
    --header "Authorization: Bearer $IAM_TOKEN" \
    --header "Content-Type: application/json" \
    --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/clusters/<cluster_ID>/hosts:restartHosts' \
    --data '{
              "hostNames": [
                <list_of_host_names>
              ]
            }'

Where hostNames is an array of strings. Each string is the name of the host to restart. You can get the host names with the list of hosts in the cluster.

You can get the cluster ID with the list of clusters in the folder.

View the server response to make sure your request was successful.

Get an IAM token for API authentication and put it into an environment variable:
```
export IAM_TOKEN="<IAM_token>"
```
Clone the cloudapi repository:
```
cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
```
Below, we assume that the repository contents reside in the ~/cloudapi/ directory.

Call the ClusterService.RestartHosts method, e.g., via the following gRPCurl request:

grpcurl \
    -format json \
    -import-path ~/cloudapi/ \
    -import-path ~/cloudapi/third_party/googleapis/ \
    -proto ~/cloudapi/yandex/cloud/mdb/clickhouse/v1/cluster_service.proto \
    -rpc-header "Authorization: Bearer $IAM_TOKEN" \
    -d '{
            "cluster_id": "<cluster_ID>",
            "host_names": [
              <list_of_host_names>
            ]
        }' \
    mdb.api.cloud.yandex.net:443 \
    yandex.cloud.mdb.clickhouse.v1.ClusterService.RestartHosts

Where host_names is an array of strings. Each string is the name of the host to restart. You can get the host names with the list of hosts in the cluster.

You can get the cluster ID with the list of clusters in the folder.

View the server response to make sure your request was successful.

Converting non-replicated tables to replicated ones

You can convert MergeTree-based non-replicated tables to ReplicatedMergeTree-based replicated ones:

Automatically, when the coordination service gets activated.
Using SQL, after the coordination service gets activated.

For more on table engines, see this ClickHouse® guide.

Automatically

SQL

To automatically convert non-replicated tables to replicated ones, enable table conversion when activating the coordination service.

To convert a non-replicated table to a replicated one:

Make the table unusable:
```
DETACH TABLE <table_name>;
```

Convert the table to a replicated one:

ATTACH TABLE <table_name> AS REPLICATED;

Restore and synchronize the state of your table replica in ClickHouse® Keeper:
```
SYSTEM RESTORE REPLICA <table_name>;
```

Deleting a ClickHouse® Keeper host

Warning

You can delete only one ClickHouse® Keeper host at a time. However, there must be at least three ClickHouse® Keeper hosts left in the cluster at all times.

Management console

CLI

REST API

gRPC API

Navigate to the folder dashboard and select Managed Service for ClickHouse.
Click the cluster name and navigate to the Hosts tab.
In the host row, click and select Delete.
Confirm the deletion.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

To delete a ClickHouse® Keeper host:

See the description of the CLI command for deleting a host:
```
yc managed-clickhouse hosts delete --help
```
Delete the host by running this command:
```
yc managed-clickhouse hosts delete <host_name> \ 
  --cluster-id=<cluster_ID>
```
You can get the host name with the list of hosts in the cluster.

You can get the cluster ID with the list of clusters in the folder.

Get an IAM token for API authentication and put it into an environment variable:
```
export IAM_TOKEN="<IAM_token>"
```

Call the Cluster.DeleteHosts method, e.g., via the following cURL request:

curl \
  --request POST \
  --header "Authorization: Bearer $IAM_TOKEN" \
  --header "Content-Type: application/json" \
  --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/clusters/<cluster_ID>/hosts:batchDelete' \
  --data '{
    "hostNames": [
      <host_name>
    ]
  }'

You can get the host name with the list of hosts in the cluster.

You can get the cluster ID with the list of clusters in the folder.

Check the server response to make sure your request was successful.

Get an IAM token for API authentication and put it into an environment variable:
```
export IAM_TOKEN="<IAM_token>"
```
Clone the cloudapi repository:
```
cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
```
Below, we assume that the repository contents reside in the ~/cloudapi/ directory.

Call the ClusterService.DeleteHosts method, e.g., via the following gRPCurl request:

grpcurl \
  -format json \
  -import-path ~/cloudapi/ \
  -import-path ~/cloudapi/third_party/googleapis/ \
  -proto ~/cloudapi/yandex/cloud/mdb/clickhouse/v1/cluster_service.proto \
  -rpc-header "Authorization: Bearer $IAM_TOKEN" \
  -d '{
    "cluster_id": "<cluster_ID>",
    "host_names": [
      <host_name>
    ]
  }' \
  mdb.api.cloud.yandex.net:443 \
  yandex.cloud.mdb.clickhouse.v1.ClusterService.DeleteHosts

You can get the host name with the list of hosts in the cluster.

You can get the cluster ID with the list of clusters in the folder.

Check the server response to make sure your request was successful.

ClickHouse® is a registered trademark of ClickHouse, Inc.

Managing ClickHouse® Keeper hosts

Getting a list of cluster hostsGetting a list of cluster hosts

Creating a ClickHouse® Keeper hostCreating a ClickHouse® Keeper host

Changing ClickHouse® Keeper settingsChanging ClickHouse® Keeper settings

Restarting a hostRestarting a host

Converting non-replicated tables to replicated onesConverting non-replicated tables to replicated ones

Deleting a ClickHouse® Keeper hostDeleting a ClickHouse® Keeper host

Was the article helpful?

Getting a list of cluster hosts

Creating a ClickHouse® Keeper host

Changing ClickHouse® Keeper settings

Restarting a host

Converting non-replicated tables to replicated ones

Deleting a ClickHouse® Keeper host