Merge pull request #2627 from DougAnsonAustinTX/clickhouse_LP_techreview_updates

ClickHouse on GCP LP techrevriew updates

Author: jasonrandrews

content/learning-paths/servers-and-cloud-computing/clickhouse-gcp/_index.md

@@ -1,6 +1,10 @@
 ---
 title: Deploy ClickHouse on Google Cloud C4A (Arm-based Axion VMs)
 
+draft: true
+cascade:
+    draft: true
+    
 minutes_to_complete: 30
 
 who_is_this_for: This learning path is intended for software developers deploying and optimizing ClickHouse on Linux/Arm64 environments, specifically using Google Cloud C4A virtual machines powered by Axion processors.

content/learning-paths/servers-and-cloud-computing/clickhouse-gcp/baseline.md

@@ -165,4 +165,10 @@ Query id: b3db69f8-c885-419f-9900-53d258f0b996
 Peak memory usage: 785.05 KiB.
 ```
 
+Exit the client:
+
+```console
+exit;
+```
+
 The baseline tests confirm that ClickHouse is stable, functional, and performing efficiently on the Arm64 VM. With core operations validated, the setup is now ready for detailed performance benchmarking.

content/learning-paths/servers-and-cloud-computing/clickhouse-gcp/benchmarking.md

@@ -249,17 +249,7 @@ localhost:9000, queries: 5, QPS: 20.935, RPS: 10467305.309, MiB/s: 79.859, resul
 - **Result RPS / Result MiB/s:** Reflects the size and rate of returned query results. Low values are expected for aggregate queries like `COUNT(*)`.
 - **Insert Benchmark Metrics:** Write tests measure ingestion speed and stability, where consistent latency indicates reliable bulk insert performance.
 
-### Benchmark summary on x86_64
-To compare the benchmark results, the following results were collected by running the same benchmark on an `x86 - c4-standard-4` (4 vCPUs, 15 GB Memory) x86_64 VM in GCP, running SUSE:
-
-| Test Category           | Test Case      | Query / Operation                                                                  | Iterations | Concurrency | QPS    | Rows / sec (RPS) | Throughput (MiB/s) | p50 Latency | p95 Latency | p99 Latency |
-| ----------------------- | -------------- | ---------------------------------------------------------------------------------- | ---------- | ----------- | ------ | ---------------- | ------------------ | ----------- | ----------- | ----------- |
-| Read                    | Filtered COUNT | `SELECT COUNT(*) FROM bench.hits WHERE url LIKE '/page/%'`                         | 10         | 1           | 63.22  | 63.22 M          | 958.68             | 4 ms        | 6 ms        | 6 ms        |
-| Read / Aggregate        | GROUP BY       | `SELECT url, COUNT(*) FROM bench.hits GROUP BY url`                                | 10         | 2           | 67.23  | 67.23 M          | 1019.43            | 7 ms        | 8 ms        | 8 ms        |
-| Read (High Concurrency) | Filtered COUNT | `SELECT COUNT(*) FROM bench.hits WHERE user_id % 10 = 0`                           | 20         | 8           | 102.54 | 102.54 M         | 782.31             | 23 ms       | 54 ms       | 60 ms       |
-| Write                   | Bulk Insert    | `INSERT INTO bench.hits SELECT now(), rand64(), '/benchmark' FROM numbers(500000)` | 5          | 4           | 22.09  | 11.04 M          | 84.25              | 80 ms       | 81 ms       | 81 ms       |
-
-### Benchmark summary on Arm64
+### Benchmark summary
 Results from the earlier run on the `c4a-standard-4` (4 vCPU, 16 GB memory) Arm64 VM in GCP (SUSE):
 
 | Test Category           | Test Case      | Query / Operation                      | Iterations | Concurrency |   QPS | Rows / sec (RPS) | Throughput (MiB/s) | p50 Latency | p95 Latency | p99 Latency |
@@ -269,8 +259,6 @@ Results from the earlier run on the `c4a-standard-4` (4 vCPU, 16 GB memory) Arm6
 | Read (High Concurrency) | Filtered COUNT | `COUNT(*) WHERE user_id % 10 = 0`      |         20 |           8 | 99.72 |          99.72 M |             760.83 |       29 ms |       63 ms |       78 ms |
 | Write                   | Bulk Insert    | `INSERT SELECT … FROM numbers(500000)` |          5 |           4 | 20.94 |          10.47 M |              79.86 |       68 ms |       73 ms |       73 ms |
 
-### ClickHouse Benchmark comparison insights
-
 - **High Read Throughput:** Simple filtered reads and aggregations achieved over **63–67 million rows/sec**, demonstrating strong scan and aggregation performance on Arm64.
 - **Scales Under Concurrency:** At higher concurrency (8 clients), the system sustained nearly **100 million rows/sec**, showing efficient parallel execution and CPU utilization.
 - **Fast Aggregations:** `GROUP BY` workloads delivered over **1 GiB/s throughput** with low single-digit millisecond latency at moderate concurrency.

content/learning-paths/servers-and-cloud-computing/clickhouse-gcp/images/gcp-shell.png

@@ -9,28 +9,21 @@ layout: learningpathall
 ## Install ClickHouse on GCP VM
 This guide covers installing, configuring, and validating ClickHouse on a GCP SUSE Linux Arm64 VM. It includes system preparation, installing ClickHouse with the official installer, verifying the setup, starting the server, and connecting via the client. The guide also configures ClickHouse as a systemd service to ensure reliable, automatic startup on Arm-based environments.
 
-### Install required system packages
+### Install required system packages and the ClickHouse repo
 Refresh system repositories and install basic utilities needed to download and run ClickHouse.
 
 ```console
 sudo zypper refresh
