Altinity.Cloud allows administrators to manage clusters, users, and keep control of their ClickHouse environments with a few clicks. Monitoring tools are provided so you can keep track of everything in your environment to keep on top of your business.
This is the multi-page printable view of this section. Click here to print.
Administrator Guide
- 1: Clusters
- 1.1: View Cluster Details
- 1.2: Cluster Actions
- 1.2.1: Upgrade Cluster
- 1.2.2: Rescale Cluster
- 1.2.3: Stop and Start a Cluster
- 1.2.4: Export Cluster Settings
- 1.2.5: Replicate a Cluster
- 1.2.6: Destroy Cluster
- 1.3: Cluster Settings
- 1.4: Configure Cluster
- 1.4.1: How to Configure Cluster Settings
- 1.4.2: How to Configure Cluster Profiles
- 1.4.3: How to Configure Cluster Users
- 1.5: Launch New Cluster
- 1.6: Cluster Alerts
- 1.7: Cluster Health Check
- 1.8: Cluster Monitoring
- 1.9: Cluster Logs
- 2: Access Control
1 - Clusters
ClickHouse databases are managed through clusters, which harness the power of distributed processing to quickly deliver results on even the most complex and data intensive queries.
Altinity.Cloud users can create their own ClickHouse Clusters tailored to their organization’s needs.
1.1 - View Cluster Details
Cluster Details Page
Once a cluster has been launched, its current operating details can be viewed by selecting the cluster from the Clusters View. This displays the Cluster Details page. From the Cluster Dashboard page, select Nodes to view the Nodes Summary page.
From the Cluster Details page, users can perform the following:

- A: Manage the cluster’s:
- Actions
- Configuration
- Tables and structure with Explore
- Alerts
- View the Cluster’s Logs
- B: Check Cluster Health.
- C: View the cluster’s Access Point.
- D: Monitor the Cluster and its Queries.
- E: View summary details for the Cluster or Node. Select Nodes to view details on the cluster’s Nodes.
Nodes Summary
The Nodes Summary Page displays all nodes that are part of the selected cluster. From this page the following options and information is available:
- The Node Summary that lists:
- Endpoint: The connection settings for this node. See Node Connection.
- Details and Node View: Links to the Node Dashboard and Node Metrics.
- Version: The ClickHouse version running on this node.
- Type: The processor setting for the node.
- Node Storage: Storage space in GB available.
- Memory: RAM memory allocated for the node.
- Availability Zone: Which AWS Availability Zone the node is hosted on.
- Select Node View or View for the specific node to access the Node DashboardNode Metrics, and Node Schema sections.

Node Connection
The Node Connection Details shows how to connect from various clients, including the clickhouse-client
, JDBC drivers, HTTPS, and Python. Unlike the Cluster Access Point, this allows a connection directly to the specific node.

Node Dashboard
From the Node Dashboard Page users can:

