ClickHouse data store

Learn how the Solo UI stores telemetry data in ClickHouse, how to bring your own ClickHouse instance, and how to query data directly.

All telemetry data collected by the OpenTelemetry pipeline is stored in ClickHouse. The Solo UI reads directly from ClickHouse to power the service graph, metrics views, and resource overviews.

Tables

ClickHouse stores each telemetry type in a separate table. All tables are in the platformdb database.

Table	Content
`otel_metrics_gauge`	Gauge metrics scraped from Istio components
`otel_metrics_sum`	Sum metrics scraped from Istio components
`otel_metrics_summary`	Summary metrics scraped from Istio components
`otel_metrics_histogram`	Histogram metrics scraped from Istio components
`otel_metrics_exp_histogram`	Exponential histogram metrics scraped from Istio components
`otel_logs_json`	Kubernetes events from the local cluster
`otel_k8sobjects_json`	Kubernetes object snapshots for the resource overview

Storage

The ClickHouse pod uses an EmptyDir volume. Data is not persisted across pod restarts; if the solo-management-clickhouse-shard0-0 pod is deleted or restarted, all telemetry history is lost and the UI begins repopulating from the time the pod comes back online. For production environments where data persistence matters, replace the bundled instance with an external ClickHouse that you manage. For steps, see Bring your own ClickHouse.

Query data directly

You can run SQL queries against ClickHouse directly from the pod to inspect raw telemetry data or diagnose pipeline issues. The following steps apply to the bundled ClickHouse instance. For external instances, connect by using your ClickHouse client of choice.

The following steps use the default release name solo-management and namespace solo-enterprise. If you used different values, update the commands accordingly.

Get the ClickHouse credentials from the secret.

export CH_USER=$(kubectl get secret solo-management-clickhouse-auth -n solo-enterprise -o jsonpath='{.data.username}' | base64 -d)
export CH_PASS=$(kubectl get secret solo-management-clickhouse-auth -n solo-enterprise -o jsonpath='{.data.password}' | base64 -d)

Open a shell in the ClickHouse pod.

kubectl exec -it -n solo-enterprise solo-management-clickhouse-shard0-0 -- clickhouse-client --user ${CH_USER} --password ${CH_PASS}

Run queries against the platformdb database. The following examples show common queries.
List all tables.
```
SHOW TABLES FROM platformdb;
```
Count the number of metrics stored.
```
SELECT count() FROM platformdb.otel_metrics_gauge;
```

Bring your own ClickHouse

Replace the bundled ClickHouse instance with an external instance that you manage. This method is recommended for production environments where persistent storage and independent lifecycle management are required.

Prerequisites

A ClickHouse version 22.x or later instance that is accessible from your cluster on port 9000 (native TCP protocol).
A ClickHouse admin user with permission to create databases and tables. For production environments, create a separate read-write user for the Solo UI after the schema is initialized.
Network connectivity from the solo-enterprise namespace to your ClickHouse host

The Solo UI uses the ClickHouse native TCP protocol (port 9000) without TLS. Secure the connection at the network level, such as with a private VPC or service mesh mTLS.

Configure the Helm chart

To switch to an external ClickHouse instance, disable the bundled deployment and provide your connection details.

Option 1: Pass credentials directly in Helm values

In your Helm values file for the management chart, set clickhouse.enabled to false and provide the connection details inline. The chart automatically generates the connection secret from these values.

clickhouse:
  enabled: false
ui:
  backend:
    clickhouse:
      generateConfig: true
      address: <clickhouse-host>
      port: 9000
      database: platformdb
      username: <username>
      password: <password>

Apply these values when you install or upgrade the Solo UI chart.

helm upgrade solo-enterprise solo-enterprise/management \
  --namespace solo-enterprise \
  --reuse-values \
  -f your-values.yaml

Option 2: Use a pre-existing secret

If you manage credentials outside of Helm, create the secret before installing the chart and set generateConfig to false.

Create the secret in the solo-enterprise namespace.

kubectl create secret generic clickhouse-config \
  --namespace solo-enterprise \
  --from-literal=config.json='{"address":"<clickhouse-host>","port":9000,"database":"platformdb","username":"<username>","password":"<password>"}'

Reference the secret in your Helm values file for the management chart.

clickhouse:
  enabled: false
ui:
  backend:
    clickhouse:
      generateConfig: false
      secretRef: clickhouse-config

Apply these values when you install or upgrade the Solo UI chart.

helm upgrade solo-enterprise solo-enterprise/management \
  --namespace solo-enterprise \
  --reuse-values \
  -f your-values.yaml

Helm values reference

Value	Default	Description
`clickhouse.enabled`	`true`	Deploy the bundled ClickHouse instance. Set to `false` for BYO.
`ui.backend.clickhouse.generateConfig`	`true`	Generate the connection secret from Helm values. Set to `false` to reference a pre-existing secret.
`ui.backend.clickhouse.secretRef`	`clickhouse-config`	Name of the Kubernetes Secret to create or reference.
`ui.backend.clickhouse.address`	`""`	External ClickHouse host. Must be reachable from the `solo-enterprise` namespace on port 9000 (native TCP). When empty, the bundled service DNS is used.
`ui.backend.clickhouse.port`	`9000`	ClickHouse native protocol port.
`ui.backend.clickhouse.database`	`platformdb`	ClickHouse database name.
`ui.backend.clickhouse.username`	`default`	ClickHouse username. Optional if you supply credentials via a pre-existing Secret using `secretRef`.
`ui.backend.clickhouse.password`	`password`	ClickHouse password. Optional if you supply credentials via a pre-existing Secret using `secretRef`.

Schema initialization

When you install or upgrade the chart, an init container runs the migrations tool to create the platformdb database and apply all table schemas against your external ClickHouse host. This creates and evolves schema only, and does not migrate or move existing data. No manual schema setup is required as long as the admin credentials have CREATE DATABASE and CREATE TABLE privileges.

If you need to initialize the schema outside of a Helm deployment, such as in a CI environment or to pre-initialize the database before a first install, run the migrations container directly.

docker run --rm \
  <registry>/solo-enterprise/solo-enterprise-migrations:<version> \
  init --host=<clickhouse-host> --port=9000 --database=platformdb \
  --adminuser=<username> --adminpassword=<password>

docker run --rm \
  <registry>/solo-enterprise/solo-enterprise-migrations:<version> \
  migrate-up --host=<clickhouse-host> --port=9000 --database=platformdb \
  --adminuser=<username> --adminpassword=<password>

The migrations tool is safe to re-run. Running migrate-up on an already-initialized database applies only new migrations and skips existing ones.

Troubleshooting

Init container fails with connection refused

Verify that ui.backend.clickhouse.address resolves from within the cluster and that port 9000 is reachable. Test connectivity with a temporary pod.

kubectl run ch-test --rm -it --image=clickhouse/clickhouse-client \
  --namespace solo-enterprise --restart=Never -- \
  --host=<clickhouse-host> --port=9000 \
  --user=<username> --password=<password> \
  --query="SELECT 1"

UI backend fails to start

The connection secret must contain all four fields: address, database, username, and password. Inspect the generated secret.

kubectl get secret clickhouse-config -n solo-enterprise \
  -o jsonpath='{.data.config\.json}' | base64 -d

Request traces Prometheus