Skip to content

Commit aef334d

Browse files
Blokje5Blokje5
committed
feat: Add documentation on Clickhouse Collector + Analyzer
See also: replicatedhq/troubleshoot#1967
1 parent 1eac14e commit aef334d

4 files changed

Lines changed: 228 additions & 1 deletion

File tree

‎docs/analyze/clickhouse.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
title: "ClickHouse"
3+
description: "Check version and connection status"
4+
tags: ["analyze"]
5+
---
6+
7+
8+
The `ClickHouse` analyzer is available to check version and connection status of a ClickHouse database.
9+
It relies on the data collected by the [ClickHouse collector](/docs/collect/clickhouse/).
10+
11+
The analyzer's outcome `when` clause may be used to evaluate the database connection status or a semver range to compare against the running version, and supports standard comparison operators.
12+
13+
## Parameters
14+
15+
**checkName:** Optional name.
16+
17+
**collectorName:** (Recommended) Must match the `collectorName` specified by the ClickHouse collector.
18+
19+
## Outcomes
20+
21+
The `when` value in an outcome of this analyzer contains the connection or version information.
22+
23+
The conditional in the when value supports the following:
24+
25+
**connected:** A boolean representing whether the database is connected.
26+
Can be compared to a boolean value with the `==` operator.
27+
28+
**version:** A string representing the semantic version of the database.
29+
Can be compared to a semver string using `<`, `<=`, `>`, `>=`, `==`, `!=`, with the letter 'x' as a version wildcard (25.x).
30+
The 'x' is parsed as '0'.
31+
32+
## Example Analyzer Definition
33+
34+
```yaml
35+
apiVersion: troubleshoot.sh/v1beta2
36+
kind: Preflight
37+
metadata:
38+
name: supported-clickhouse-version
39+
spec:
40+
collectors:
41+
- clickhouse:
42+
collectorName: clickhouse
43+
uri: 'clickhouse://user:password@hostname:9000/defaultdb'
44+
analyzers:
45+
- clickhouse:
46+
checkName: Must be ClickHouse 25.x or later
47+
collectorName: clickhouse
48+
outcomes:
49+
- fail:
50+
when: connected == false
51+
message: Cannot connect to ClickHouse server
52+
- fail:
53+
when: version < 25.x
54+
message: The ClickHouse server must be at least version 25
55+
- pass:
56+
message: The ClickHouse server is ready
57+
```
58+

‎docs/collect/all.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ tags: ["collect"]
3434
- [postgresql](./postgresql): collects information related to a postgresql server
3535
- [mysql](./mysql): collects information related to a mysql server
3636
- [redis](./redis): collects information related to a redis cluster
37+
- [clickhouse](./clickhouse.md) collects information related to a ClickHouse cluster
3738

3839
## CSI
3940