- A: Manage the node’s:
- Tables and structure with Explore
- View the Node’s Logs
- B: Check the node’s health.
- C: View summary details node, it’s Metrics and its Schema.
- D: Perform Node Actions.
Node Metrics
Node Metrics provides a breakdown of the node’s performance, such as CPU data, active threads, etc.
Node Schema
The Node Schema provides a view of the databases’ schema and tables. For more information on how to interact with a Node by submitting queries, viewing the schema of its databases and tables, and viewing process, see the Cluster Explore Guide.
Node Actions
The following actions can be performed on a Node:
- Delete: Removes the Node from the cluster.
1.2 - Cluster Actions
Launched clusters can be have different actions applied to them based on your needs.
1.2.1 - Upgrade Cluster
Clusters can be upgraded to versions of ClickHouse other than the one your cluster is running.
When upgrading to a ClickHouse Altinity Stable Build, review the release notes for the version that you are upgrading to.
How to Upgrade an Altinity Cloud Cluster
To upgrade a launched cluster:
-
Select Actions for the cluster to upgrade.
-
Select Upgrade.
-
Select the ClickHouse version to upgrade to.
-
Select Upgrade to start the process.
The upgrade process completion time varies with the size of the cluster, as each server is upgraded individually. This may cause downtime while the cluster is upgraded.
1.2.2 - Rescale Cluster
The size and structure of the cluster may need to be altered after launching based on your organization’s needs. The following settings can be rescaled:
- Number of Shards
- Number of Replicas
- Node Type
- Node Storage
- Number of Volumes
- Apply to new nodes only: This setting will only effect nodes created from this point forward.
See Cluster Settings for more information.
How to Rescale a Cluster
To rescale a cluster:
-
Select Actions for the cluster to rescale.
-
Select Rescale.
-
Set the new values of the cluster.
-
Click OK to begin rescaling.
Depending on the size of the cluster, this may take several minutes.
1.2.3 - Stop and Start a Cluster
To stop an launched cluster, or start a stopped cluster:
- From either the Clusters View or the Cluster Details Page, select Actions.
- If the cluster is currently running, select Stop to halt its operations.
- If the cluster has been stopped, select Start to restart it.
Depending on the size of your cluster, it may take a few minutes until it is fully stopped or is restarted. To access the health and availability of the cluster, see Cluster Health or the Cluster Availability.
1.2.4 - Export Cluster Settings
The structure of an Altinity Cloud cluster can be exported as JSON. For details on the cluster’s settings that are exported, see Cluster Settings.
To export a cluster’s settings to JSON:
- From either the Clusters View or the Cluster Details Page, select Actions, then select Export.
- A new browser window will open with the settings for the cluster in JSON.
1.2.5 - Replicate a Cluster
Clusters can be replicated with the same or different settings. These can include the same database schema as the replicated cluster, or launched without the schema. This may be useful to create a test cluster, then launch the production cluster with different settings ready for production data.
For complete details on Altinity.Cloud clusters settings, see Cluster Settings.
To create a replica of an existing cluster:
- From either the Clusters View or the Cluster Details Page, select Actions, then select Launch a Replica Cluster.
- Enter the desired values for Resources Configuration.
-
To replicate the schema of the source directory, select Replicate Schema.
-
Click Next to continue.
-
- High Availability Configuration, and Connection Configuration.
- Each section must be completed in its entirety before moving on to the next one.
- In the module Review & Launch, verify the settings are correct. When finished, select Launch.
Depending on the size of the new cluster it will be available within a few minutes. To verify the health and availability of the new cluster, see Cluster Health or the Cluster Availability.
1.2.6 - Destroy Cluster
When a cluster is no longer required, the entire cluster and all of its data can be destroyed.
- IMPORTANT NOTE: Once destroyed, a cluster can not be recovered. It must be manually recreated.
To destroy a cluster:
-
From either the Clusters View or the Cluster Details Page, select Actions, then select Destroy.
-
Enter the cluster name, then select OK to confirm its deletion.
1.3 - Cluster Settings
ClickHouse Clusters hosted on Altinity.Cloud have the following structural attributes. These determine options such as the version of ClickHouse installed on them, how many replicas, and other important features.
Name | Description | Values |
---|---|---|
Cluster Name | The name for this cluster. It will be used for the hostname of the cluster. | Cluster names must be DNS compliant. This includes:
|
Node Type | Determines the number of CPUs and the amount of RAM used per node. | The following Node Types are sample values, and may be updated at any time:
|
Node Storage | The amount of storage space available to each node, in GB. | |
Number of Volumes | Storage can be split across multiple volumes. The amount of data stored per node is the same as set in Node Storage, but it split into multiple volumes. Separating storage into multiple volumes can increase query performance. |
|
Volume Type | Defines the Amazon Web Services volume class. Typically used to determine whether or not to encrypt the columns. | Values:
|
Number of Shards | Shards represent a set of nodes. Shards can be replicated to provide increased availability and computational power. | |
ClickHouse Version | The version of the ClickHouse database that will be used on each node. To run a custom ClickHouse container version, specify the Docker image to use.
|
Currently available options:
|
ClickHouse Admin Name | The name of the ClickHouse administrative user. | Set to admin by default. Can not be changed. |
ClickHouse Admin Password | The password for the ClickHouse administrative user. | |
Data Replication | Toggles whether shards will be replicated. When enabled, Zookeeper is required to manage the shard replication process. | Values:
|
Number of Replicas | Sets the number of replicas per shard. Only enabled if Data Replication is enabled. | |
Zookeeper Configuration | When Data Replication is set to Enabled, Zookeeper is required. This setting determines how Zookeeper will run and manage shard replication. The Zookeeper Configuration mainly sets how many Zookeeper nodes are used to manage the shards. More Zookeeper nodes increases the availability of the cluster. |
Values:
|
Zookeeper Node Type | Determines the type of Zookeeper node. | Defaults to default and can not be changed. |
Node Placement | Sets how nodes are distributed via Kubernetes. Depending on your situation and how robust you want your replicas and clusters. | Values:
|
Enable Backups | Backs up the cluster. These can be restored in the event data loss or to roll back to previous versions. | Values:
|
Backup Schedule | Determines how often the cluster will be backed up. | Defaults to Daily |
Number of Backups to keep | Sets how many backups will be stored before deleting the oldest one | Defaults to 5. |
Endpoint | The Access point Domain Name. | This is hard set by the name of your cluster and your organization. |
Use TLS | Sets whether or not to encrypt external communications with the cluster to TLS. | Default to Enabled and can not be changed. |
Load Balancer Type | The load balancer manages communications between the various nodes to ensure that nodes are not overwhelmed. | Defaults to Altinity Edge Ingress |
Protocols | Sets the TCP ports used in external communications with the cluster. | Defaults to ClickHouse TCP port 9440 and HTTP port 8443 . |
1.4 - Configure Cluster
Once a cluster has been launched, it’s configuration can be updated to best match your needs.
1.4.1 - How to Configure Cluster Settings
Cluster settings can be updated from the Clusters View or from the Cluster Details by selecting Configure > Settings.
- IMPORTANT NOTE: Changing a cluster’s settings will require a restart of the entire cluster.
Note that some settings are locked - their values can not be changed from this screen.