-sudo zypper install -y curl tar gzip sudo
+sudo zypper addrepo -r https://packages.clickhouse.com/rpm/clickhouse.repo -g
+sudo zypper --gpg-auto-import-keys refresh clickhouse-stable
 ```
 
-### Download ClickHouse using the official installer
-Download the official ClickHouse installation script, which works for both x86 and ARM64 systems.
+### Install ClickHouse via the ClickHouse repo
+Download and install ClickHouse for SuSE systems:
 
 ```console
-curl https://clickhouse.com/ | sh
-```
-This command downloads the ClickHouse binary into the current directory.
-
-### Install ClickHouse components
-Run the installer with root privileges to install all ClickHouse components.
-
-```console
-sudo ./clickhouse install
-```
+sudo zypper install -y clickhouse-server clickhouse-client
+``` 
 
 This installs:
 
@@ -51,9 +44,9 @@ clickhouse local --version
 
 You should see an output similar to:
 ```output
-ClickHouse local version 25.12.1.168 (official build).
-ClickHouse server version 25.12.1.168 (official build).
-ClickHouse client version 25.12.1.168 (official build).
+ClickHouse local version 25.11.2.24 (official build).
+ClickHouse server version 25.11.2.24 (official build).
+ClickHouse client version 25.11.2.24 (official build).
 ```
 
 ### Create ClickHouse user and directories
@@ -63,33 +56,30 @@ Create a dedicated system user and required directories for data, logs, and runt
 sudo useradd -r -s /sbin/nologin clickhouse || true
 sudo mkdir -p /var/lib/clickhouse
 sudo mkdir -p /var/log/clickhouse-server
-sudo mkdir -p /var/run/clickhouse-server
+sudo mkdir -p /var/run/clickhouse-client
 ```
 Set proper ownership so ClickHouse can access these directories.
 
 ```console
 sudo chown -R clickhouse:clickhouse \
   /var/lib/clickhouse \
   /var/log/clickhouse-server \
-  /var/run/clickhouse-server
+  /var/run/clickhouse-client
+sudo chmod 755 /var/lib/clickhouse \
+  /var/log/clickhouse-server \
+  /var/run/clickhouse-client
 ```
 
-### Start ClickHouse Server manually (validation)
+### Start ClickHouse Server manually
 You can just run the ClickHouse server in the foreground to confirm the configuration is valid.
 
 ```console
-sudo clickhouse server --config-file=/etc/clickhouse-server/config.xml
+sudo -u clickhouse clickhouse server --config-file=/etc/clickhouse-server/config.xml
 ```
 Keep this terminal open while testing.
 
-### Start clickhouse-server with:
-Start ClickHouse using the built-in start command for normal operation.
-
-```console
-sudo clickhouse start
-```
 ### Connect using ClickHouse Client
-Open a new terminal and connect to the ClickHouse server.
+Open a new SSH terminal and connect to the ClickHouse server.
 
 ```console
 clickhouse client
