274 lines
17 KiB
Markdown
274 lines
17 KiB
Markdown
# CH-UI
|
|
|
|
[CH-UI](https://github.com/caioricciuti/ch-ui) is a modern, feature-rich web interface for ClickHouse databases.
|
|
|
|
## TL;DR
|
|
|
|
```bash
|
|
helm install ch-ui ./charts/ch-ui \
|
|
--set clickhouse.url="http://clickhouse:8123" \
|
|
--set clickhouse.auth.password="your-password"
|
|
```
|
|
|
|
## Introduction
|
|
|
|
This chart bootstraps a [CH-UI](https://github.com/caioricciuti/ch-ui) deployment on a [Kubernetes](https://kubernetes.io) cluster using the [Helm](https://helm.sh) package manager.
|
|
|
|
## Prerequisites
|
|
|
|
- Kubernetes 1.19+
|
|
- Helm 3.2.0+
|
|
- PV provisioner support in the underlying infrastructure (if persistence is needed)
|
|
- ClickHouse server accessible from the cluster
|
|
|
|
## Installing the Chart
|
|
|
|
To install the chart with the release name `ch-ui`:
|
|
|
|
```bash
|
|
helm install ch-ui ./charts/ch-ui
|
|
```
|
|
|
|
The command deploys CH-UI on the Kubernetes cluster in the default configuration. The [Parameters](#parameters) section lists the parameters that can be configured during installation.
|
|
|
|
> **Tip**: List all releases using `helm list`
|
|
|
|
## Uninstalling the Chart
|
|
|
|
To uninstall/delete the `ch-ui` deployment:
|
|
|
|
```bash
|
|
helm delete ch-ui
|
|
```
|
|
|
|
The command removes all the Kubernetes components associated with the chart and deletes the release.
|
|
|
|
## Parameters
|
|
|
|
### Global parameters
|
|
|
|
| Name | Description | Value |
|
|
| ------------------------- | ----------------------------------------------- | ----- |
|
|
| `nameOverride` | String to partially override ch-ui.fullname | `""` |
|
|
| `fullnameOverride` | String to fully override ch-ui.fullname | `""` |
|
|
| `imagePullSecrets` | Global Docker registry secret names as an array | `[]` |
|
|
|
|
### Common parameters
|
|
|
|
| Name | Description | Value |
|
|
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------- |
|
|
| `replicaCount` | Number of CH-UI replicas to deploy | `1` |
|
|
| `image.repository` | CH-UI image repository | `ghcr.io/caioricciuti/ch-ui` |
|
|
| `image.pullPolicy` | CH-UI image pull policy | `IfNotPresent` |
|
|
| `image.tag` | CH-UI image tag (immutable tags are recommended) | `""` |
|
|
| `serviceAccount.create` | Specifies whether a ServiceAccount should be created | `true` |
|
|
| `serviceAccount.automount` | Automatically mount a ServiceAccount's API credentials? | `true` |
|
|
| `serviceAccount.annotations` | Annotations to add to the service account | `{}` |
|
|
| `serviceAccount.name` | The name of the ServiceAccount to use | `""` |
|
|
| `podAnnotations` | Annotations for CH-UI pods | `{}` |
|
|
| `podLabels` | Extra labels for CH-UI pods | `{}` |
|
|
| `podSecurityContext` | Set CH-UI pod's Security Context | `{}` |
|
|
| `securityContext` | Set CH-UI container's Security Context | `{}` |
|
|
|
|
### CH-UI Configuration parameters
|
|
|
|
| Name | Description | Value |
|
|
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------- |
|
|
| `clickhouse.url` | ClickHouse server URL | `"http://clickhouse:8123"` |
|
|
| `clickhouse.auth.username` | ClickHouse username | `"default"` |
|
|
| `clickhouse.auth.password` | ClickHouse password (ignored if existingSecret is set) | `""` |
|
|
| `clickhouse.auth.existingSecret` | Name of existing Secret containing ClickHouse password | `""` |
|
|
| `clickhouse.auth.secretKeys.password` | Key in the existing Secret containing the password | `"clickhouse-password"` |
|
|
| `clickhouse.useAdvanced` | Enable advanced mode | `false` |
|
|
| `clickhouse.requestTimeout` | Request timeout in milliseconds | `30000` |
|
|
| `clickhouse.basePath` | Base path for the application | `"/"` |
|
|
|
|
### Exposure parameters
|
|
|
|
| Name | Description | Value |
|
|
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------- |
|
|
| `service.type` | CH-UI service type | `ClusterIP` |
|
|
| `service.port` | CH-UI service HTTP port | `80` |
|
|
| `service.targetPort` | CH-UI container port | `5521` |
|
|
| `ingress.enabled` | Enable ingress record generation for CH-UI | `false` |
|
|
| `ingress.className` | IngressClass that will be be used to implement the Ingress (Kubernetes 1.18+) | `""` |
|
|
| `ingress.annotations` | Additional annotations for the Ingress resource | `{}` |
|
|
| `ingress.hosts[0].host` | Default host for the ingress record | `ch-ui.local` |
|
|
| `ingress.hosts[0].paths[0].path` | Default path for the default host | `/` |
|
|
| `ingress.hosts[0].paths[0].pathType` | Ingress path type | `ImplementationSpecific` |
|
|
| `ingress.tls` | Enable TLS configuration for the host defined at `ingress.hosts[0].host` parameter | `[]` |
|
|
|
|
### Resource parameters
|
|
|
|
| Name | Description | Value |
|
|
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------- |
|
|
| `resources.limits.cpu` | The CPU limits for the CH-UI containers | `500m` |
|
|
| `resources.limits.memory` | The memory limits for the CH-UI containers | `512Mi` |
|
|
| `resources.requests.cpu` | The requested CPU for the CH-UI containers | `100m` |
|
|
| `resources.requests.memory` | The requested memory for the CH-UI containers | `128Mi` |
|
|
| `livenessProbe.httpGet.path` | Path for liveness probe | `/` |
|
|
| `livenessProbe.httpGet.port` | Port for liveness probe | `http` |
|
|
| `livenessProbe.initialDelaySeconds` | Initial delay seconds for liveness probe | `30` |
|
|
| `livenessProbe.timeoutSeconds` | Timeout seconds for liveness probe | `5` |
|
|
| `readinessProbe.httpGet.path` | Path for readiness probe | `/` |
|
|
| `readinessProbe.httpGet.port` | Port for readiness probe | `http` |
|
|
| `readinessProbe.initialDelaySeconds` | Initial delay seconds for readiness probe | `5` |
|
|
| `readinessProbe.timeoutSeconds` | Timeout seconds for readiness probe | `5` |
|
|
| `autoscaling.enabled` | Enable Horizontal POD autoscaling for CH-UI | `false` |
|
|
| `autoscaling.minReplicas` | Minimum number of CH-UI replicas | `1` |
|
|
| `autoscaling.maxReplicas` | Maximum number of CH-UI replicas | `3` |
|
|
| `autoscaling.targetCPUUtilizationPercentage`| Target CPU utilization percentage | `80` |
|
|
|
|
### Additional parameters
|
|
|
|
| Name | Description | Value |
|
|
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------- |
|
|
| `extraEnvVars` | Array with extra environment variables to add to CH-UI containers | `[]` |
|
|
| `extraEnvVarsCM` | Name of existing ConfigMap containing extra env vars for CH-UI containers | `""` |
|
|
| `extraEnvVarsSecret` | Name of existing Secret containing extra env vars for CH-UI containers | `""` |
|
|
| `volumes` | Optionally specify extra list of additional volumes for the CH-UI pod(s) | `[]` |
|
|
| `volumeMounts` | Optionally specify extra list of additional volumeMounts for the CH-UI container(s) | `[]` |
|
|
| `nodeSelector` | Node labels for pod assignment | `{}` |
|
|
| `tolerations` | Tolerations for pod assignment | `[]` |
|
|
| `affinity` | Affinity for pod assignment | `{}` |
|
|
|
|
## Configuration and installation details
|
|
|
|
### Using an existing Secret
|
|
|
|
Instead of passing the ClickHouse password directly, you can use an existing Kubernetes Secret:
|
|
|
|
1. Create a Secret with your ClickHouse password:
|
|
|
|
```bash
|
|
kubectl create secret generic clickhouse-secret \
|
|
--from-literal=clickhouse-password="your-password"
|
|
```
|
|
|
|
2. Install the chart using the existing Secret:
|
|
|
|
```bash
|
|
helm install ch-ui ./charts/ch-ui \
|
|
--set clickhouse.auth.existingSecret="clickhouse-secret" \
|
|
--set clickhouse.auth.secretKeys.password="clickhouse-password"
|
|
```
|
|
|
|
### Exposing CH-UI
|
|
|
|
#### Using Ingress
|
|
|
|
To expose CH-UI using an Ingress:
|
|
|
|
```bash
|
|
helm install ch-ui ./charts/ch-ui \
|
|
--set ingress.enabled=true \
|
|
--set ingress.hosts[0].host="ch-ui.example.com" \
|
|
--set ingress.className="nginx"
|
|
```
|
|
|
|
#### Using LoadBalancer
|
|
|
|
To expose CH-UI using a LoadBalancer service:
|
|
|
|
```bash
|
|
helm install ch-ui ./charts/ch-ui \
|
|
--set service.type=LoadBalancer
|
|
```
|
|
|
|
#### Using NodePort
|
|
|
|
To expose CH-UI using a NodePort service:
|
|
|
|
```bash
|
|
helm install ch-ui ./charts/ch-ui \
|
|
--set service.type=NodePort
|
|
```
|
|
|
|
### Adding extra environment variables
|
|
|
|
You can add extra environment variables using `extraEnvVars`:
|
|
|
|
```bash
|
|
helm install ch-ui ./charts/ch-ui \
|
|
--set extraEnvVars[0].name=LOG_LEVEL \
|
|
--set extraEnvVars[0].value=debug
|
|
```
|
|
|
|
Or by referencing an existing ConfigMap or Secret:
|
|
|
|
```bash
|
|
helm install ch-ui ./charts/ch-ui \
|
|
--set extraEnvVarsCM=my-configmap \
|
|
--set extraEnvVarsSecret=my-secret
|
|
```
|
|
|
|
## Examples
|
|
|
|
### Basic installation with password
|
|
|
|
```bash
|
|
helm install ch-ui ./charts/ch-ui \
|
|
--set clickhouse.url="http://my-clickhouse:8123" \
|
|
--set clickhouse.auth.username="admin" \
|
|
--set clickhouse.auth.password="secretpassword"
|
|
```
|
|
|
|
### Installation with external ClickHouse and Ingress
|
|
|
|
```bash
|
|
helm install ch-ui ./charts/ch-ui \
|
|
--set clickhouse.url="http://clickhouse.example.com:8123" \
|
|
--set clickhouse.auth.existingSecret="clickhouse-credentials" \
|
|
--set ingress.enabled=true \
|
|
--set ingress.hosts[0].host="ch-ui.example.com" \
|
|
--set ingress.tls[0].secretName="ch-ui-tls" \
|
|
--set ingress.tls[0].hosts[0]="ch-ui.example.com"
|
|
```
|
|
|
|
### Installation with resource limits
|
|
|
|
```bash
|
|
helm install ch-ui ./charts/ch-ui \
|
|
--set resources.requests.memory="256Mi" \
|
|
--set resources.requests.cpu="250m" \
|
|
--set resources.limits.memory="1Gi" \
|
|
--set resources.limits.cpu="1"
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### CH-UI cannot connect to ClickHouse
|
|
|
|
1. Verify that the ClickHouse URL is correct and accessible from within the cluster:
|
|
|
|
```bash
|
|
kubectl run -it --rm debug --image=busybox --restart=Never -- wget -O- http://clickhouse:8123
|
|
```
|
|
|
|
2. Check the CH-UI logs:
|
|
|
|
```bash
|
|
kubectl logs -l app.kubernetes.io/name=ch-ui
|
|
```
|
|
|
|
3. Verify the credentials are correct by checking the Secret:
|
|
|
|
```bash
|
|
kubectl get secret ch-ui-secret -o jsonpath='{.data.clickhouse-password}' | base64 -d
|
|
```
|
|
|
|
### CH-UI is not accessible
|
|
|
|
1. Check the service is running:
|
|
|
|
```bash
|
|
kubectl get svc -l app.kubernetes.io/name=ch-ui
|
|
```
|
|
|
|
2. For Ingress issues, check the Ingress controller logs and ensure the Ingress resource is created:
|
|
|
|
```bash
|
|
kubectl get ingress
|
|
kubectl describe ingress ch-ui
|
|
```
|