How to Set Troubleshooting Mode
Troubleshooting mode prevents your cluster from auto-starting after a crash. To update this setting:
- Toggle Troubleshooting Mode either On or Off.
How to Edit an Existing Setting
To edit an existing setting:
- Select the menu on the left side of the setting to update.
- Select Edit.
- Set the following:
- Setting Type.
- Name
- Value
- Select OK to save the setting.

How to Add a New Setting
To add a new setting to your cluster:
- Select Add Setting.
- Set the following:
- Setting Type.
- Name
- Value
- Select OK to save the setting.

How to Delete an Existing Setting
To delete an existing setting:
- Select the menu on the left side of the setting to update.
- Select OK.
- Select Remove to confirm removing the setting.

1.4.2 - How to Configure Cluster Profiles
Cluster profiles allow you to set the user permissions and settings based on their assigned profile.
The Cluster Profiles can be accessed from the Clusters View or from the Cluster Details by selecting Configure > Settings.

Add a New Profile
To add a new cluster profile:
- From the Cluster Profile View page, select Add Profile.
- Provide profile’s Name and Description, then click OK.
Edit an Existing Profile
To edit an existing profile:
- Select the menu to the left of the profile to update and select Edit, or select Edit Settings.
- To add a profile setting, select Add Setting and enter the Name and Value, then click OK to store your setting value.
- To edit an existing setting, select the menu to the left of the setting to update. Update the Name and Value, then click OK to store the new value.
Delete an Existing Profile
To delete an existing profile:
- Select the menu to the left of the profile to update and select Delete.
- Select OK to confirm the profile deletion.
1.4.3 - How to Configure Cluster Users
The cluster’s Users allow you to set one or more entities who can access your cluster, based on their Cluster Profile.
Cluster users can be updated from the Clusters View or from the Cluster Details by selecting Configure > Users.