‎docs/collect/clickhouse.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
---
2+
title: "ClickHouse"
3+
description: "Include connection details from a ClickHouse server"
4+
tags: ["collect"]
5+
---
6+
7+
The data collector will validate and add information about a ClickHouse server to a support bundle.
8+
9+
## Parameters
10+
11+
The data collector has the following parameters:
12+
13+
#### `collectorName` (Recommended)
14+
The name of the collector.
15+
This is recommended to set to a string identifying the ClickHouse instance, and can be used to refer to this collector in analyzers and preflight checks.
16+
If unset, this will be set to the string "clickhouse".
17+
18+
#### `uri` (Required)
19+
The connection URI to use when connecting to the ClickHouse server. The ClickHouse collector uses the clickhous-go [`ParseDSN()`](https://pkg.go.dev/github.com/ClickHouse/clickhouse-go/v2#ParseDSN) function which expects URL-encoded connection strings. This relies on `url.Parse()`(https://pkg.go.dev/net/url#Parse) to parse the connection URI.
20+
If your password contains special characters, like `@`, `#`, `&`, etc., you may need to URL-encode the password.
21+
22+
#### `tls` (Optional)
23+
24+
TLS parameters are required whenever connections to the target ClickHouse server are encrypted using TLS. The server can be configured to authenticate clients (`mTLS`) or to secure the connection (`TLS`). This is controlled via the `verificationMode` setting in the Clickhouse Configuration. If `verificationMode` is strict, ClickHouse will additinally validate the client certificate. See the [OpenSSL configuration settings of ClickHouse](https://clickhouse.com/docs/operations/server-configuration-parameters/settings#openssl) for more details.
25+
26+
In `mTLS` mode, the required parameters are `client certificate`, `private key` and a `CA certificate`. If the server is configured to encrypt only the connection, then only the `CA certificate` is required. When the `skipVerify` option is set to `true`, then verifying the server certificate can be skipped. The `skipVerify` option is available only in `TLS` mode.
27+
28+
## Example Collector Definitions
29+
30+
Plain text connection to a server:
31+
```yaml
32+
apiVersion: troubleshoot.sh/v1beta2
33+
kind: SupportBundle
34+
metadata:
35+
name: sample
36+
spec:
37+
collectors:
38+
- clickhouse:
39+
collectorName: clickhouse-collector
40+
uri: clickhouse://user:password@hostname:9000/defaultdb
41+
```
42+
43+
URL-encoded password with special characters, using [Helm's `urlquery` function](https://helm.sh/docs/chart_template_guide/function_list/#urlquery):
44+
```yaml
45+
apiVersion: troubleshoot.sh/v1beta2
46+
kind: SupportBundle
47+
metadata:
48+
name: sample
49+
spec:
50+
collectors:
51+
- clickhouse:
52+
collectorName: clickhouse-collector
53+
uri: 'clickhouse://{{ $db_user | urlquery }}:{{ $db_pass | urlquery }}@{{ $db_host }}:{{ $db_port }}/{{ $db_name }}'
54+
```
55+
56+
Secured (`mTLS`) connection to a server with inline TLS parameter configurations. The parameters must be in `PEM` format:
57+
```yaml
58+
apiVersion: troubleshoot.sh/v1beta2
59+
kind: SupportBundle
60+
metadata:
61+
name: sample
62+
spec:
63+
collectors:
64+
- clickhouse:
65+
collectorName: clickhouse-collector
66+
uri: clickhouse://user:password@hostname:9000/defaultdb
67+
tls:
68+
cacert: |
69+
-----BEGIN CERTIFICATE-----
70+
...
71+
<truncated>
72+
...
73+
-----END CERTIFICATE-----
74+
clientCert: |
75+
-----BEGIN CERTIFICATE-----
76+
...
77+
<truncated>
78+
...
79+
-----END CERTIFICATE-----
80+
clientKey: |
81+
-----BEGIN RSA PRIVATE KEY-----
82+
...
83+
<truncated>
84+
...
85+
-----END RSA PRIVATE KEY-----
86+
```
87+
88+
Secured (`mTLS`) connection to a server with TLS parameters stored in a Kubernetes secret as `stringData`. The parameters must be in `PEM` format:
89+
```yaml
90+
apiVersion: troubleshoot.sh/v1beta2
91+
kind: Preflight
92+
metadata:
93+
name: sample
94+
spec:
95+
collectors:
96+
- clickhouse:
97+
collectorName: clickhouse-collector
98+
uri: clickhouse://user:password@hostname:9000/defaultdb
99+
tls:
100+
secret:
101+
# This secret must contain the following keys:
102+
# cacert: <CA PEM cert>
103+
# clientCert: <Client PEM cert> if mTLS
104+
# clientKey: <Client PEM key> if mTLS
105+
name: pg-tls-secret
106+
namespace: default
107+
```
108+
109+
Encrypted (`TLS`) connection to a server with TLS parameters inline. The parameters must be in `PEM` format. In this case, the server is configured not to authenticate clients:
110+
```yaml
111+
apiVersion: troubleshoot.sh/v1beta2
112+
kind: Preflight
113+
metadata:
114+
name: dbs-collector
115+
spec:
116+
collectors:
117+
- clickhouse:
118+
collectorName: clickhouse-collector
119+
uri: clickhouse://user:password@hostname:9000/defaultdb
120+
tls:
121+
cacert: |
122+
-----BEGIN CERTIFICATE-----
123+
...
124+
<truncated>
125+
...
126+
-----END CERTIFICATE-----
127+
```
128+
129+
Skip verification of the server certificate when creating an encrypted connection. This works only if the ClickHouse server has `verificationMode` set to `relaxed`. This means the connection will not validate the signing of the ClickHouse server certificate. The connection remains encrypted:
130+
```yaml
131+
apiVersion: troubleshoot.sh/v1beta2
132+
kind: Preflight
133+
metadata:
134+
name: dbs-collector
135+
spec:
136+
collectors:
137+
- clickhouse:
138+
collectorName: clickhouse-collector
139+
uri: clickhouse://user:password@hostname:9000/defaultdb
140+
tls:
141+
skipVerify: true
142+
```
143+
144+
## Included resources
145+
146+
A single JSON file will be added to the support bundle, in the path `/clickhouse/[collector-name].json`:
147+
148+
```json
149+
{
150+
"isConnected": false,
151+
"error": "Code: 241. DB::Exception: Received from ***:9000 ....",
152+
"version": "10.12",
153+
}
154+
```
155+
156+
### Fields
157+
158+
#### `isConnected`
159+
a boolean indicating if the collector was able to connect and authenticate using the connection string provided.
160+
161+
#### `error`
162+
a string that indicates the connection error, if there was one.
163+
164+
#### `version`
165+
when connected, a string indicating the version of ClickHouse that's running. Note that it is a valid Semver version, meaning
166+
commit information has been stripped from the version.

‎sidebars.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,7 @@ const sidebars: SidebarsConfig = {
7575
"collect/node-metrics",
7676
"collect/postgresql",
7777
"collect/redis",
78+
"collect/clickhouse",
7879
"collect/registry-images",
7980
"collect/sonobuoy",
8081
"collect/sysctl",
@@ -127,6 +128,7 @@ const sidebars: SidebarsConfig = {
127128
"analyze/mssql",
128129
"analyze/mysql",
129130
"analyze/postgresql",
131+
"analyze/clickhouse",
130132
"analyze/redis",
131133
"analyze/registry-images",
132134
"analyze/velero",
@@ -190,4 +192,4 @@ const sidebars: SidebarsConfig = {
190192
],
191193
};
192194

193-
export default sidebars;
195+
export default sidebars;

0 commit comments

Comments
 (0)