Cluster actions

Common tasks for working with ClickHouse clusters

In this section we’ll look at all the actions you can take with ClickHouse clusters through the Altinity Cloud Manager (ACM), expanding on the basics we covered in the ACM introduction.

There are a number of common ClickHouse cluster tasks you’ll likely need to do:

Launching a new Cluster

Launching a new cluster is incredibly easy, and only takes a few minutes. To launch a new ClickHouse cluster, click the LAUNCH CLUSTER button at the top of the Clusters view page: See the Launch Cluster wizard documentation for complete details on the options for creating and configuring a new cluster.

Launch New Cluster

Figure 1 - The LAUNCH CLUSTER button

NOTE: As you would expect, if you have one or more ClickHouse clusters running already, they’ll appear here in place of the “You don’t have any clusters” message.

Locking a cluster

If you’re looking at a particular cluster, there is a lock button at the top of the panel that allows you to prevent any changes to the cluster. Be aware that anyone with appropriate access can lock or unlock the cluster at any time.

To lock or unlock the cluster, simply click the lock button:

Cluster Lock button

Figure 2 - The Lock Cluster button

The button turns red when locked and returns to transparent when unlocked.

The Actions menu

The rest of the items we’ll go through are in the Actions menu, which appears at the bottom of the cluster explorer view or the top of a cluster panel:

The Actions menu

Upgrading a cluster

Launch New Cluster

Clusters can be upgraded to newer versions of ClickHouse. Before you upgrade, we strongly encourage you to open a support ticket with normal priority and label the ticket “Upgrade.”

Select the ClickHouse version to update to. You can select from Altinity Stable Builds or Community Builds. As you choose which type of build you want to use, the dropdown menu below changes to include the latest builds of that type. There is also a Release notes link beneath the menu; clicking that link takes you to the release notes for that release. We also strongly recommend reading the release notes for the version you’re upgrading to.

Cluster Upgrade

Figure 3 - The Upgrade Cluster dialog

Be sure to read any warning messages carefully. If the version you’ve selected will downgrade your cluster by at least one major version, you’re required to acknowledge that before the process will start.

The upgrade process time varies with the size of the cluster, as each server is upgraded individually. This may cause downtime while the cluster is upgraded.

Rescaling a cluster

Launch New Cluster

You may need to change the size and structure of your ClickHouse cluster at some point. Clicking the Rescale menu item displays this dialog:

Cluster Rescale

Figure 4 - The Rescale Cluster dialog

The current properties of your cluster are shown on the left side; you can enter new values or select a new node type on the right. Click OK to rescale the cluster with the new values. As you would expect, the rescaling time varies with the size of the cluster, as each node is rescaled individually.

The rescaling operation takes place one node at a time, so the impact of rescaling should have a minimal impact on the performance of your applications. (Assuming your cluster has more than one replica, of course.)

NOTE: Rescaling a cluster resets its activity schedule to ALWAYS ON. If your cluster is using the RESCALE ON SCHEDULE activity schedule, you’ll see this confirmation message:

Rescale Confirmation dialog

Figure 5 - The Rescale Confirmation dialog

(The text in yellow reads “The cluster is configured for an automatic rescale. The Activity Schedule will be reset after this action.”)

If you rescale the cluster, you’ll need to recreate its activity schedule. See Setting an activity schedule for all the details.

Stopping, resuming, or restarting a cluster

Launch New Cluster
Launch New Cluster

You can stop, resume, or restart a cluster by clicking the appropriate menu item. As you would expect, the text of the first menu item is Stop if the cluster is running and Resume if the cluster is stopped. Depending on the size of your cluster, it may take a few minutes until it is fully stopped, resumed, or restarted.

You’ll see this confirmation dialog when you stop a cluster:

Stop Cluster Confirmation dialog

Figure 6 - The Stop Cluster confirmation dialog

NOTE: Stopping a cluster resets its activity schedule to ALWAYS ON. See Setting an activity schedule for more details on creating activity schedules.

If you are resuming a cluster, you can change the node type used in the cluster:

Resuming a cluster