How to Add a New User
To add a new user to your cluster:
-
Select Add User
-
Enter the following:
- Login: the name of the new user.
- Password and Confirm Password: the authenticating credentials for the user. Th
- Networks: The networks that the user can connect from. Leave as 0.0.0.0/0 to allow access from all networks.
- Databases: Which databases the user can connect to. Leave empty to allow access all databases.
- Profile: Which profile settings to apply to this user.
-
Select OK to save the new user.
How to Edit a User
To edit an existing user:
- Select the menu to the left of the user to edit, then select Edit.
- Enter the following:
- Login: the new name of the user.
- Password and Confirm Password: the authenticating credentials for the user. Th
- Networks: The networks that the user can connect from. Leave as 0.0.0.0/0 to allow access from all networks.
- Databases: Which databases the user can connect to. Leave empty to allow access all databases.
- Profile: Which profile settings to apply to this user.
- Select OK to save the updated user user.
How to Delete a User
- Select the menu to the left of the user to edit, then select Delete.
- Select OK to verify the user deletion.
1.5 - Launch New Cluster
Launching a new ClickHouse Cluster is incredibly easy, and only takes a few minutes. For those looking to create their first ClickHouse cluster with the minimal steps, see the Quick Start Guide. For complete details on Altinity.Cloud clusters settings, see Cluster Settings.
To launch a new ClickHouse cluster:
-
From the Clusters View page, select Launch Cluster. This starts the Cluster Launch Wizard.
-
Enter the desired values for Resources Configuration, High Availability Configuration, and Connection Configuration.
- Each section must be completed in its entirety before moving on to the next one.
-
In the module Review & Launch, verify the settings are correct. When finished, select Launch.
Within a few minutes, the new cluster will be ready for your use and display that all health checks have been passed.
1.6 - Cluster Alerts
The Cluster Alerts module allows users to set up when they are notified for a set fo events. Alerts can either be a popup, displaying the alert when the user is logged into Altinity.Cloud, or email so they can receive an alert even when they are not logged into Altinty.Cloud.
To set which alerts you receive:
-
From the Clusters view, select the cluster to for alerts.
-
Select Alerts.
-
Add the Email address to send alerts to.
-
Select whether to receive a Popup or Email alert for the following events:
- ClickHouse Version Upgrade: Alert triggered when the version of ClickHouse that is installed in the cluster has a new update.
- Cluster Rescale: Alert triggered when the cluster is rescaled, such as new shards added.
- Cluster Stop: Alert triggered when some event has caused the cluster to no longer running.
- Cluster Resume: Alert triggered when a cluster that was stopped has resumed operations.
1.7 - Cluster Health Check
From the Clusters View, you can see the health status of your cluster and its nodes at a glance.
How to Check Node Health
The quick health check of your cluster’s nodes is displayed from the Clusters View. Next to the cluster name is a summary of your nodes’ statuses, indicating the total number of nodes and how many nodes are available.

How to Check Cluster Health
The overall health of the cluster is shown in the Health row of the cluster summary, showing the number of health checks passed.

Click checked passed to view a detailed view of the cluster’s health.
How to View a Cluster’s Health Checks
The cluster’s Health Check module displays the status of the following health checks:
- Access point availability check
- Distributed query check
- Zookeeper availability check
- Zookeeper contents check
- Readonly replica check
- Delayed inserts check
To view details on what queries are used to verify the health check, select the caret for each health check.

1.8 - Cluster Monitoring
Altinity.Cloud integrates Grafana into its monitoring tools. From a cluster, you can quickly access the following monitoring views:
- Cluster Metrics
- Queries
- Logs
How to Access Cluster Metrics
To access the metrics views for your cluster:
- From the Clusters view, select the cluster to monitor.
- From Monitoring, select the drop down View in Grafana and select from one of the following options:
- Cluster Metrics
- Queries
- Logs
- Each metric view opens in a separate tab.
Cluster Metrics
Cluster Metrics displays how the cluster is performing from a hardware and connection standpoint.

Some of the metrics displayed here include:
- DNS and Distributed Connection Errors: Displays the rate of any connection issues.
- Select Queries: The number of select queries submitted to the cluster.
- Zookeeper Transactions: The communications between the zookeeper nodes.
- ClickHouse Data Size on Disk: The total amount of data the ClickHouse database is using.
Queries
The Queries monitoring page displays the performance of clusters, including the top requests, queries that require the most memory, and other benchmarks. This can be useful in identifying queries that can cause performance issues and refactoring them to be more efficient.

Log Metrics
The Log monitoring page displays the logs for your clusters, and allows you to make queries directly on them. If there’s a specific detail you’re trying to iron out, the logs are the most granular way of tracking down those issues.

