[Yandex Cloud documentation](../../index.md) > [Yandex Managed Service for ClickHouse®](../index.md) > [Step-by-step guides](index.md) > Clusters > Managing hosts > Managing ZooKeeper hosts

# Managing ZooKeeper hosts


ZooKeeper is a coordination system you can use to distribute queries among ClickHouse® hosts for [data replication](../concepts/replication.md). For successful replication, your Managed Service for ClickHouse® cluster must have [three or five ZooKeeper hosts](../qa/cluster-settings.md#zookeeper-hosts-number). This cluster will be fault-tolerant.

If you are creating a cluster with two or more ClickHouse® hosts per shard, the system will automatically add three ZooKeeper hosts to the cluster. At this stage, you can only set up their configuration. If you created a single-host cluster or a cluster with multiple single-host shards, you can add ZooKeeper hosts later.

For more information about ZooKeeper hosts, see [ZooKeeper](../concepts/coordination-system.md#zk).

When managing ZooKeeper hosts, you can do the following:

* [Get a list of cluster hosts](#list-hosts).
* [Add ZooKeeper hosts](#add-zk).
* [Update ZooKeeper host settings](#update-zk-settings).
* [Restart a host](#restart).
* [Convert non-replicated tables to replicated ones](#replicated-tables).
* [Delete a host](#delete-zk-host).

For information about moving ZooKeeper hosts to a different [availability zone](../../overview/concepts/geo-scope.md), see [this guide](host-migration.md#zookeeper-hosts).

## Getting a list of cluster hosts {#list-hosts}

# Getting a list of cluster hosts

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select the folder containing the cluster.
  1. Navigate to **Managed Service for ClickHouse**.
  1. Click the name of your cluster and select the **Hosts** tab.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) 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:

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

  ```text
  +----------------------------+--------------+---------+--------+---------------+
  |            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](cluster-list.md#list-clusters).

- REST API {#api}

    1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

        ```bash
        export IAM_TOKEN="<IAM_token>"
        ```

    1. Call the [Cluster.ListHosts](../api-ref/Cluster/listHosts.md) method, e.g., via the following [cURL](https://curl.se/) request:

        ```bash
        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](cluster-list.md#list-clusters).

    1. View the [server response](../api-ref/Cluster/listHosts.md#yandex.cloud.mdb.clickhouse.v1.ListClusterHostsResponse) to make sure your request was successful.

- gRPC API {#grpc-api}

    1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

        ```bash
        export IAM_TOKEN="<IAM_token>"
        ```

    1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository:
       
       ```bash
       cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
       ```
       
       Below, we assume that the repository contents reside in the `~/cloudapi/` directory.

    1. Call the [ClusterService.ListHosts](../api-ref/grpc/Cluster/listHosts.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:

        ```bash
        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](cluster-list.md#list-clusters).

    1. View the [server response](../api-ref/grpc/Cluster/listHosts.md#yandex.cloud.mdb.clickhouse.v1.ListClusterHostsResponse) to make sure your request was successful.

{% endlist %}


## Adding ZooKeeper hosts {#add-zk}

{% note info %}

Intel Broadwell is not supported in the `ru-central1-d` [availability zone](../../overview/concepts/geo-scope.md).

{% endnote %}

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select the folder containing the cluster.
  1. Navigate to **Managed Service for&nbsp;ClickHouse**.
  1. Click the name of your cluster and select the **Hosts** tab.
  1. At the top right, click **Set up coordinator service**.
  1. Specify the [host class](../concepts/instance-types.md).
  1. Configure the storage.
  1. Change the ZooKeeper host settings, if required. To do this, hover over the relevant host row and click ![image](../../_assets/console-icons/pencil.svg).
  1. To convert non-replicated tables to [replicated](../concepts/replication.md#replicated-tables) ones, enable **Convert non-replicated tables**. This will automatically convert [MergeTree](https://clickhouse.com/docs/enen/engines/table-engines/mergetree-family/mergetree) tables to [ReplicatedMergeTree](https://clickhouse.com/docs/enen/engines/table-engines/mergetree-family/replication) ones.

     {% note warning %}

     Once this option is enabled, you cannot disable it.

     {% endnote %}

  1. Click **Save changes**.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) 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 add ZooKeeper hosts to a cluster:
  1. View the description of the CLI command for adding ZooKeeper hosts:

     ```bash
     yc managed-clickhouse cluster add-zookeeper --help
     ```

  1. Run this command to add hosts with the default configurations:

     ```bash
     yc managed-clickhouse cluster add-zookeeper <cluster_name> \
        --host zone-id=ru-central1-d,subnet-name=default-d \
        --host zone-id=ru-central1-a,subnet-name=default-a \
        --host zone-id=ru-central1-b,subnet-name=default-b
     ```

     If the cluster network contains exactly three subnets, one per availability zone, you do not have to explicitly specify subnets for the hosts: Managed Service for ClickHouse® will automatically distribute hosts across these subnets.

     To convert non-replicated tables to [replicated](../concepts/replication.md#replicated-tables), add the `--convert-tables-to-replicated` parameter to the command. This will automatically convert non-replicated tables [MergeTree](https://clickhouse.com/docs/enen/engines/table-engines/mergetree-family/mergetree) tables to [ReplicatedMergeTree](https://clickhouse.com/docs/enen/engines/table-engines/mergetree-family/replication)-based replicated ones.

     {% note warning %}

     Once this option is enabled, you cannot disable it.

     {% endnote %}

     You can get the cluster name from the [list of clusters in your folder](cluster-list.md#list-clusters).


- Terraform {#tf}

  With [Terraform](https://www.terraform.io/), you can quickly create a cloud infrastructure in Yandex Cloud and manage it using configuration files. These files store the infrastructure description written in HashiCorp Configuration Language (HCL). If you change the configuration files, Terraform automatically detects which part of your configuration is already deployed, and what should be added or removed.
  
  Terraform is distributed under the [Business Source License](https://github.com/hashicorp/terraform/blob/main/LICENSE). The [Yandex Cloud provider for Terraform](https://github.com/yandex-cloud/terraform-provider-yandex) is distributed under the [MPL-2.0](https://www.mozilla.org/en-US/MPL/2.0/) license.
  
  For more information about the provider resources, see the relevant documentation on the [Terraform](https://www.terraform.io/docs/providers/yandex/index.html) website or [its mirror](../../terraform/index.md).

  To add ZooKeeper hosts to a cluster:

  1. Open the current Terraform configuration file with the infrastructure plan.

     For more on how to create such a file, see the [Creating a cluster](cluster-create.md) section.

  1. In the configuration file, add three subnets to different availability zones:

     ```hcl
     resource "yandex_vpc_network" "<network_name>" {
       name = "<network_name>"
     }

     resource "yandex_vpc_subnet" "<subnet_name_in_ru-central1-a_zone>" {
       name           = "<subnet_name_in_ru-central1-a_zone>"
       zone           = "ru-central1-a"
       network_id     = yandex_vpc_network.<network_name>.id
       v4_cidr_blocks = [ "<ru-central1-a_zone_subnet_IP_address_range>" ]
     }

     resource "yandex_vpc_subnet" "<subnet_name_in_ru-central1-b_zone>" {
       name           = "<subnet_name_in_ru-central1-b_zone>"
       zone           = "ru-central1-b"
       network_id     = yandex_vpc_network.<network_name>.id
       v4_cidr_blocks = [ "<ru-central1-b_zone_subnet_IP_address_range>" ]
     }

     resource "yandex_vpc_subnet" "<subnet_name_in_ru-central1-d_zone>" {
       name           = "<subnet_name_in_ru-central1-d_zone>"
       zone           = "ru-central1-d"
       network_id     = yandex_vpc_network.<network_name>.id
       v4_cidr_blocks = [ "<ru-central1-d_zone_subnet_IP_address_range>" ]
     }
     ```
      
  1. Add the following to the ClickHouse® cluster description:
      
     * `zookeeper` section with ZooKeeper configuration.
     * At least three ZooKeeper hosts in the `hosts` section.
      
     These three ZooKeeper hosts must reside in different availability zones.
      
     The ZooKeeper host requirements are as follows:

     * Minimum host class: `b1.medium`.
     * Disk type: `network-ssd`.
     * Minimum storage size: 10 GB.

     Configuration file example:

     ```hcl
     resource "yandex_mdb_clickhouse_cluster_v2" "<cluster_name>" {
       ...
       zookeeper = {
         resources = {
           resource_preset_id = "<host_class>"
           disk_type_id       = "network-ssd"
           disk_size          = <storage_size_in_GB>
         }
       }
       
       hosts = {
         ...
         <host_1_name> = {
           type      = "ZOOKEEPER"
           zone      = "ru-central1-a"
           subnet_id = yandex_vpc_subnet.<subnet_name_in_ru-central1-a_zone>.id
         }
         <host_2_name> = {
           type      = "ZOOKEEPER"
           zone      = "ru-central1-b"
           subnet_id = yandex_vpc_subnet.<subnet_name_in_ru-central1-b_zone>.id
         }
         <host_3_name> = {
           type      = "ZOOKEEPER"
           zone      = "ru-central1-d"
           subnet_id = yandex_vpc_subnet.<subnet_name_in_ru-central1-d_zone>.id
         }
       }
     }
     ```

     Where `resource_preset_id` is the host class, `b1.medium` or higher.

  1. Make sure the settings are correct.

     1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
     1. Run this command:
     
        ```bash
        terraform validate
        ```
     
        Terraform will show any errors found in your configuration files.

  1. Confirm updating the resources.

     1. Run this command to view the planned changes:
     
        ```bash
        terraform plan
        ```
     
        If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.
     
     1. If everything looks correct, apply the changes:
        1. Run this command:
     
           ```bash
           terraform apply
           ```
     
        1. Confirm updating the resources.
        1. Wait for the operation to complete.

  For more information, see [this Terraform provider guide](../../terraform/resources/mdb_clickhouse_cluster.md).

  {% note warning "Timeouts" %}
  
  The Terraform provider sets the following timeouts for Managed Service for ClickHouse® cluster operations:
  
  * Creating a cluster, including by restoring from a backup: 60 minutes.
  * Updating a cluster: 90 minutes.
  * Deleting a cluster: 30 minutes.
  
  Operations exceeding the timeout are aborted.
  
  {% cut "How to change these limits" %}
  
  Add the `timeouts` section to your cluster description, such as the following:
  
  ```hcl
  resource "yandex_mdb_clickhouse_cluster_v2" "<cluster_name>" {
    ...
    timeouts = {
      create = "1h30m" # 1 hour 30 minutes
      update = "2h"    # 2 hours
      delete = "30m"   # 30 minutes
    }
  }
  ```
  
  {% endcut %}
  
  {% endnote %}


- REST API {#api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:
  
      ```bash
      export IAM_TOKEN="<IAM_token>"
      ```
  
  1. Call the [Cluster.AddZookeeper](../api-ref/Cluster/addZookeeper.md) method, e.g., via the following [cURL](https://curl.se/) request:
  
      ```bash
      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>:addZookeeper' \
        --data '{
                 "resources": {
                   "resourcePresetId": "<host_class>",
                   "diskSize": "<storage_size_in_bytes>",
                   "diskTypeId": "<disk_type>"
                 },
                 "hostSpecs": [
                   {
                     "type": "ZOOKEEPER",
                     "zoneId": "<availability_zone>",
                     "subnetId": "<subnet_ID>"
                   },
                   { <similar_settings_for_new_host_2> },
                   { ... },
                   { <similar_settings_for_new_host_N> }
                 ],
                 "convertTablesToReplicated": true
               }'
      ```
  
      Where:
  
      * `resources`: Resources for ZooKeeper hosts.
  
        * `resourcePresetId`: [Host class](../concepts/instance-types.md) ID.
        * `diskSize`: Disk size, in bytes.
        * `diskTypeId`: [Disk type](../concepts/storage.md).
  
      * `hostSpecs`: Array of settings for the new hosts. One array element contains settings for a single host and the cluster must have at least three ZooKeeper hosts. An array element has the following structure:
  
        * `type`: `ZOOKEEPER` host type.
        * `zoneId`: Availability zone.
        * `subnetId`: Subnet ID.
  
      * `convertTablesToReplicated`: Converting non-replicated tables to [replicated](../concepts/replication.md#replicated-tables) ones, `true` or `false`. This will automatically convert non-replicated tables [MergeTree](https://clickhouse.com/docs/enen/engines/table-engines/mergetree-family/mergetree) tables to [ReplicatedMergeTree](https://clickhouse.com/docs/enen/engines/table-engines/mergetree-family/replication)-based replicated ones.
  
        {% note warning %}
  
        Once this option is enabled, you cannot disable it.
  
        {% endnote %}
  
      You can request the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).
  
  1. View the [server response](../api-ref/Cluster/addZookeeper.md#responses) to make sure your request was successful.

- gRPC API {#grpc-api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:
  
      ```bash
      export IAM_TOKEN="<IAM_token>"
      ```
  
  1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository:
     
     ```bash
     cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
     ```
     
     Below, we assume that the repository contents reside in the `~/cloudapi/` directory.
  1. Call the [ClusterService.AddZookeeper](../api-ref/grpc/Cluster/addZookeeper.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:
  
       ```bash
       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>",
               "resources": {
                 "resource_preset_id": "<host_class>",
                 "disk_size": "<storage_size_in_bytes>",
                 "disk_type_id": "<disk_type>"
               },
               "host_specs": [
                 {
                   "type": "ZOOKEEPER",
                   "zone_id": "<availability_zone>",
                   "subnet_id": "<subnet_ID>"
                 },
                 { <similar_settings_for_new_host_2> },
                 { ... },
                 { <similar_settings_for_new_host_N> }
               ],
               "convert_tables_to_replicated": true
             }' \
         mdb.api.cloud.yandex.net:443 \
         yandex.cloud.mdb.clickhouse.v1.ClusterService.AddZookeeper
       ```
  
      Where:
  
      * `resources`: Resources for ZooKeeper hosts.
  
        * `resource_preset_id`: [Host class](../concepts/instance-types.md) ID.
        * `disk_size`: Disk size, in bytes.
        * `disk_type_id`: [Disk type](../concepts/storage.md).
  
      * `host_specs`: Array of settings for the new hosts. Each array element contains settings for a single host and the cluster must have at least three ZooKeeper hosts.
  
        An array element has the following structure:
  
        * `type`: `ZOOKEEPER` host type.
        * `zone_id`: Availability zone.
        * `subnet_id`: Subnet ID.
  
      * `convert_tables_to_replicated`: Converting non-replicated tables to [replicated](../concepts/replication.md#replicated-tables) ones, `true` or `false`. This will automatically convert non-replicated tables [MergeTree](https://clickhouse.com/docs/enen/engines/table-engines/mergetree-family/mergetree) tables to [ReplicatedMergeTree](https://clickhouse.com/docs/enen/engines/table-engines/mergetree-family/replication)-based replicated ones.
  
        {% note warning %}
  
        Once this option is enabled, you cannot disable it.
  
        {% endnote %}
  
      You can request the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).
  
  1. View the [server response](../api-ref/grpc/Cluster/addZookeeper.md#yandex.cloud.operation.Operation) to make sure your request was successful.

{% endlist %}

## Updating ZooKeeper host settings {#update-zk-settings}

After creating ZooKeeper hosts, you can change their [class](../concepts/instance-types.md), storage size, and [disk type](../concepts/storage.md).

We recommend changing the host class only when your cluster has no active workload.

The minimum number of cores per ZooKeeper host depends on the total number of cores on ClickHouse® hosts. For more information, see [Coordination services](../concepts/coordination-system.md#zk).

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select the folder containing the cluster.
  1. Navigate to **Managed Service for&nbsp;ClickHouse**.
  1. Select your cluster and click **Edit** in the top panel.
  1. Under **ZooKeeper host class**, select the platform, VM type, and required ZooKeeper host class.
  1. Under **ZooKeeper storage size**, set the storage size and disk type for ZooKeeper hosts.
  1. Click **Save changes**.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) 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 update a ZooKeeper host configuration:

  1. View the description of the CLI command for updating a cluster:

     ```bash
     yc managed-clickhouse cluster update --help
     ```

  1. Get the list of available host classes. The `ZONE IDS` column lists the availability zones where you can select the appropriate class:

     ```bash
     yc managed-clickhouse resource-preset list

     +-----------+--------------------------------+-------+----------+
     |    ID     |            ZONE IDS            | CORES |  MEMORY  |
     +-----------+--------------------------------+-------+----------+
     | s1.micro  | ru-central1-a, ru-central1-b,  |     2 | 8.0 GB   |
     |           | ru-central1-d                  |       |          |
     | ...                                                           |
     +-----------+--------------------------------+-------+----------+
     ```

  1. In the update cluster command, provide the new ZooKeeper host class, disk type, and storage size:

     ```bash
     yc managed-clickhouse cluster update <cluster_name_or_ID> \
        --zookepeer-resource-preset=<host_class> \
        --zookeeper-disk-size=<storage_size_in_GB> \
        --zookeeper-disk-type=<disk_type>
     ```

     You can get the cluster name and ID with the [list of clusters in the folder](cluster-list.md#list-clusters).


- Terraform {#tf}

  With [Terraform](https://www.terraform.io/), you can quickly create a cloud infrastructure in Yandex Cloud and manage it using configuration files. These files store the infrastructure description written in HashiCorp Configuration Language (HCL). If you change the configuration files, Terraform automatically detects which part of your configuration is already deployed, and what should be added or removed.
  
  Terraform is distributed under the [Business Source License](https://github.com/hashicorp/terraform/blob/main/LICENSE). The [Yandex Cloud provider for Terraform](https://github.com/yandex-cloud/terraform-provider-yandex) is distributed under the [MPL-2.0](https://www.mozilla.org/en-US/MPL/2.0/) license.
  
  For more information about the provider resources, see the relevant documentation on the [Terraform](https://www.terraform.io/docs/providers/yandex/index.html) website or [its mirror](../../terraform/index.md).

  To update the ZooKeeper host settings:

  1. Open the current Terraform configuration file with the infrastructure plan.

     For more on how to create such a file, see the [Creating a cluster](cluster-create.md) section.

  1. In the ZooKeeper configuration section, specify the new host class, disk type, and storage size.

     The ZooKeeper host requirements are as follows:
     * Minimum host class: `b1.medium`.
     * Minimum storage size: 10 GB.

     ```hcl
     resource "yandex_mdb_clickhouse_cluster_v2" "<cluster_name>" {
       ...
       zookeeper = {
         resources = {
           resource_preset_id = "<host_class>"
           disk_type_id       = "<disk_type>"
           disk_size          = <storage_size_in_GB>
         }
       }
       ...
     }
     ```

  1. Make sure the settings are correct.

     1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
     1. Run this command:
     
        ```bash
        terraform validate
        ```
     
        Terraform will show any errors found in your configuration files.

  1. Confirm updating the resources.

     1. Run this command to view the planned changes:
     
        ```bash
        terraform plan
        ```
     
        If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.
     
     1. If everything looks correct, apply the changes:
        1. Run this command:
     
           ```bash
           terraform apply
           ```
     
        1. Confirm updating the resources.
        1. Wait for the operation to complete.

  For more information, see [this Terraform provider guide](../../terraform/resources/mdb_clickhouse_cluster.md).

  {% note warning "Timeouts" %}
  
  The Terraform provider sets the following timeouts for Managed Service for ClickHouse® cluster operations:
  
  * Creating a cluster, including by restoring from a backup: 60 minutes.
  * Updating a cluster: 90 minutes.
  * Deleting a cluster: 30 minutes.
  
  Operations exceeding the timeout are aborted.
  
  {% cut "How to change these limits" %}
  
  Add the `timeouts` section to your cluster description, such as the following:
  
  ```hcl
  resource "yandex_mdb_clickhouse_cluster_v2" "<cluster_name>" {
    ...
    timeouts = {
      create = "1h30m" # 1 hour 30 minutes
      update = "2h"    # 2 hours
      delete = "30m"   # 30 minutes
    }
  }
  ```
  
  {% endcut %}
  
  {% endnote %}


- REST API {#api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

      ```bash
      export IAM_TOKEN="<IAM_token>"
      ```

  1. Get the list of available host classes:

      1. Call the [ResourcePreset.List](../api-ref/ResourcePreset/list.md) method, e.g., via the following [cURL](https://curl.se/) request:

          ```bash
          curl \
              --request GET \
              --header "Authorization: Bearer $IAM_TOKEN" \
              --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/resourcePresets'
          ```

      1. Check the [server response](../api-ref/ResourcePreset/list.md#responses) to make sure your request was successful.

  1. Update the host class, disk type, and storage size:

      1. Call the [Cluster.Update](../api-ref/Cluster/update.md) method, e.g., via the following [cURL](https://curl.se/) request:

          {% note warning %}
          
          The API method will assign default values to all the parameters of the object you are modifying unless you explicitly provide them in your request. To avoid this, list the settings you want to change in the `updateMask` parameter as a single comma-separated string.
          
          {% endnote %}

          ```bash
          curl \
              --request PATCH \
              --header "Authorization: Bearer $IAM_TOKEN" \
              --header "Content-Type: application/json" \
              --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/clusters/<cluster_ID>' \
              --data '{
                        "updateMask": "configSpec.zookeeper.resources.resourcePresetId,configSpec.zookeeper.resources.diskTypeId,configSpec.zookeeper.resources.diskSize",
                        "configSpec": {
                          "zookeeper": {
                            "resources": {
                              "resourcePresetId": "<host_class>",
                              "diskTypeId": "<disk_type>",
                              "diskSize": "<storage_size_in_GB>"
                            }
                          }
                        }
                      }'
          ```

          Where:

          * `updateMask`: Comma-separated string of settings you want to update.

              Specify the relevant parameters:
              * `configSpec.zookeeper.resources.resourcePresetId`: To change the ZooKeeper host class.
              * `configSpec.zookeeper.resources.diskTypeId`: To change the disk type for ZooKeeper hosts.
              * `configSpec.zookeeper.resources.diskSize`: To change the ZooKeeper storage size.

          * `configSpec.zookeeper.resources.resourcePresetId`: [Host class](../concepts/instance-types.md) ID.
          * `configSpec.zookeeper.resources.diskTypeId`: [Disk type](../concepts/storage.md).
          * `configSpec.zookeeper.resources.diskSize`: Storage size, in GB.

          You can get the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters). Earlier, you already obtained the list of available host classes with their IDs.

    1. Check the [server response](../api-ref/Cluster/update.md#yandex.cloud.operation.Operation) to make sure your request was successful.

- gRPC API {#grpc-api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

      ```bash
      export IAM_TOKEN="<IAM_token>"
      ```

  1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository:
     
     ```bash
     cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
     ```
     
     Below, we assume that the repository contents reside in the `~/cloudapi/` directory.

  1. Get the list of available host classes:

      1. Call the [ResourcePresetService.List](../api-ref/grpc/ResourcePreset/list.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:

          ```bash
          grpcurl \
              -format json \
              -import-path ~/cloudapi/ \
              -import-path ~/cloudapi/third_party/googleapis/ \
              -proto ~/cloudapi/yandex/cloud/mdb/clickhouse/v1/resource_preset_service.proto \
              -rpc-header "Authorization: Bearer $IAM_TOKEN" \
              mdb.api.cloud.yandex.net:443 \
              yandex.cloud.mdb.clickhouse.v1.ResourcePresetService.List
          ```

      1. Check the [server response](../api-ref/grpc/ResourcePreset/list.md#yandex.cloud.mdb.clickhouse.v1.ListResourcePresetsResponse) to make sure your request was successful.

  1. Update the host class, disk type, and storage size:

      1. Call the [ClusterService.Update](../api-ref/grpc/Cluster/update.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:

          {% note warning %}
          
          The API method will assign default values to all the parameters of the object you are modifying unless you explicitly provide them in your request. To avoid this, list the settings you want to change in the `update_mask` parameter as an array of `paths[]` strings.
          
          {% cut "Format for listing settings" %}
          
          ```yaml
          "update_mask": {
              "paths": [
                  "<setting_1>",
                  "<setting_2>",
                  ...
                  "<setting_N>"
              ]
          }
          ```
          
          {% endcut %}
          
          {% endnote %}

          ```bash
          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>",
                    "update_mask": {
                      "paths": [
                        "config_spec.zookeeper.resources.resource_preset_id",
                        "config_spec.zookeeper.resources.disk_type_id",
                        "config_spec.zookeeper.resources.disk_size"
                      ]
                    },
                    "config_spec": {
                      "zookeeper": {
                        "resources": {
                          "resource_preset_id": "<host_class>",
                          "disk_type_id": "<disk_type>",
                          "disk_size": "<storage_size_in_GB>"
                        }
                      }
                    }
                  }' \
              mdb.api.cloud.yandex.net:443 \
              yandex.cloud.mdb.clickhouse.v1.ClusterService.Update
          ```

          Where:

          * `update_mask`: List of settings you want to update as an array of strings (`paths[]`).

              Specify the relevant parameters:
              * `config_spec.zookeeper.resources.resource_preset_id`: To change the ZooKeeper host class.
              * `config_spec.zookeeper.resources.disk_type_id`: To change the disk type for ZooKeeper hosts.
              * `config_spec.zookeeper.resources.disk_size`: To change the ZooKeeper storage size.

          * `config_spec.zookeeper.resources.resource_preset_id`: [Host class](../concepts/instance-types.md) ID.
          * `config_spec.zookeeper.resources.disk_type_id`: [Disk type](../concepts/storage.md).
          * `config_spec.zookeeper.resources.disk_size`: Storage size, in GB.

          You can get the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters). Earlier, you already obtained the list of available host classes with their IDs.

  1. View the [server response](../api-ref/grpc/Cluster/update.md#yandex.cloud.operation.Operation) to make sure your request was successful.

{% endlist %}

## Restarting a ZooKeeper host {#restart}

# 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

{% list tabs group=instructions %}

- Management console {#console}

  To restart a single host:

    1. In the [management console](https://console.yandex.cloud), select the folder containing the cluster.
    1. Navigate to **Managed Service for&nbsp;ClickHouse**.
    1. Click the cluster name and navigate to the **Hosts** tab.
    1. In the host row, click ![icon](../../_assets/console-icons/ellipsis.svg) and select **Restart**.
    1. In the window that opens, enable **I am restarting host** and click **Confirm**.

  To restart multiple hosts in one go:

    1. In the [management console](https://console.yandex.cloud), select the folder containing the cluster.
    1. Navigate to **Managed Service for&nbsp;ClickHouse**.
    1. Click the cluster name and navigate to the **Hosts** tab.
    1. Select the hosts you want to restart and click **Restart** at the bottom of the screen.
    1. In the window that opens, click **Confirm**.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) 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 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:

  ```bash
  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](cluster-list.md#list-clusters).

- REST API {#api}

    1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

        ```bash
        export IAM_TOKEN="<IAM_token>"
        ```

    1. Call the [Cluster.RestartHosts](../api-ref/Cluster/restartHosts.md) method, e.g., via the following [cURL](https://curl.se/) request:

        ```bash
        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](hosts.md#list-hosts).

        You can get the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).

    1. View the [server response](../api-ref/Cluster/restartHosts.md#yandex.cloud.operation.Operation) to make sure your request was successful.

- gRPC API {#grpc-api}

    1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

        ```bash
        export IAM_TOKEN="<IAM_token>"
        ```

    1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository:
       
       ```bash
       cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
       ```
       
       Below, we assume that the repository contents reside in the `~/cloudapi/` directory.

    1. Call the [ClusterService.RestartHosts](../api-ref/grpc/Cluster/restartHosts.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:

        ```bash
        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](hosts.md#list-hosts).

        You can get the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).

    1. View the [server response](../api-ref/grpc/Cluster/create.md#yandex.cloud.operation.Operation) to make sure your request was successful.

{% endlist %}

## Converting non-replicated tables to replicated ones {#replicated-tables}

You can convert MergeTree-based non-replicated tables to ReplicatedMergeTree-based [replicated](../concepts/replication.md#replicated-tables) 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](https://clickhouse.com/docs/enen/engines/table-engines/mergetree-family). 

{% list tabs group=instructions %}

- Automatically {#auto}

  To automatically convert non-replicated tables to replicated ones, [add ZooKeeper hosts](#add-zk) with table conversion enabled.

- SQL {#sql}

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

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

  1. Convert the table to a replicated one:

      ```sql
      ATTACH TABLE <table_name> AS REPLICATED;
      ```

  1. Restore and synchronize the state of your table replica in ZooKeeper:

      ```sql
      SYSTEM RESTORE REPLICA <table_name>;
      ```

{% endlist %}

## Deleting a ZooKeeper host {#delete-zk-host}

{% note warning %}

If ZooKeeper hosts have already been created in the cluster, you cannot delete them completely: a cluster will always have at least three ZooKeeper hosts.

{% endnote %}

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select the folder containing the cluster.
  1. Navigate to **Managed Service for&nbsp;ClickHouse**.
  1. Click the name of your cluster and select the **Hosts** tab.
  1. Hover over the relevant host row and click ![image](../../_assets/console-icons/xmark.svg).
  1. In the window that opens, click **Delete**.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) 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 delete a host from a cluster, run this command:

  ```bash
  yc managed-clickhouse hosts delete <host_name> \
    --cluster-name=<cluster_name>
  ```

  You can get the host name with the [list of cluster hosts](hosts.md#list-hosts), and the cluster name, with the [list of clusters in the folder](cluster-list.md#list-clusters).


- Terraform {#tf}

   With [Terraform](https://www.terraform.io/), you can quickly create a cloud infrastructure in Yandex Cloud and manage it using configuration files. These files store the infrastructure description written in HashiCorp Configuration Language (HCL). If you change the configuration files, Terraform automatically detects which part of your configuration is already deployed, and what should be added or removed.
   
   Terraform is distributed under the [Business Source License](https://github.com/hashicorp/terraform/blob/main/LICENSE). The [Yandex Cloud provider for Terraform](https://github.com/yandex-cloud/terraform-provider-yandex) is distributed under the [MPL-2.0](https://www.mozilla.org/en-US/MPL/2.0/) license.
   
   For more information about the provider resources, see the relevant documentation on the [Terraform](https://www.terraform.io/docs/providers/yandex/index.html) website or [its mirror](../../terraform/index.md).

   To delete a ZooKeeper host:

   1. Open the current Terraform configuration file with the infrastructure plan.

      For more on how to create such a file, see the [Creating a cluster](cluster-create.md) section.

   1. Delete the `ZooKeeper` host from the `hosts` section.
   1. Make sure the settings are correct.

      1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
      1. Run this command:
      
         ```bash
         terraform validate
         ```
      
         Terraform will show any errors found in your configuration files.

   1. Type `yes` and press **Enter**.

      1. Run this command to view the planned changes:
      
         ```bash
         terraform plan
         ```
      
         If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.
      
      1. If everything looks correct, apply the changes:
         1. Run this command:
      
            ```bash
            terraform apply
            ```
      
         1. Confirm updating the resources.
         1. Wait for the operation to complete.

   For more information, see [this Terraform provider guide](../../terraform/resources/mdb_clickhouse_cluster.md).

   {% note warning "Timeouts" %}
   
   The Terraform provider sets the following timeouts for Managed Service for ClickHouse® cluster operations:
   
   * Creating a cluster, including by restoring from a backup: 60 minutes.
   * Updating a cluster: 90 minutes.
   * Deleting a cluster: 30 minutes.
   
   Operations exceeding the timeout are aborted.
   
   {% cut "How to change these limits" %}
   
   Add the `timeouts` section to your cluster description, such as the following:
   
   ```hcl
   resource "yandex_mdb_clickhouse_cluster_v2" "<cluster_name>" {
     ...
     timeouts = {
       create = "1h30m" # 1 hour 30 minutes
       update = "2h"    # 2 hours
       delete = "30m"   # 30 minutes
     }
   }
   ```
   
   {% endcut %}
   
   {% endnote %}


- REST API {#api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it in an environment variable:
  
      ```bash
      export IAM_TOKEN="<IAM_token>"
      ```
  
  1. Call the [Cluster.DeleteHosts](../api-ref/Cluster/deleteHosts.md) method, e.g., via the following [cURL](https://curl.se/) request:
  
      ```bash
      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": [
                      <list_of_host_names>
                    ]
                  }'
      ```
  
      Where `hostNames` is an array of strings. Each string is the name of a host to delete. You can get the host names with the [list of hosts in the cluster](#list-hosts).
  
      You can get the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).
  
  1. View the [server response](../api-ref/Cluster/deleteHosts.md#yandex.cloud.operation.Operation) to make sure your request was successful.

- gRPC API {#grpc-api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it in an environment variable:
  
      ```bash
      export IAM_TOKEN="<IAM_token>"
      ```
  
  1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository:
     
     ```bash
     cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
     ```
     
     Below, we assume that the repository contents reside in the `~/cloudapi/` directory.
  
  1. Call the [ClusterService.DeleteHosts](../api-ref/grpc/Cluster/deleteHosts.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:
  
      ```bash
      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.DeleteHosts
      ```
  
      Where `host_names` is an array of strings. Each string is the name of a host to delete. You can get the host names with the [list of hosts in the cluster](#list-hosts).
  
      You can get the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).
  
  1. View the [server response](../api-ref/grpc/Cluster/deleteHosts.md#yandex.cloud.operation.Operation) to make sure your request was successful.

{% endlist %}

_ClickHouse® is a registered trademark of [ClickHouse, Inc](https://clickhouse.com)._