@@ -106,12 +96,14 @@ SELECT version()
 Query id: ddd3ff38-c0c6-43c5-8ae1-d9d07af4c372
 
    ┌─version()───┐
-1. │ 25.12.1.168 │
+1. │ 25.11.2.24 │
    └─────────────┘
 
 1 row in set. Elapsed: 0.001 sec.
 ```
 
+Please close the client SSH terminal and press "ctrl-c" in the server SSH terminal to halt the manual invocation of ClickHouse. FYI, the server may take a few seconds to close down when "ctrl-c" is received. 
+
 {{% notice Note %}}
 Recent benchmarks show that ClickHouse (v22.5.1.2079-stable) delivers up to 26% performance improvements on Arm-based platforms, such as AWS Graviton3, compared to other architectures, highlighting the efficiency of its vectorized execution engine on modern Arm CPUs.
 You can view [this Blog](https://community.arm.com/arm-community-blogs/b/servers-and-cloud-computing-blog/posts/improve-clickhouse-performance-up-to-26-by-using-aws-graviton3)
@@ -144,18 +136,38 @@ EOF
 **Reload systemd and enable the service:**
 
 ```console
-sudo systemctl daemon-reload
 sudo systemctl enable clickhouse-server
 sudo systemctl start clickhouse-server
+sudo systemctl daemon-reload
 ```
 
+{{% notice Note %}}
+You may get the following error which can be safely ignored:
+
+"ln: failed to create symbolic link '/etc/init.d/rc2.d/S50clickhouse-server': No such file or directory"
+{{% /notice %}}
+
 ### Verify ClickHouse service
 Ensure the ClickHouse server is running correctly as a background service.
 
 ```console
 sudo systemctl status clickhouse-server
 ```
 
+This confirms that the ClickHouse server is running correctly under systemd and ready to accept connections.
+
+```output
+● clickhouse-server.service - ClickHouse Server
+     Loaded: loaded (/etc/systemd/system/clickhouse-server.service; enabled; vendor preset: disabled)
+     Active: active (running) since Thu 2025-11-27 05:07:42 UTC; 18s ago
+   Main PID: 4229 (ClickHouseWatch)
+      Tasks: 814
+        CPU: 2.629s
+     CGroup: /system.slice/clickhouse-server.service
+             ├─ 4229 clickhouse-watchdog server --config=/etc/clickhouse-server/config.xml
+             └─ 4237 /usr/bin/clickhouse server --config=/etc/clickhouse-server/config.xml
+```
+
 ### Final validation
 Reconnect to ClickHouse and confirm it is operational.
 

content/learning-paths/servers-and-cloud-computing/clickhouse-gcp/images/gcp-ssh.png

@@ -26,6 +26,18 @@ To create a virtual machine based on the C4A instance type:
 
    ![Create a Google Axion C4A Arm virtual machine in the Google Cloud Console with c4a-standard-4 selected alt-text#center](images/gcp-vm.png "Creating a Google Axion C4A Arm virtual machine in Google Cloud Console")
 
-- Under **OS and Storage**, select **Change**, then choose an Arm64-based OS image. For this Learning Path, use **SUSE Linux Enterprise Server**. Pick the preferred version for your Operating System. Ensure you select the **Arm image** variant. Click **Select**.
+
+- Under **OS and Storage**, select **Change**, then choose an Arm64-based OS image. For this Learning Path, use **SUSE Linux Enterprise Server**. 
+- If using use **SUSE Linux Enterprise Server**. Select "Pay As You Go" for the license type.
+- Once appropriately selected and configured, please Click **Select**.
 - Under **Networking**, enable **Allow HTTP traffic**.
 - Click **Create** to launch the instance.
+- Once created, you should see a "SSH" option to the right in your list of VM instances.  Click on this to launch a SSH shell into your VM instance:
+
+![Invoke a SSH session via your browser alt-text#center](images/gcp-ssh.png "Invoke a SSH session into your running VM instance")
+
+- A window from your browser should come up and you should now see a shell into your VM instance:
+
+![Terminal Shell in your VM instance alt-text#center](images/gcp-shell.png "Terminal shell in your VM instance")
+
+Next, let's install ClickHouse!