1.9 - Cluster Logs
Altinity.Cloud provides the cluster log details so users can trace down specific issues or performance bottlenecks.
To access a cluster’s logs:
- From the Clusters view, select the cluster to for alerts.
- Select Logs.
- From the Log Page, you can display the number of rows to view, or filter logs by specific text.
- To download the logs, select the download icon in the upper right corner (A).
- To refresh the logs page, select the refresh icon (B).

The following logs are available:
- ACM Logs: These logs are specific to Altinity.Cloud issues and include the following:
- System Log: Details the system actions such as starting a cluster, updating endpoints, and other details.
- API Log: Displays updates to the API and activities.
- ClickHouse Logs: Displays the Common Log that stores ClickHouse related events. From this view a specific host can be selected form the dropdown box.
- Backup Logs: Displays backup events from the
clickhouse-backup
service. Log details per cluster host can be selected from the dropdown box. - Operator Logs: Displays logs from the Altinity Kubernetes Operator service, which is used to manage cluster replication cluster and communications in the Kubernetes environment.
2 - Access Control
Altinity.Cloud provides role based access control. Depending the role granted to an Altinity.Cloud Account, they can assign other Altinity.Cloud accounts roles and grant permissions to access organizations, environments, or clusters.
2.1 - Role Based Access and Security Tiers
Access to ClickHouse data hosted in Altinity.Cloud is controlled through a combination of security tiers and account roles. This allows companies to tailor access to data in a way that maximizes security while still allowing ease of access.
Security Tiers
Altinity.Cloud groups sets of clusters together in ways that allows companies to provide Accounts access only to the clusters or groups of clusters that they need to.
Altinity.Cloud groups clusters into the following security related tiers:

