Managing ClickHouse® Keeper hosts

Written by

Yandex Cloud

Updated at December 22, 2025

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

After creating a cluster with separate ClickHouse® Keeper hosts, you can:

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 the cluster is in.
Go to Managed Service for ClickHouse.
Click the cluster name and select the Hosts tab.

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

By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.

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 in 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 save it as 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 the repository contents are stored 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 go 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 the cluster is in.
Go 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 the cluster is in.
Go 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 installed 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 save it as 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 save it as 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 the repository contents are stored 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

To automatically convert non-replicated MergeTree tables to replicated ReplicatedMergeTree tables, enable the Convert non-replicated tables setting when activating the coordination service.

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 go to the Hosts tab.
In the host row, click and select Delete.
Confirm the deletion.

If you do not have the Yandex Cloud CLI installed 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 in 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 in 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 the repository contents are stored 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.

View 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