Load balancing for ApsaraDB for ClickHouse clusters - ApsaraDB for ClickHouse

ApsaraDB for ClickHouse Community-compatible Edition clusters created after December 1, 2021 include a Classic Load Balancer (CLB) instance by default. The CLB instance provides VPC connectivity, performs health checks on backend nodes, and automatically routes traffic away from unavailable nodes — enabling failover and high availability (HA). Attaching a CLB instance is a paid service. If you no longer need it, release it at any time.

Important

Releasing or reattaching a CLB instance changes the VPC port number. Update the port number in your application after each operation.

How CLB works

CLB status	Behavior
Attached	Binds a domain name to the IP addresses of ClickHouse nodes to provide VPC connection services. Forwards requests among nodes, performs health checks, and isolates unavailable nodes so that traffic is routed only to healthy ones. On single-replica clusters, unhealthy nodes are isolated, but query results may be incomplete if a node is unavailable because data is distributed across nodes. If you use the public endpoint to connect to the cluster, the same CLB instance handles both VPC and public traffic.
Released	VPC connection service is disabled. The cluster performs simple load balancing based on the public endpoint. Health checks are no longer performed at the request routing layer, which may cause requests to be routed to unavailable nodes, resulting in read and write failures.

CLB status

Behavior

Attached

Binds a domain name to the IP addresses of ClickHouse nodes to provide VPC connection services. Forwards requests among nodes, performs health checks, and isolates unavailable nodes so that traffic is routed only to healthy ones. On single-replica clusters, unhealthy nodes are isolated, but query results may be incomplete if a node is unavailable because data is distributed across nodes. If you use the public endpoint to connect to the cluster, the same CLB instance handles both VPC and public traffic.

Released

VPC connection service is disabled. The cluster performs simple load balancing based on the public endpoint. Health checks are no longer performed at the request routing layer, which may cause requests to be routed to unavailable nodes, resulting in read and write failures.

Usage notes

When you attach a CLB instance, the cluster automatically creates a new one. You cannot select an existing CLB instance.
To find the CLB instance for your cluster in the Server Load Balancer console, filter by tag key managedby and tag value equal to your cluster ID.
View the port number for VPC connections in the Network Information section on the Cluster Information page.
The default CLB instance type is slb.s1.small. The bandwidth limit is fixed and cannot be increased by upgrading the instance type. If burst traffic exceeds the limit, packet loss may occur. For higher throughput, use direct connections instead.
For billing details, see Billing of dependent services.

Release a CLB instance

Releasing the CLB instance stops billing within the next hour.

Prerequisites

Before you begin, make sure your Alibaba Cloud account has no overdue payment. If your account has an overdue payment, the release fails and the cluster remains in the CLB Being Released state. Add funds to your account before proceeding.

Steps

Log on to the ApsaraDB for ClickHouse console.
In the upper-left corner, select the region where your cluster is located.
On the Clusters page, click the Clusters of Community-compatible Edition tab.
Click the cluster ID to go to the Cluster Information page.
In the Network Information section, click Release CLB Instance to the right of VPC Endpoint.
In the dialog box, click OK.

The CLB instance is released when the cluster status changes from CLB Being Released to Running.

Important

After the release completes, update the VPC port number in your application. Find the new port number in the Network Information section on the Cluster Information page.

Attach a CLB instance

Attaching a CLB instance restores VPC connection services, health checks, and automatic failover. Attaching a CLB instance is a paid service.

Log on to the ApsaraDB for ClickHouse console.
In the upper-left corner, select the region where your cluster is located.
On the Clusters page, click the Clusters of Community-compatible Edition tab.
Click the cluster ID to go to the Cluster Information page.
In the Network Information section, click Mount CLB Instance to the right of VPC Endpoint.
In the dialog box, click OK.

The CLB instance is attached when the cluster status changes from The CLB instance is being mounted to Running.

Important

After the attachment completes, update the VPC port number in your application. Find the new port number in the Network Information section on the Cluster Information page.

Read from and write to nodes using direct connections

If your read and write throughput exceeds the CLB bandwidth limit, connect directly to nodes instead of using the CLB instance.

Port mapping

Map each CLB port to the corresponding node port:

CLB port	Node port
9000	3003
3306	3003
8443	3006
9004	3005
8123	3002

Steps

Query node IP addresses:
```
SELECT * FROM system.clusters;
```
Connect to the database using a node IP address and the corresponding node port from the table above.
(Optional) If your cluster has multiple replicas or nodes and you are not using a CLB instance, configure load balancing in your application.
Execute read and write operations. SELECT and INSERT operations run on the connected node. Data Definition Language (DDL) operations — CREATE, DROP, and ALTER — are automatically distributed to all nodes as distributed DDL operations.

FAQ

The cluster is stuck in the CLB Being Released state

Check your Alibaba Cloud account for an overdue payment. If an overdue payment exists, the release completes automatically after you add funds to your account.