- Nodes: The most basic level - an individual ClickHouse database and tables.
- Clusters: These contain one or more nodes provide ClickHouse database access.
- Environments: Environments contain one or more clusters.
- Organizations: Organizations contain one or more environments.
Account access is controlled by assigning an account a single role and a security tier depending on their role. A single account can be assigned to multiple organizations, environments, multiple clusters in an environment, or a single cluster depending on their account role.
Account Roles
The actions that can be taken by Altinity.Cloud accounts is based on the role they are assigned. The following roles and their actions based on the security tier is detailed in the table below:
Role | Environment | Cluster | |
---|---|---|---|
orgadmin | Create, Edit, and Delete environments that they create, or are assigned to, within the assigned organizations. Administrate Accounts associated with environments they are assign to. |
Create, Edit, and Delete clusters within environments they create or assigned to in the organization. | |
envadmin | Access assigned environments. | Create, Edit, and Delete clusters within environments they are assigned to in the organization. | |
envuser | Access assigned environments. | Access one or more clusters the account is specifically assigned to. |
The account roles are tied into the security tiers, and allow an account to access multiple environment and clusters depending on what type of tier they are assigned to.
For example, we may have the following situation:
- Accounts
peter
,paul
, andmary
andjessica
are all members of the organizationHappyDragon
. HappyDragon
has the following environments:HappyDragon_Dev
andHappyDragon_Prod
, each with the clustersmarketing
,sales
, andops
.
The accounts are assigned the following roles and security tiers:
Account | Role | Organization | Environments | Clusters |
---|---|---|---|---|
mary | orgadmin | HappyDragon |
HappyDragon_Prod |
* |
peter | envadmin | HappyDragon |
HappyDragon_Dev |
* |
jessica | envadmin | HappyDragon |
HappyDragon_Prod , HappyDragon_Dev |
* |
paul | envuser | HappyDragon |
HappyDragon_Prod |
marketing |
In this scenario, mary
has the ability to access the environment HappyDragon_Prod
, or can create new environments and manage them and any clusters within them. However, she is not able to edit or access HappyDragon_Dev
or any of its clusters.
- Both
peter
andjessica
have the ability to create and remove clusters within their assigned environments.peter
is able to modify the clusters in the environmentHappyDragon_Dev
.jessica
can modify clusters in both environments.
paul
can only access the clustermarketing
in the environmentHappyDragon_Prod
.
2.2 - Account Management
Altinity.Cloud accounts with the role orgadmin are able to create new Altinity.Cloud accounts and associate them with organizations, environments, and one or more clusters depending on their role. For more information on roles, see Role Based Access and Security Tiers.
Account Page
The Account Page displays all accounts assigned to the same Organization and Environments as the logged in account.
For example: the accounts mario
, luigi
, and peach
and todd
are members of the organizations MushroomFactory
and BeanFactory
as follows:
Account | Role | Organization: MushroomFactory | Organization: BeanFactory |
---|---|---|---|
peach | orgadmin | * | |
mario | orgadmin | * | |
luigi | envuser | * | |
todd | envuser | * |
peach
will be able to see their account andtodd
in the Account Page, while accountsmario
andluigi
will be hidden from them.mario
will be able to see their account andluigi
.
Access Accounts
To access the accounts that are assigned to the same Organizations and Environments as the logged in user with the account role orgadmin:
- Login to Altinity.Cloud with an account granted the orgadmin role.
- From the left navigation panel, select Accounts.
- All accounts that are in the same Organizations and Environments as the logged in account will be displayed.
Account Details
Accounts have the following details that can be set by an account with the orgadmin role:
- Common Information:
- Name: The name of the account.
- Email (Required): The email address of the account. This will be used to login, reset passwords, notifications, and other uses. This must be a working email for these functions to work.
- Password: The password for the account. Once a user has authenticated to the account, they can change their password.
- Confirm Password: Confirm the password for the account.
- Role (Required): The role assigned to the account. For more information on roles, see Role Based Access and Security Tiers.
- Organization: The organization assigned to the account. Note that the
orgadmin
can only assign accounts the same organizations that theorgadmin
account also belongs to. - Suspended: When enabled, this prevents the account from logging into Altinity.Cloud.
- Environment Access:
- Select the environments that the account will require access to. Note that the
orgadmin
can only assign accounts the same environments that theorgadmin
account also belongs to.
- Select the environments that the account will require access to. Note that the
- Cluster Access:
- This is only visible if the Role is set to envuser. This allows one or more clusters in the environments the new account was assigned to in Environmental Access to be accessed by them.
- API Access:
- Allows the new account to make API calls from the listed domain names.
Account Actions
Create Account
orgadmin
accounts can create new accounts and assign them to the same organization and environments they are assigned to. For example, continuing the scenario from above, if account peach
is assigned to the organization MushroomFactory
and the environments MushroomProd
and MushroomDev
, they can assign new accounts to the organization MushroomFactory
, and to the environments MushroomProd
or MushroomDev
or both.
To create a new account:
-
Login to Altinity.Cloud with an account granted the orgadmin role.
-
From the left navigation panel, select Accounts.
-
Select Add Account.
-
Set the fields as listed in the Account Details section.
-
Once all settings are completed, select Save. The account will be able to login with the username and password, or if their email address is registered through Google, Auth0.
Edit Account
- Login to Altinity.Cloud with an account granted the orgadmin role.
- From the left navigation panel, select Accounts.
- From the left hand side of the Accounts table, select the menu icon for the account to update and select Edit.
- Update the fields as listed in the Account Details section.
- When finished, select Save.
Suspend Account
Instead of deleting an account, setting an account to Suspended may be more efficient to preserve the accounts name and other settings. A suspended account is unable to login to Altinity.Cloud. This includes directly logging through a browser and API calls made under the account.
To suspend or activate an account:
- Login to Altinity.Cloud with an account granted the orgadmin role.
- From the left navigation panel, select Accounts.
- From the left hand side of the Accounts table, select the menu icon for the account to update and select Edit.
- To suspend an account, toggle Suspended to on.
- To activate a suspended account, toggle Suspended to off.
- When finished, select Save.
Delete Account
Accounts can be deleted which removes all information on the account. Clusters and environments created by account will remain.
To delete an existing account:
- Login to Altinity.Cloud with an account granted the orgadmin role.
- From the left navigation panel, select Accounts.
- From the left hand side of the Accounts table, select the menu icon for the account to update and select Delete.
- Verify the account is to be deleted by selecting OK.