Migrating a cluster from v1 to v2

Before you get started with the migration, review the changes.

To migrate a cluster from resource v1 (yandex_mdb_clickhouse_cluster) to resource v2 (yandex_mdb_clickhouse_cluster_v2):

1. Update the Terraform configuration.
2. Save the cluster ID.
3. Remove the old resource from state.
4. Import the existing resource into the new one.
5. Optionally, import databases and users.
6. Review the planned changes.
7. Apply the changes.

Update the Terraform configurationUpdate the Terraform configuration

1. Apply all syntax changes from the table below:

   v1 (section syntax)	v2 (assignment syntax)
   clickhouse { }	clickhouse = { }
   zookeeper { }	zookeeper = { }
   access { }	access = { }
   cloud_storage { }	cloud_storage = { }
   backup_window_start { }	backup_window_start = { }
   clickhouse.config.kafka { }	kafka = { } (inside config)
   clickhouse.config.rabbitmq { }	rabbitmq = { } (inside config)
   clickhouse.config.compression { } (repeat section)	compression = [{ method = "LZ4", ... }]
   host { } (repeat section)	hosts = { "key" = { } }
   shard { } (repeat section)	shards = { "shard1" = { } }

2. Set keys for your hosts.

Save the cluster IDSave the cluster ID

1. Run this command:

   terraform state show yandex_mdb_clickhouse_cluster.main
   

2. Copy the id value from the output for later.

Remove the old resource from stateRemove the old resource from state

Run this command:

terraform state rm yandex_mdb_clickhouse_cluster.main

Import the existing resource into the new oneImport the existing resource into the new one

Run this command:

terraform import yandex_mdb_clickhouse_cluster_v2.main <cluster_ID>

Use the id value you got earlier in the command.

After the import, the hosts’ FQDNs will be used as their keys in state, e.g., "rc1a-abc.mdb.yandexcloud.net".

Optionally, import databases and usersOptionally, import databases and users

If database {} or user {} were previously a part of the cluster resource and now are represented by separate resources, import them:

terraform import 'yandex_mdb_clickhouse_database.mydb' "<cluster_ID>:<DB_name>"
terraform import 'yandex_mdb_clickhouse_user.myuser'   "<cluster_ID>:<username>"

Review the planned changesReview the planned changes

Run this command:

terraform plan

You will see a list of resources and their properties. This is a verification step: no resources will be created. Terraform will show any errors detected in the configuration.

In plan, all hosts may appear as + and -. While this may look alarming, it is safe for matching hosts to apply the changes.

The provider matches hosts in three steps:

1. Same key in plan and state: Host remains as-is, no action required.
2. Full match by zone, subnet_id, type, shard_name, and assign_public_ip: The state key is renamed to the plan key; the host itself is not affected.
3. Partial match by zone, FQDN, shard_name, and subnet_id: The state key is renamed to the plan key; an update may be required, e.g., assign_public_ip.

Hosts in plan use short keys, such as "c1", "k1". If zone, subnet, type, and shard match, the second step will start: the keys will be renamed without any actual changes to the hosts.

Apply the changesApply the changes

1. To create resources, run the command:

   terraform apply
   

2. Confirm creating the resources by typing yes and pressing Enter.

   Terraform will create all the required resources. You can check the new resources and their settings in the management console.

In case of errors, read Migration errors.

Useful linksUseful links

• Updates in a v2 cluster