Figure 7 - The Resume Cluster confirmation dialog

NOTE: Resuming a cluster resets its activity schedule to ALWAYS ON. See Setting an activity schedule for more details on creating activity schedules.

If you are restarting a cluster, you have the option of doing a Hard Cluster Reset, which kills all of the ClickHouse cluster’s Kubernetes pods before restarting the cluster:

Hard cluster reset

Figure 8 - The Cluster Restart confirmation dialog

Finally, be aware that a cluster may be stopped, resumed, or rescaled automatically based on any activity schedule settings you may have configured.

Exporting a cluster’s configuration

Launch New Cluster

The structure of an Altinity Cloud cluster can be exported as JSON. Selecting this menu item creates a JSON file that is downloaded to your machine. As an example, if your cluster is named maddie-byok, the JSON file will be named maddie-byok.json.

Publishing a cluster’s configuration

Launch New Cluster

The Publish Configuration menu item applies any configuration changes you have made to your cluster. This gives you more control over how changes are applied.

This feature is related to the Automatic Publish setting on your environment:

The Automatic Publish setting

Figure 9 - The Automatic Publish environment setting

Automatic publishing is enabled by default. That means any changes to the configuration of any cluster in the environment are automatically applied as they are made in the ACM. However, you (or your administrator) may want more control over how changes are applied. Publish Configuration lets you decide when changes should be applied. (You must have administrator-level access to change an environment’s Automatic Publish option setting.)

If you have configuration changes that haven’t been published yet, you’ll see the PUBLISH button at the top of the cluster view:

The Publish button

Figure 10 - The Publish button

Clicking the button displays the Pending Cluster Updates dialog:

The Pending Cluster Updates dialog

Figure 11 - The Pending Cluster Updates dialog

You can click the arrow icon to see the details of any particular change. Be aware that you can’t modify your changes from this dialog. If you need to modify something, click CANCEL, edit your settings and environment variables as needed, then come back to the Publish Configuration function to continue.

Click CONFIRM to publish the changes.

Working with a cluster’s history

Cluster History

The Cluster Update History view lets you rollback changes that have been made to your cluster:

Cluster History

Figure 12 - The Cluster Update History view

In this example, several cluster settings have been modified. You can click the arrow icon to expand an item and see its details. The highlighted change added the logger/level attribute to the cluster’s configuration.

NOTE: Rolling back an action also rolls back every other action made since the one you’re rolling back. The text for the two actions above the highlighted one are crossed out as a visual reminder.

Launching a replica cluster

Launch New Cluster


Clusters can be replicated easily. A replica can include the same database schema as the original cluster, or it can be launched without the schema.

NOTE: Be aware this a true replica, not a one-time copy. Any changes made to the replica’s data will be replicated back to the source cluster.

This menu item starts a slightly modified version of the Launch Cluster Wizard. The only difference is on the ClickHouse Setup panel:

Replicate the cluster schema

Figure 13 - The modified ClickHouse Setup panel

You have the option to replicate the schema of the existing cluster. With that exception, this version of the Launch Cluster Wizard is identical to the one covered in the Launch Cluster Wizard documentation.

Once you click Launch on the Review & Launch tab at the end of the wizard, the replica cluster will be available within a few minutes.

Creating a backup

Launch New Cluster

Creating a backup is straightforward: simply click the Create Backup item on the ACTIONS menu. You’ll see an informative message like this:

Creating a backup

Figure 14 - The Cluster Backup confirmation dialog

As the dialog points out, backups are stored separately from the cluster, so you can restore your cluster from a backup even if you delete the cluster. Click OK to create the backup.

Restoring a backup

Launch New Cluster


You must have Administrator access to perform this action. See Backing up and Restoring Data in the Administrator Guide for all the details.

Destroying a cluster

Destroy a cluster

When you no longer need a cluster, the entire cluster and all of its data can be destroyed. Enter the name of the cluster and click OK to delete it:

Destroy a cluster

Figure 15 - The Delete Cluster dialog

NOTE: Once destroyed, a cluster cannot be recovered, it must be manually recreated.