Updating ClickHouse® cluster settings
After creating a cluster, you can:
- Change service account settings.
- Change the host class.
- Increase storage size.
- Enable user and database management via SQL.
- Change additional cluster settings.
- Move the cluster to another folder.
- Change cluster security groups.
- Changing hybrid storage settings.
Learn more about other cluster updates:
- Migrating a cluster to a different availability zone.
- Configuring ClickHouse® servers as described in this ClickHouse® article
. - Changing ClickHouse® settings at the query level.
Changing service account settings
To link your service account to a Managed Service for ClickHouse® cluster, assign the iam.serviceAccounts.user role or higher to your Yandex Cloud account.
Warning
If the cluster already uses a service account to access objects from Object Storage, then changing it to a different service account may make these objects unavailable and interrupt the cluster operation. Before changing the service account settings, make sure that the cluster doesn't use the objects in question.
To change the service account settings:
- 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 Service settings, select your service account from the list or create a new one. For more information about setting up a service account, see Configuring access to Object Storage from a ClickHouse® cluster.
Changing the host class
Note
You cannot use ZooKeeper hosts in clusters with ClickHouse® Keeper support. To learn more, see Replication.
When changing the host class:
- Your single-host cluster will be unavailable for a few minutes with database connections terminated.
- In a multi-host cluster, hosts will be stopped and updated one by one. When stopped, a host will be unavailable for a few minutes.
- Using a special FQDN does not guarantee a stable database connection: user sessions may be terminated.
We recommend changing the host class only when your cluster has no active workload.
The host class affects the RAM amount ClickHouse® can use. For more information, see Memory management.
The minimum number of cores per ZooKeeper host depends on the total number of cores on ClickHouse® hosts. To learn more, see Replication.
- 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.
- To change the ClickHouse® host class, select the platform, VM type, and required host class under Resources.
- To change the ZooKeeper host class, select the platform, VM type, and required ZooKeeper host class under ZooKeeper host class.
- Click Save changes.
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 change the host class for a cluster:
-
View the description of the CLI command to update a cluster:
yc managed-clickhouse cluster update --help
-
Request a list of available host classes (the
ZONE IDS
column specifies the availability zones where you can select the appropriate class):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 | | | | ... | +-----------+--------------------------------+-------+----------+
-
Specify the class in the update cluster command:
yc managed-clickhouse cluster update <cluster_name_or_ID> \ --clickhouse-resource-preset=<class_ID>
Managed Service for ClickHouse® will run the update host class command for the cluster.
-
To change the class of a ZooKeeper host, provide the value you need in the
--zookeeper-resource-preset
parameter.
-
Open the current Terraform configuration file that defines your infrastructure.
For more information about creating this file, see this guide.
-
In the Managed Service for ClickHouse® cluster description, change the value of the
resource_preset_id
parameter in theclickhouse.resources
andzookeeper.resources
sections for ClickHouse® and ZooKeeper hosts, respectively:resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" { ... clickhouse { resources { resource_preset_id = "<ClickHouse®_host_class>" ... } } zookeeper { resources { resource_preset_id = "<ZooKeeper_host_class>" ... } } }
-
Make sure the settings are correct.
-
In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
-
Run this command:
terraform validate
Terraform will show any errors found in your configuration files.
-
-
Confirm updating the resources.
-
Run this command to view the planned changes:
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.
-
If everything looks correct, apply the changes:
-
Run this command:
terraform apply
-
Confirm updating the resources.
-
Wait for the operation to complete.
-
-
For more information, see this Terraform provider article
Time limits
A Terraform provider sets the timeout for Managed Service for ClickHouse® cluster operations:
- Creating a cluster, including by restoring one from a backup: 60 minutes.
- Editing a cluster: 90 minutes.
- Deleting a cluster: 30 minutes.
Operations exceeding the set timeout are interrupted.
How do I change these limits?
Add the timeouts
block to the cluster description, for example:
resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" {
...
timeouts {
create = "1h30m" # 1 hour 30 minutes
update = "2h" # 2 hours
delete = "30m" # 30 minutes
}
}
-
Get an IAM token for API authentication and save it as an environment variable:
export IAM_TOKEN="<IAM_token>"
-
Request a list of available host classes:
-
Use the ResourcePreset.List method and send the following request, e.g., via cURL
:curl \ --request GET \ --header "Authorization: Bearer $IAM_TOKEN" \ --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/resourcePresets'
-
View the server response to make sure your request was successful.
-
-
Change the host class as appropriate:
-
Use the Cluster.Update method and send the following request, e.g., via cURL
: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.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.clickhouse.resources.resourcePresetId,configSpec.zookeeper.resources.resourcePresetId", "configSpec": { "clickhouse": { "resources": { "resourcePresetId": "<ClickHouse®_host_class_ID>" } }, "zookeeper": { "resources": { "resourcePresetId": "<ZooKeeper_host_class_ID>" } } } }'
Where:
-
updateMask
: List of parameters to update as a single string, separated by commas.Specify the relevant parameters:
configSpec.clickhouse.resources.resourcePresetId
: To change the ClickHouse® host class.configSpec.zookeeper.resources.resourcePresetId
: To change the ZooKeeper host class.
In our request example, we are changing both ClickHouse® and ZooKeeper host classes.
-
configSpec.clickhouse.resources.resourcePresetId
: ClickHouse® host class ID. -
configSpec.zookeeper.resources.resourcePresetId
: ZooKeeper host class ID.
You can request the cluster ID with the list of clusters in the folder. Earlier, you already obtained the list of available host classes with their IDs.
-
-
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. -
Request a list of available host classes:
-
Use the ResourcePresetService/List call and send the following request, e.g., via gRPCurl
: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
-
View the server response to make sure your request was successful.
-
-
Change the host class as appropriate:
-
Use the ClusterService.Update call and send the following request, e.g., via gRPCurl
: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 ofpaths[]
strings.Format for listing settings
"update_mask": { "paths": [ "<setting_1>", "<setting_2>", ... "<setting_N>" ] }
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.clickhouse.resources.resource_preset_id", "config_spec.zookeeper.resources.resource_preset_id" ] }, "config_spec": { "clickhouse": { "resources": { "resource_preset_id": "<ClickHouse®_host_class_ID>" } }, "zookeeper": { "resources": { "resource_preset_id": "<ZooKeeper_host_class_ID>" } } } }' \ mdb.api.cloud.yandex.net:443 \ yandex.cloud.mdb.clickhouse.v1.ClusterService.Update
Where:
-
update_mask
: List of parameters to update as an array ofpaths[]
strings.Specify the relevant parameters:
config_spec.clickhouse.resources.resource_preset_id
: To change the ClickHouse® host class.config_spec.zookeeper.resources.resource_preset_id
: To change the ZooKeeper host class.
In our request example, we are changing both ClickHouse® and ZooKeeper host classes.
-
config_spec.clickhouse.resources.resource_preset_id
: ClickHouse® host class ID. -
config_spec.zookeeper.resources.resource_preset_id
: ZooKeeper host class ID.
You can request the cluster ID with the list of clusters in the folder. Earlier, you already obtained the list of available host classes with their IDs.
-
-
View the server response to make sure your request was successful.
-
Increasing your storage size
Note
You cannot use ZooKeeper hosts in clusters with ClickHouse® Keeper support. To learn more, see Replication.
Make sure the cloud has enough quota to increase the storage size. Open the cloud's Quotas
To increase your cluster storage size:
- 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 Storage size, specify the value you need.
- Click Save changes.
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 increase your cluster storage size:
-
View the description of the CLI command to update a cluster:
yc managed-clickhouse cluster update --help
-
Specify the required storage size in the cluster update command (it must be at least as large as
disk_size
in the cluster properties):yc managed-clickhouse cluster update <cluster_name_or_ID> \ --clickhouse-disk-size <storage_size_in_GB>
-
To increase the storage size of ZooKeeper hosts, provide the value you need in the
--zookeeper-disk-size
parameter.
To increase the storage size:
-
Open the current Terraform configuration file that defines your infrastructure.
For more information about creating this file, see this guide.
-
In the Managed Service for ClickHouse® cluster description, change the value of the
disk_size
parameter in theclickhouse.resources
andzookeeper.resources
sections for ClickHouse® and ZooKeeper hosts, respectively:resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" { ... clickhouse { resources { disk_size = <storage_size_in_GB> ... } } zookeeper { resources { disk_size = <storage_size_in_GB> ... } } }
-
Make sure the settings are correct.
-
In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
-
Run this command:
terraform validate
Terraform will show any errors found in your configuration files.
-
-
Confirm updating the resources.
-
Run this command to view the planned changes:
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.
-
If everything looks correct, apply the changes:
-
Run this command:
terraform apply
-
Confirm updating the resources.
-
Wait for the operation to complete.
-
-
For more information, see this Terraform provider article
Time limits
A Terraform provider sets the timeout for Managed Service for ClickHouse® cluster operations:
- Creating a cluster, including by restoring one from a backup: 60 minutes.
- Editing a cluster: 90 minutes.
- Deleting a cluster: 30 minutes.
Operations exceeding the set timeout are interrupted.
How do I change these limits?
Add the timeouts
block to the cluster description, for example:
resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" {
...
timeouts {
create = "1h30m" # 1 hour 30 minutes
update = "2h" # 2 hours
delete = "30m" # 30 minutes
}
}
-
Get an IAM token for API authentication and save it as an environment variable:
export IAM_TOKEN="<IAM_token>"
-
Use the Cluster.Update method and send the following request, e.g., via cURL
: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.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.clickhouse.resources.diskSize,configSpec.zookeeper.resources.diskSize", "configSpec": { "clickhouse": { "resources": { "diskSize": "<storage_size_in_bytes>" } }, "zookeeper": { "resources": { "diskSize": "<storage_size_in_bytes>" } } } }'
Where:
-
updateMask
: List of parameters to update as a single string, separated by commas.Specify the relevant parameters:
configSpec.clickhouse.resources.diskSize
: To increase the storage size of ClickHouse® hosts.configSpec.zookeeper.resources.diskSize
: To increase the storage size of ZooKeeper hosts.
In our request example, we are increasing the storage size for both ClickHouse® and ZooKeeper hosts.
-
configSpec.clickhouse.resources.diskSize
: ClickHouse® host storage size, in bytes. -
configSpec.zookeeper.resources.diskSize
: ZooKeeper host storage size, in bytes.
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. -
Use the ClusterService.Update call and send the following request, e.g., via gRPCurl
: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 ofpaths[]
strings.Format for listing settings
"update_mask": { "paths": [ "<setting_1>", "<setting_2>", ... "<setting_N>" ] }
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.clickhouse.resources.disk_size", "config_spec.zookeeper.resources.disk_size" ] }, "config_spec": { "clickhouse": { "resources": { "disk_size": "<storage_size_in_bytes>" } }, "zookeeper": { "resources": { "disk_size": "<storage_size_in_bytes>" } } } }' \ mdb.api.cloud.yandex.net:443 \ yandex.cloud.mdb.clickhouse.v1.ClusterService.Update
Where:
-
update_mask
: List of parameters to update as an array ofpaths[]
strings.Specify the relevant parameters:
config_spec.clickhouse.resources.disk_size
: To increase the storage size of ClickHouse® hosts.config_spec.zookeeper.resources.disk_size
: To increase the storage size of ZooKeeper hosts.
In our request example, we are increasing the storage size for both ClickHouse® and ZooKeeper hosts.
-
config_spec.clickhouse.resources.disk_size
: ClickHouse® host storage size, in bytes. -
config_spec.zookeeper.resources.disk_size
: ZooKeeper host storage size, in bytes.
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.
Enabling user and database management via SQL
Managed Service for ClickHouse® enables managing cluster users and databases via SQL.
Alert
This disables user and database management through native Yandex Cloud interfaces, such as management console, CLI, Terraform, and API.
You cannot disable settings for user or database management via SQL once they are enabled.
- Navigate to the folder dashboard and select Managed Service for ClickHouse.
- Select the cluster and click Edit in the top panel.
- To manage users via SQL, enable DBMS settings under User management via SQL and specify the
admin
password. - To manage databases via SQL, enable DBMS settings and User management via SQL under Managing databases via SQL and specify the
admin
password. - Click Save changes.
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 enable user management via SQL:
- Set
--enable-sql-user-management
totrue
. - Set a password for
admin
in the--admin-password
parameter.
yc managed-clickhouse cluster update <cluster_name_or_ID> \ ... --enable-sql-user-management true \ --admin-password "<admin_user_password>"
- Set
-
To enable database management via SQL:
- Set
--enable-sql-user-management
and--enable-sql-database-management
totrue
. - Set a password for
admin
in the--admin-password
parameter.
yc managed-clickhouse cluster update <cluster_name_or_ID> \ ... --enable-sql-user-management true \ --enable-sql-database-management true \ --admin-password "<admin_user_password>"
- Set
-
Open the current Terraform configuration file that defines your infrastructure.
For more information about creating this file, see this guide.
-
To enable user management via SQL, expand the cluster description to include a
sql_user_management
field set totrue
and anadmin_password
field containing the password for theadmin
account:resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" { name = "<cluster_name>" ... admin_password = "<admin_password>" sql_user_management = true ... }
-
To enable database management via SQL, expand the cluster description to include a
sql_user_management
field and asql_database_management
field, both set totrue
, as well as theadmin_password
field containing the password for theadmin
account:resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" { name = "<cluster_name>" ... admin_password = "<admin_password>" sql_database_management = true sql_user_management = true ... }
-
Make sure the settings are correct.
-
In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
-
Run this command:
terraform validate
Terraform will show any errors found in your configuration files.
-
-
Confirm updating the resources.
-
Run this command to view the planned changes:
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.
-
If everything looks correct, apply the changes:
-
Run this command:
terraform apply
-
Confirm updating the resources.
-
Wait for the operation to complete.
-
-
For more information, see this Terraform provider article
Time limits
A Terraform provider sets the timeout for Managed Service for ClickHouse® cluster operations:
- Creating a cluster, including by restoring one from a backup: 60 minutes.
- Editing a cluster: 90 minutes.
- Deleting a cluster: 30 minutes.
Operations exceeding the set timeout are interrupted.
How do I change these limits?
Add the timeouts
block to the cluster description, for example:
resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" {
...
timeouts {
create = "1h30m" # 1 hour 30 minutes
update = "2h" # 2 hours
delete = "30m" # 30 minutes
}
}
-
Get an IAM token for API authentication and save it as an environment variable:
export IAM_TOKEN="<IAM_token>"
-
Use the Cluster.Update method and send the following request, e.g., via cURL
: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.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.adminPassword,configSpec.sqlUserManagement,configSpec.sqlDatabaseManagement", "configSpec": { "adminPassword": "<admin_password>", "sqlUserManagement": <user_management_via_SQL>, "sqlDatabaseManagement": <database_management_via_SQL> } }'
Where:
-
updateMask
: List of parameters to update as a single string, separated by commas.Specify the relevant parameters:
configSpec.adminPassword
: Password of theadmin
account used for management.configSpec.sqlUserManagement
: To enable user management via SQL.configSpec.sqlDatabaseManagement
: To enable database management via SQL.
In our request example, both user and database management via SQL are enabled.
-
configSpec.adminPassword
:admin
password. -
configSpec.sqlUserManagement
: User management via SQL,true
orfalse
. -
configSpec.sqlDatabaseManagement
: Database management via SQL,true
orfalse
. For that, you also need to enable user management through SQL.
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. -
Use the ClusterService.Update call and send the following request, e.g., via gRPCurl
: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 ofpaths[]
strings.Format for listing settings
"update_mask": { "paths": [ "<setting_1>", "<setting_2>", ... "<setting_N>" ] }
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.admin_password", "config_spec.sql_user_management", "config_spec.sql_database_management" ] }, "config_spec": { "admin_password": "<admin_password>", "sql_user_management": <user_management_via_SQL>, "sql_database_management": <database_management_via_SQL> } }' \ mdb.api.cloud.yandex.net:443 \ yandex.cloud.mdb.clickhouse.v1.ClusterService.Update
Where:
-
update_mask
: List of parameters to update as an array ofpaths[]
strings.Specify the relevant parameters:
config_spec.admin_password
: Password of theadmin
account used for management.config_spec.sql_user_management
: To enable user management via SQL.config_spec.sql_database_management
: To enable database management via SQL.
In our request example, both user and database management via SQL are enabled.
-
config_spec.admin_password
:admin
user password. -
config_spec.sql_user_management
: User management via SQL,true
orfalse
. -
config_spec.sql_database_management
: Database management via SQL,true
orfalse
. For that, you also need to enable user management through SQL.
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.
Changing additional cluster settings
-
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 Service settings, change the following additional cluster settings:
-
Backup start time (UTC): Time interval during which the cluster backup starts. Time is specified in 24-hour UTC format. The default time is
22:00 - 23:00
UTC. -
Retention period for automatic backups, days: Retention period for automatic backups, in days. If an automatic backup expires, it is deleted. The default is 7 days. For more information, see Backups.
Changing the retention period affects both new automatic backups and existing backups. For example, the initial retention period was 7 days, and the remaining lifetime of a single automatic backup is 1 day. If the retention period increases to 9 days, the remaining lifetime for this backup will now be 3 days.
-
Maintenance window: Maintenance window settings:
- To enable maintenance at any time, select arbitrary (default).
- To specify the preferred maintenance start time, select by schedule and specify the desired day of the week and UTC hour. For example, you can choose a time when the cluster is least loaded.
Maintenance operations are carried out both on enabled and disabled clusters. They may include updating the DBMS, applying patches, and so on.
-
DataLens access: This option allows you to analyze cluster data in Yandex DataLens.
-
WebSQL access: Enables you to run SQL queries against cluster databases from the Yandex Cloud management console using Yandex WebSQL.
-
Access from Metrica and AppMetrica: This option helps import data from AppMetrica
to a cluster. -
Serverless access: Enable this option to allow cluster access from Yandex Cloud Functions. For more information about setting up access, see the Cloud Functions documentation.
-
Yandex Query access: Enable this option to allow cluster access from Yandex Query. This feature is at the Preview stage.
-
Deletion protection: Manages cluster protection against accidental deletion.
Even with cluster deletion protection enabled, one can still delete a user or database or connect manually and delete the database contents.
-
-
Click Save changes.
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 change additional cluster settings:
-
View the description of the CLI command to update a cluster:
yc managed-clickhouse cluster update --help
-
Run the following command with the list of settings to update:
yc managed-clickhouse cluster update <cluster_name_or_ID> \ --backup-window-start <backup_start_time> \ --backup-retain-period-days <automatic_backup_retention_period> \ --datalens-access=<true_or_false> \ --metrika-access=<true_or_false> \ --serverless-access=<true_or_false> \ --websql-access=<true_or_false> \ --yandexquery-access=<true_or_false> \ --deletion-protection \ --disk-size-autoscaling clickhouse-disk-size-limit=<maximum_storage_size_in_GB>,` `clickhouse-planned-usage-threshold=<threshold_for_scheduled_increase_in_percent>,` `clickhouse-emergency-usage-threshold=<threshold_for_immediate_increase_in_percent>,` `zookeeper-disk-size-limit=<maximum_storage_size_in_GB>,` `zookeeper-planned-usage-threshold=<threshold_for_scheduled_increase_in_percent>,` `zookeeper-emergency-usage-threshold=<threshold_for_immediate_increase_in_percent> \ --maintenance-window type=<maintenance_type>,` `day=<day_of_week>,` `hour=<hour>
You can change the following settings:
--backup-window-start
: The cluster backup start time, set in UTC formatHH:MM:SS
. If the time is not set, the backup will start at 22:00 UTC.
-
--backup-retain-period-days
: Automatic backup retention period, in days. -
--datalens-access
: Enables access from DataLens. The default value isfalse
. For more information about setting up a connection, see Connecting from DataLens. -
--metrika-access
: Enables data import from AppMetrica to your cluster . The default value isfalse
. -
--serverless-access
: Enables cluster access from Yandex Cloud Functions. The default value isfalse
. For more information about setting up access, see Cloud Functionsthis article. -
--websql-access
: Enables SQL queries against cluster databases from the Yandex Cloud management console using Yandex WebSQL. The default value isfalse
. -
--yandexquery-access=true
: Enables cluster access from Yandex Query. This feature is at the Preview stage. The default value isfalse
. -
--deletion-protection
: Cluster protection from accidental deletion,true
orfalse
.Even with cluster deletion protection enabled, one can still delete a user or database or connect manually and delete the database contents.
-
--disk-size-autoscaling
: Automatic storage size increase settings:-
clickhouse-disk-size-limit
: Maximum storage size for a ClickHouse® subcluster, GB. -
clickhouse-planned-usage-threshold
: ClickHouse® subcluster storage utilization threshold for storage to be increased during the next maintenance window, in percent. The default value is0
(automatic increase disabled).The valid values range from
0
to100
. -
clickhouse-emergency-usage-threshold
: ClickHouse® subcluster storage utilization threshold for storage to be increased right away, in percent. The default value is0
(automatic increase disabled).The valid values range from
0
to100
. -
zookeeper-disk-size-limit
: Maximum storage size for a ZooKeeper subcluster, GB. -
zookeeper-planned-usage-threshold
: ZooKeeper subcluster storage utilization threshold for storage to be increased during the next maintenance window, in percent. The default value is0
(automatic increase disabled).The valid values range from
0
to100
. -
zookeeper-emergency-usage-threshold
: ZooKeeper subcluster storage utilization threshold for storage to be increased right away, in percent. The default value is0
(automatic increase disabled).The valid values range from
0
to100
.
Warning
-
If you specify both thresholds for a ClickHouse® subcluster,
clickhouse-emergency-usage-threshold
must not be less thanclickhouse-planned-usage-threshold
. -
If you specify both thresholds for a ZooKeeper subcluster,
zookeeper-emergency-usage-threshold
must not be less thanzookeeper-planned-usage-threshold
. -
When using
clickhouse-planned-usage-threshold
andzookeeper-planned-usage-threshold
, make sure to set up a maintenance window.
Autoscaling settings configured for a ClickHouse® subcluster apply to all existing shards within the subcluster. When adding a new shard, the settings are taken from the oldest shard. These values are not saved in the subcluster configuration and are not displayed in the
yc managed-clickhouse cluster get
command output.To view information about a specific shard, including its autoscaling settings, use this command:
yc managed-clickhouse shards get <shard_name> --cluster-id <cluster_ID>
You can get the cluster ID with the list of clusters in the folder.
You can get the shard name with the list of shards in the cluster.
-
-
--maintenance-window
: Maintenance window settings (including for disabled clusters), wheretype
is the maintenance type:anytime
: At any time (default).weekly
: On a schedule. For this value, also specify the following:day
: Day of week, i.e.,MON
,TUE
,WED
,THU
,FRI
,SAT
, orSUN
.hour
: Hour of day (UTC), from1
to24
.
You can get the cluster ID and name with the list of clusters in the folder.
-
Open the current Terraform configuration file that defines your infrastructure.
For more information about creating this file, see this guide.
-
To change the backup start time, add the
backup_window_start
section to the Managed Service for ClickHouse® cluster description:resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" { ... backup_window_start { hours = <backup_start_hour> minutes = <backup_start_minute> } ... }
-
To enable cluster access from other services and allow running SQL queries from the management console using Yandex WebSQL, edit the values of the appropriate fields in the
access
section:resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" { ... access { data_lens = <access_from_DataLens> metrika = <access_from_Metrica_and_AppMetrica> serverless = <access_from_Cloud_Functions> web_sql = <run_SQL_queries_from_management_console> yandex_query = <access_from_Yandex_Query> } ... }
Where:
-
data_lens
: Access from DataLens,true
orfalse
. -
metrika
: Access from Yandex Metrica and AppMetrica,true
orfalse
. -
serverless
: Access from Cloud Functions,true
orfalse
. -
yandex_query
: Access from Yandex Query,true
orfalse
. -
web_sql
: Execution of SQL queries from the management console,true
orfalse
.
-
-
To set up the maintenance window (for disabled clusters as well), add the
maintenance_window
block to the cluster description:resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" { ... maintenance_window { type = <maintenance_type> day = <day_of_week> hour = <hour> } ... }
Where:
type
: Maintenance type. The possible values include:ANYTIME
: AnytimeWEEKLY
: On a schedule
day
: Day of week for theWEEKLY
type, i.e.,MON
,TUE
,WED
,THU
,FRI
,SAT
, orSUN
.hour
: UTC hour for theWEEKLY
type, from1
to24
.
-
To enable cluster protection against accidental deletion by a user of your cloud, add the
deletion_protection
field set totrue
to your cluster description:resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" { ... deletion_protection = <cluster_deletion_protection> }
Even with cluster deletion protection enabled, one can still delete a user or database or connect manually and delete the database contents.
-
Make sure the settings are correct.
-
In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
-
Run this command:
terraform validate
Terraform will show any errors found in your configuration files.
-
-
Confirm updating the resources.
-
Run this command to view the planned changes:
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.
-
If everything looks correct, apply the changes:
-
Run this command:
terraform apply
-
Confirm updating the resources.
-
Wait for the operation to complete.
-
-
For more information, see this Terraform provider article
Time limits
A Terraform provider sets the timeout for Managed Service for ClickHouse® cluster operations:
- Creating a cluster, including by restoring one from a backup: 60 minutes.
- Editing a cluster: 90 minutes.
- Deleting a cluster: 30 minutes.
Operations exceeding the set timeout are interrupted.
How do I change these limits?
Add the timeouts
block to the cluster description, for example:
resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" {
...
timeouts {
create = "1h30m" # 1 hour 30 minutes
update = "2h" # 2 hours
delete = "30m" # 30 minutes
}
}
-
Get an IAM token for API authentication and save it as an environment variable:
export IAM_TOKEN="<IAM_token>"
-
Use the Cluster.Update method and send the following request, e.g., via cURL
: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.-
Create a file named
body.json
and paste the following code into it:{ "updateMask": "<list_of_settings_to_update>", "configSpec": { "backupWindowStart": { "hours": "<hours>", "minutes": "<minutes>", "seconds": "<seconds>", "nanos": "<nanoseconds>" }, "clickhouse": { "diskSizeAutoscaling": { "plannedUsageThreshold": "<threshold_for_scheduled_increase_in_percent>", "emergencyUsageThreshold": "<threshold_for_immediate_increase_in_percent>", "diskSizeLimit": "<maximum_storage_size_in_bytes>" } }, "zookeeper": { "diskSizeAutoscaling": { "plannedUsageThreshold": "<threshold_for_scheduled_increase_in_percent>", "emergencyUsageThreshold": "<threshold_for_immediate_increase_in_percent>", "diskSizeLimit": "<maximum_storage_size_in_bytes>" } }, "access": { "dataLens": <access_from_DataLens>, "webSql": <run_SQL_queries>, "metrika": <import_data_from_AppMetrica>, "serverless": <access_from_Yandex Cloud Functions>, "dataTransfer": <access_from_Yandex Data Transfer>, "yandexQuery": <access_from_Yandex Query> } }, "maintenanceWindow": { "anytime": {}, "weeklyMaintenanceWindow": { "day": "<day_of_week>", "hour": "<hour_UTC>" } }, "deletionProtection": <cluster_deletion_protection> }
Where:
-
updateMask
: List of parameters to update as a single string, separated by commas. -
configSpec.backupWindowStart
: Backup start time (UTC):hours
: Hours in 24-hour formatminutes
: Minutesseconds
: Secondsnanos
: Nanoseconds
-
configSpec.access
: Settings enabling cluster access from other services and running SQL queries from the management console using Yandex WebSQL:-
dataLens
: Enable access from DataLens,true
orfalse
. The default value isfalse
. For more information about setting up a connection, see Connecting from DataLens. -
webSql
: Enables SQL queries against cluster databases from the Yandex Cloud management console using Yandex WebSQL,true
orfalse
. The default value isfalse
. -
metrika
: Enables data import from AppMetrica to your cluster :true
orfalse
. The default value isfalse
. -
serverless
: Enable access to the cluster from Yandex Cloud Functions,true
orfalse
. The default value isfalse
. For more information about setting up access, see the Cloud Functions documentation. -
dataTransfer
: Enable access to the cluster from Yandex Data Transfer in Serverless mode,true
orfalse
. The default value isfalse
.This will enable you to connect to Yandex Data Transfer running in Kubernetes via a special network. As a result, other operations, e.g., transfer launch and deactivation, will run faster.
-
yandexQuery
: Enable access to the cluster from Yandex Query,true
orfalse
. This feature is at the Preview stage.Default value:false
.
-
-
configSpec.clickhouse.diskSizeAutoscaling
: Automatic storage size increase settings for a ClickHouse® subcluster:-
plannedUsageThreshold
: ClickHouse® subcluster storage utilization threshold for storage to be increased during the next maintenance window, in percent. The default value is0
(automatic increase disabled).The valid values range from
0
to100
. -
emergencyUsageThreshold
: ClickHouse® subcluster storage utilization threshold for storage to be increased right away, in percent. The default value is0
(automatic increase disabled).The valid values range from
0
to100
. -
diskSizeLimit
: Maximum storage size for a ClickHouse® subcluster, in bytes.
Warning
-
If you specify both thresholds,
emergencyUsageThreshold
must not be less thanplannedUsageThreshold
. -
When using
plannedUsageThreshold
, make sure to set up a maintenance window.
Autoscaling settings configured for a ClickHouse® subcluster apply to all existing shards within the subcluster. When adding a new shard, the settings are taken from the oldest shard. These values are not saved in the subcluster configuration.
To view information about a specific shard, including autoscaling settings, use the Cluster.GetShard method and provide the cluster ID and shard name in the request.
You can get the cluster ID with the list of clusters in the folder.
You can get the shard name with the list of shards in the cluster.
-
-
configSpec.zookeeper.diskSizeAutoscaling
: Automatic storage size increase settings for a ZooKeeper subcluster:-
plannedUsageThreshold
: ZooKeeper subcluster storage utilization threshold for storage to be increased during the next maintenance window, in percent. The default value is0
(automatic increase disabled).The valid values range from
0
to100
. -
emergencyUsageThreshold
: ZooKeeper subcluster storage utilization threshold for storage to be increased right away, in percent. The default value is0
(automatic increase disabled).The valid values range from
0
to100
. -
diskSizeLimit
: Maximum storage size for a ZooKeeper subcluster, in bytes.
Warning
-
If you specify both thresholds,
emergencyUsageThreshold
must not be less thanplannedUsageThreshold
. -
When using
plannedUsageThreshold
, make sure to set up a maintenance window.
-
-
maintenanceWindow
: Maintenance window settings (including for disabled clusters). Select one of these options:anytime
: At any time (default).weeklyMaintenanceWindow
: On schedule:day
: Day of week inDDD
format:MON
,TUE
,WED
,THU
,FRI
,SAT
, orSUN
.hour
: Time of day (UTC) inHH
format, from1
to24
.
-
deletionProtection
: Cluster protection from accidental deletion,true
orfalse
. The default value isfalse
.Even with cluster deletion protection enabled, one can still delete a user or database or connect manually and delete the database contents.
-
-
Run this query:
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 '@body.json'
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. -
Use the ClusterService.Update call and send the following request, e.g., via gRPCurl
: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 ofpaths[]
strings.Format for listing settings
"update_mask": { "paths": [ "<setting_1>", "<setting_2>", ... "<setting_N>" ] }
-
Create a file named
body.json
and paste the following code into it:{ "cluster_id": "<cluster_ID>", "update_mask": { "paths": [ <list_of_settings_to_update> ] }, "config_spec": { "backup_window_start": { "hours": "<hours>", "minutes": "<minutes>", "seconds": "<seconds>", "nanos": "<nanoseconds>" }, "clickhouse": { "disk_size_autoscaling": { "planned_usage_threshold": "<threshold_for_scheduled_increase_in_percent>", "emergency_usage_threshold": "<threshold_for_immediate_increase_in_percent>", "disk_size_limit": "<maximum_storage_size_in_bytes>" } }, "zookeeper": { "disk_size_autoscaling": { "planned_usage_threshold": "<threshold_for_scheduled_increase_in_percent>", "emergency_usage_threshold": "<threshold_for_immediate_increase_in_percent>", "disk_size_limit": "<maximum_storage_size_in_bytes>" } }, "access": { "data_lens": <access_from_DataLens>, "web_sql": <run_SQL_queries>, "metrika": <import_data_from_AppMetrica>, "serverless": <access_from_Yandex Cloud Functions>, "data_transfer": <access_from_Yandex Data Transfer>, "yandex_query": <access_from_Yandex Query> } }, "maintenance_window": { "anytime": {}, "weekly_maintenance_window": { "day": "<day_of_week>", "hour": "<hour_UTC>" } }, "deletion_protection": <cluster_deletion_protection> }
Where:
-
update_mask
: List of parameters to update as an array ofpaths[]
strings. -
config_spec.backup_window_start
: Backup start time (UTC):hours
: Hours in 24-hour formatminutes
: Minutesseconds
: Secondsnanos
: Nanoseconds
-
config_spec.access
: Settings enabling cluster access from other services and running SQL queries from the management console using Yandex WebSQL:-
data_lens
: Enable access from DataLens,true
orfalse
. The default value isfalse
. For more information about setting up a connection, see Connecting from DataLens. -
web_sql
: Enables SQL queries against cluster databases from the Yandex Cloud management console using Yandex WebSQL:true
orfalse
. The default value isfalse
. -
metrika
: Enables data import from AppMetrica to your cluster :true
orfalse
. The default value isfalse
. -
serverless
: Enable access to the cluster from Yandex Cloud Functions,true
orfalse
. The default value isfalse
. For more information about setting up access, see the Cloud Functions documentation. -
data_transfer
: Enable access to the cluster from Yandex Data Transfer in Serverless mode,true
orfalse
. The default value isfalse
.This will enable you to connect to Yandex Data Transfer running in Kubernetes via a special network. As a result, other operations, e.g., transfer launch and deactivation, will run faster.
-
yandex_query
: Enable access to the cluster from Yandex Query,true
orfalse
:true
orfalse
. This feature is at the Preview stage.Default value:false
.
-
-
config_spec.clickhouse.disk_size_autoscaling
: Automatic storage size increase settings for a ClickHouse® subcluster:-
planned_usage_threshold
: ClickHouse® subcluster storage utilization threshold for storage to be increased during the next maintenance window, in percent. The default value is0
(automatic increase disabled).The valid values range from
0
to100
. -
emergency_usage_threshold
: ClickHouse® subcluster storage utilization threshold for storage to be increased right away, in percent. The default value is0
(automatic increase disabled).The valid values range from
0
to100
. -
disk_size_limit
: Maximum storage size for a ClickHouse® subcluster, in bytes.
Warning
-
If you specify both thresholds,
emergency_usage_threshold
must not be less thanplanned_usage_threshold
. -
When using
planned_usage_threshold
, make sure to set up a maintenance window.
Autoscaling settings configured for a ClickHouse® subcluster apply to all existing shards within the subcluster. When adding a new shard, the settings are taken from the oldest shard. These values are not saved in the subcluster configuration.
To view information about a specific shard, including its autoscaling settings, use the ClusterService.GetShard method and provide the cluster ID and shard name in the request.
You can get the cluster ID with the list of clusters in the folder.
You can get the shard name with the list of shards in the cluster.
-
-
config_spec.zookeeper.disk_size_autoscaling
: Automatic storage size increase settings for a ZooKeeper subcluster:-
planned_usage_threshold
: ZooKeeper subcluster storage utilization threshold for storage to be increased during the next maintenance window, in percent. The default value is0
(automatic increase disabled).The valid values range from
0
to100
. -
emergency_usage_threshold
: ZooKeeper subcluster storage utilization threshold for storage to be increased right away, in percent. The default value is0
(automatic increase disabled).The valid values range from
0
to100
. -
disk_size_limit
: Maximum storage size for a ZooKeeper subcluster, in bytes.
Warning
-
If you specify both thresholds,
emergency_usage_threshold
must not be less thanplanned_usage_threshold
. -
When using
planned_usage_threshold
, make sure to set up a maintenance window.
-
-
maintenance_window
: Maintenance window settings (including for disabled clusters). Select one of these options:anytime
: At any time (default).weekly_maintenance_window
: On schedule:day
: Day of week inDDD
format:MON
,TUE
,WED
,THU
,FRI
,SAT
, orSUN
.hour
: Time of day (UTC) inHH
format, from1
to24
.
-
deletion_protection
: Cluster protection from accidental deletion,true
orfalse
. The default value isfalse
.Even with cluster deletion protection enabled, one can still delete a user or database or connect manually and delete the database contents.
You can get the cluster ID with the list of clusters in the folder.
-
-
Run this query:
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 @ \ mdb.api.cloud.yandex.net:443 \ yandex.cloud.mdb.clickhouse.v1.ClusterService.Update \ < body.json
-
-
View the server response to make sure your request was successful.
Connection Manager
If you cluster has no integration with Connection Manager, enable Use Connection Manager. It is only available in the management console
The following resources will be created for each database user:
-
Connection Manager connection with information about the database connection.
-
Yandex Lockbox secret with the user password. Storing passwords in Yandex Lockbox ensures their security.
The connection and secret will be created for each new database user. To view all connections, select the Connections tab on the cluster page.
You need the
connection-manager.viewer
role to view connection info. You can use Connection Manager to configure access to connections.Note
You can use Connection Manager and secrets you create there free of charge.
Moving a cluster
- Navigate to the folder dashboard and select Managed Service for ClickHouse.
- Click
to the right of the cluster you want to move. - Select Move.
- Select the folder you want to move your cluster to.
- Click Move.
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 move a cluster:
-
See the description of the CLI command for moving a cluster:
yc managed-clickhouse cluster move --help
-
Specify the destination folder in that command:
yc managed-clickhouse cluster move <cluster_name_or_ID> \ --destination-folder-name=<destination_folder_name>
You can get the cluster ID with the list of clusters in the folder.
-
Open the current Terraform configuration file that defines your infrastructure.
For more information about creating this file, see this guide.
-
In the Managed Service for ClickHouse® cluster description, edit or add the
folder_id
parameter value:resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" { ... folder_id = "<destination_folder_ID>" }
-
Make sure the settings are correct.
-
In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
-
Run this command:
terraform validate
Terraform will show any errors found in your configuration files.
-
-
Confirm updating the resources.
-
Run this command to view the planned changes:
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.
-
If everything looks correct, apply the changes:
-
Run this command:
terraform apply
-
Confirm updating the resources.
-
Wait for the operation to complete.
-
-
For more information, see this Terraform provider article
Time limits
A Terraform provider sets the timeout for Managed Service for ClickHouse® cluster operations:
- Creating a cluster, including by restoring one from a backup: 60 minutes.
- Editing a cluster: 90 minutes.
- Deleting a cluster: 30 minutes.
Operations exceeding the set timeout are interrupted.
How do I change these limits?
Add the timeouts
block to the cluster description, for example:
resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" {
...
timeouts {
create = "1h30m" # 1 hour 30 minutes
update = "2h" # 2 hours
delete = "30m" # 30 minutes
}
}
-
Get an IAM token for API authentication and save it as an environment variable:
export IAM_TOKEN="<IAM_token>"
-
Use the Cluster.Move method and send the following request, e.g., via cURL
: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>:move' \ --data '{ "destinationFolderId": "<destination_folder_ID>" }'
Where
destinationFolderId
is the ID of the destination folder to move your cluster to. You can request this ID with the list of folders in the cloud.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. -
Use the ClusterService.Move call and send the following request, e.g., via gRPCurl
: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>", "destination_folder_id": "<destination_folder_ID>" }' \ mdb.api.cloud.yandex.net:443 \ yandex.cloud.mdb.clickhouse.v1.ClusterService.Move
Where
destination_folder_id
is the ID of the destination folder to move your cluster to. You can request this ID with the list of folders in the cloud.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.
Changing security groups
- 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 Network settings, select security groups for cluster network traffic.
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 edit the list of security groups for your cluster:
-
View the description of the CLI command to update a cluster:
yc managed-clickhouse cluster update --help
-
Specify the security groups in that command:
yc managed-clickhouse cluster update <cluster_name> \ --security-group-ids <list_of_security_group_IDs>
-
Open the current Terraform configuration file that defines your infrastructure.
For more information about creating this file, see Creating clusters.
-
Edit the
security_group_ids
value in the cluster description:resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" { ... security_group_ids = [ <list_of_cluster_security_group_IDs> ] }
-
Make sure the settings are correct.
-
In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
-
Run this command:
terraform validate
Terraform will show any errors found in your configuration files.
-
-
Confirm updating the resources.
-
Run this command to view the planned changes:
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.
-
If everything looks correct, apply the changes:
-
Run this command:
terraform apply
-
Confirm updating the resources.
-
Wait for the operation to complete.
-
-
For more information, see this Terraform provider article
Time limits
A Terraform provider sets the timeout for Managed Service for ClickHouse® cluster operations:
- Creating a cluster, including by restoring one from a backup: 60 minutes.
- Editing a cluster: 90 minutes.
- Deleting a cluster: 30 minutes.
Operations exceeding the set timeout are interrupted.
How do I change these limits?
Add the timeouts
block to the cluster description, for example:
resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" {
...
timeouts {
create = "1h30m" # 1 hour 30 minutes
update = "2h" # 2 hours
delete = "30m" # 30 minutes
}
}
-
Get an IAM token for API authentication and save it as an environment variable:
export IAM_TOKEN="<IAM_token>"
-
Use the Cluster.Update method and send the following request, e.g., via cURL
: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.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": "securityGroupIds", "securityGroupIds": [ <list_of_security_group_IDs> ] }'
Where:
-
updateMask
: List of parameters to update as a single string, separated by commas.Here, we only specified a single parameter,
securityGroupIds
. -
securityGroupIds
: Array of strings. Each string is a security group ID.Warning
The list of security groups assigned to the cluster will be completely overwritten by the list in the
securityGroupIds
parameter.Before running your request, make sure the list includes all the required security group IDs, including existing ones.
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. -
Use the ClusterService.Update call and send the following request, e.g., via gRPCurl
: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 ofpaths[]
strings.Format for listing settings
"update_mask": { "paths": [ "<setting_1>", "<setting_2>", ... "<setting_N>" ] }
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": [ "security_group_ids" ] }, "security_group_ids": [ <list_of_security_group_IDs> ] }' \ mdb.api.cloud.yandex.net:443 \ yandex.cloud.mdb.clickhouse.v1.ClusterService.Update
Where:
-
update_mask
: List of parameters to update as an array ofpaths[]
strings.Here, we only specified a single parameter,
security_group_ids
. -
security_group_ids
: Array of strings. Each string is a security group ID.Warning
The list of security groups assigned to the cluster will be completely overwritten by the list in the
security_group_ids
parameter.Before running your request, make sure the list includes all the required security group IDs, including existing ones.
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.
Warning
You may need to additionally set up security groups to connect to the cluster.
Changing hybrid storage settings
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 change hybrid storage settings:
-
View the description of the CLI command to update a cluster:
yc managed-clickhouse cluster update --help
-
If hybrid storage is disabled in your cluster, enable it:
yc managed-clickhouse cluster update <cluster_name_or_ID> \ --cloud-storage=true
Note
Once enabled, hybrid storage cannot be disabled.
-
Provide a list of settings to update:
yc managed-clickhouse cluster update <cluster_name_or_ID> \ --cloud-storage-data-cache=<file_storage> \ --cloud-storage-data-cache-max-size=<memory_size_in_bytes> \ --cloud-storage-move-factor=<share_of_free_space> \ --cloud-storage-prefer-not-to-merge=<merging_data_parts>
You can change the following settings:
--cloud-storage-data-cache
: Allows you to cache files in cluster storage. This setting is enabled by default (set totrue
).--cloud-storage-data-cache-max-size
: Sets the maximum cache size (in bytes) allocated in cluster storage for files. The default value is1073741824
(1 GB).--cloud-storage-move-factor
: Sets the minimum share of free space in cluster storage. If the actual value is less than this setting value, the data is moved to Yandex Object Storage. The minimum value is0
, the maximum one is1
, and the default one is0.01
.--cloud-storage-prefer-not-to-merge
: Disables data part merges in cluster and object storage. To disable merges, set the parameter totrue
or provide it with no value. To keep merges enabled, set the parameter tofalse
or do not provide it in the CLI command when creating a cluster.
-
Get an IAM token for API authentication and save it as an environment variable:
export IAM_TOKEN="<IAM_token>"
-
Use the Cluster.Update method and send the following request, e.g., via cURL
: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.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": "<list_of_settings_to_update>", "configSpec": { "cloudStorage": { "enabled": <hybrid_storage_use>, "moveFactor": "<share_of_free_space>", "dataCacheEnabled": <temporary_file_storage>, "dataCacheMaxSize": "<maximum_cache_size_for_file_storage>", "preferNotToMerge": <disabling_data_part_merging> } } }'
Where:
-
updateMask
: List of parameters to update as a single string, separated by commas. -
configSpec.cloudStorage
: Hybrid storage settings:-
enabled
: Enable hybrid storage in the cluster if it is disabled,true
orfalse
. Default value:false
(disabled).Note
Once enabled, hybrid storage cannot be disabled.
-
moveFactor
: Minimum share of free space in cluster storage. If the minimum share is below this value, the data will be moved to Yandex Object Storage.Minimum value:
0
; maximum value:1
; default:0.01
. -
dataCacheEnabled
: Allow temporary storage of files in cluster storage,true
orfalse
.Default value:
true
(enabled). -
dataCacheMaxSize
: Maximum cache size (in bytes) allocated in cluster storage for temporary file storage.Default value:
1073741824
(1 GB). -
preferNotToMerge
: Disable merging of data parts in cluster and object storage,true
orfalse
.To disable merging, set to
true
. To leave merging enabled, set tofalse
.
-
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. -
Use the ClusterService.Update call and send the following request, e.g., via gRPCurl
: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 ofpaths[]
strings.Format for listing settings
"update_mask": { "paths": [ "<setting_1>", "<setting_2>", ... "<setting_N>" ] }
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": [ <list_of_settings_to_update> ] }, "config_spec": { "cloud_storage": { "enabled": <hybrid_storage_use>, "move_factor": "<share_of_free_space>", "data_cache_enabled": <temporary_file_storage>, "data_cache_max_size": "<maximum_cache_size_for_file_storage>", "prefer_not_to_merge": <disabling_data_part_merging> } } }' \ mdb.api.cloud.yandex.net:443 \ yandex.cloud.mdb.clickhouse.v1.ClusterService.Update
Where:
-
update_mask
: List of parameters to update as an array ofpaths[]
strings. -
config_spec.cloud_storage
: Hybrid storage settings:-
enabled
: Enable hybrid storage in the cluster if it is disabled,true
orfalse
. Default value:false
(disabled).Note
Once enabled, hybrid storage cannot be disabled.
-
move_factor
: Minimum share of free space in cluster storage. If the minimum share is below this value, the data will be moved to Yandex Object Storage.Minimum value:
0
; maximum value:1
; default:0.01
. -
data_cache_enabled
: Allow temporary storage of files in cluster storage,true
orfalse
.Default value:
true
(enabled). -
data_cache_max_size
: Maximum cache size (in bytes) allocated in cluster storage for temporary file storage.Default value:
1073741824
(1 GB). -
prefer_not_to_merge
: Disable merging of data parts in cluster and object storage,true
orfalse
.To disable merging, set to
true
. To leave merging enabled, set tofalse
.
-
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