Helm

ClickStack 的 Helm 图表可在此处获取，也是生产环境部署的推荐方式。

v2.x 图表 采用两阶段安装。首先通过 clickstack-operators 图表 安装 operator 和 CRD，然后安装主 clickstack 图表；后者会为 ClickHouse、MongoDB 和 OpenTelemetry Collector 创建由 operator 管理的自定义资源。

默认情况下，Helm 图表会预配所有核心组件，包括：

• ClickHouse — 通过 ClickHouseCluster 和 KeeperCluster 自定义资源，由 ClickHouse Operator 管理
• HyperDX — 可观测性 UI 和 API
• OpenTelemetry (OTel) collector — 作为子 图表，通过官方 OpenTelemetry Collector Helm 图表部署
• MongoDB — 通过 MongoDBCommunity 自定义资源，由 MongoDB Kubernetes Operator (MCK) 管理

不过，它也可以轻松自定义，以集成现有的 ClickHouse 部署——例如部署在 ClickHouse Cloud 上的实例。

该 图表 支持 Kubernetes 的标准最佳实践，包括：

• 通过 values.yaml 进行环境特定配置
• 资源限制和 pod (容器组) 级别的扩缩容
• TLS 和入口配置
• secrets 管理和身份验证设置
• 附加清单，用于随 图表 一起部署任意 Kubernetes 对象 (NetworkPolicy、HPA、ALB Ingress 等)

• 概念验证
• 生产环境

前置条件

• Helm v3+
• Kubernetes 集群 (推荐使用 v1.20+)
• 已配置为与集群交互的 kubectl

添加 ClickStack Helm 仓库

添加 ClickStack Helm 仓库：

helm repo add clickstack https://clickhouse.github.io/ClickStack-helm-charts
helm repo update

安装 Operator

请先安装 operator chart。这会注册主 chart 所需的 CRD：

helm install clickstack-operators clickstack/clickstack-operators

等待 Operator Pod (容器组) 就绪后再继续：

kubectl get pods -l app.kubernetes.io/instance=clickstack-operators

安装 ClickStack

operator 运行起来后，安装主 Chart：

helm install my-clickstack clickstack/clickstack

验证安装

请验证安装是否成功：

kubectl get pods -l "app.kubernetes.io/name=clickstack"

当所有 Pod (容器组) 都处于就绪状态后，请继续。

端口转发

端口转发可让我们访问并配置 HyperDX。部署到生产环境时，用户应改为通过入口或负载均衡器暴露该服务，以确保合适的网络访问、TLS 终止和可扩展性。端口转发更适合本地开发或一次性的管理操作，不适用于长期运行或高可用环境。

kubectl port-forward \
  pod/$(kubectl get pod -l app.kubernetes.io/name=clickstack -o jsonpath='{.items[0].metadata.name}') \
  8080:3000

进入 UI

访问 http://localhost:8080 以访问 HyperDX UI。

创建用户，并输入符合要求的用户名和密码。

点击 Create 后，将为通过 Helm 图表部署的 ClickHouse 实例创建数据源。

自定义值 (可选)

您可以使用 --set 参数来自定义设置。例如：

helm install my-clickstack clickstack/clickstack --set key=value

或者，编辑 values.yaml。如需获取默认值：

helm show values clickstack/clickstack > values.yaml

配置示例：

hyperdx:
  frontendUrl: "https://hyperdx.example.com"

  deployment:
    replicas: 2
    resources:
      limits:
        cpu: "2"
        memory: 4Gi
      requests:
        cpu: 500m
        memory: 1Gi

  ingress:
    enabled: true
    host: hyperdx.example.com
    tls:
      enabled: true
      tlsSecretName: "hyperdx-tls"

helm install my-clickstack clickstack/clickstack -f values.yaml

使用 secrets (可选)

v2.x chart 使用一个统一的 secret (clickstack-secret) ，其内容从 values 中的 hyperdx.secrets 填充。所有敏感环境变量——包括 ClickHouse 密码、MongoDB 密码和 HyperDX API key——都会通过这一个 secret 统一传递。

如需覆盖 secret 中的值：

hyperdx:
  secrets:
    HYPERDX_API_KEY: "your-api-key"
    CLICKHOUSE_PASSWORD: "your-clickhouse-password"
    CLICKHOUSE_APP_PASSWORD: "your-app-password"
    MONGODB_PASSWORD: "your-mongodb-password"

对于外部 Secret 管理 (例如使用 secrets operator) ，您可以引用一个现有的 Kubernetes Secret：

hyperdx:
  useExistingConfigSecret: true
  existingConfigSecret: "my-external-secret"
  existingConfigConnectionsKey: "connections.json"
  existingConfigSourcesKey: "sources.json"

如果使用 ClickHouse Cloud，请禁用内置的 ClickHouse 实例，并提供您的 Cloud 访问凭据：

# values-clickhouse-cloud.yaml
clickhouse:
  enabled: false

hyperdx:
  secrets:
    CLICKHOUSE_PASSWORD: "your-cloud-password"
    CLICKHOUSE_APP_PASSWORD: "your-cloud-password"

  useExistingConfigSecret: true
  existingConfigSecret: "clickhouse-cloud-config"
  existingConfigConnectionsKey: "connections.json"
  existingConfigSourcesKey: "sources.json"

单独创建用于连接的 Secret：

cat <<EOF > connections.json
[
  {
    "name": "ClickHouse Cloud",
    "host": "https://your-cloud-instance.clickhouse.cloud",
    "port": 8443,
    "username": "default",
    "password": "your-cloud-password"
  }
]
EOF

kubectl create secret generic clickhouse-cloud-config \
  --from-file=connections.json=connections.json

rm connections.json

helm install my-clickstack clickstack/clickstack -f values-clickhouse-cloud.yaml

默认情况下，此 图表 会安装 ClickHouse、MongoDB 和 OTel collector。对于生产环境，建议分别管理 ClickHouse 和 OTel collector。

要禁用 ClickHouse 和 OTel collector：

clickhouse:
  enabled: false

otel-collector:
  enabled: false

默认情况下，图表 配置中有一个以 cronjob 形式运行的任务，用于检查是否应触发告警。在 v2.x 中，任务配置已迁移到 hyperdx.tasks 下：

要升级到更新的版本：

helm upgrade my-clickstack clickstack/clickstack -f values.yaml

要查看可用的 图表 版本：

helm search repo clickstack

按相反的顺序卸载：

helm uninstall my-clickstack            # 先移除应用和自定义资源
helm uninstall clickstack-operators     # 移除 Operator 和 CRD

注意： 由 MongoDB 和 ClickHouse Operator 创建的 PersistentVolumeClaims 不会 在执行 helm uninstall 时被删除。这是刻意为之，旨在防止意外数据丢失。要清理 PVC，请参阅：

• MongoDB Kubernetes Operator 文档

kubectl logs -l app.kubernetes.io/name=clickstack

helm install my-clickstack clickstack/clickstack --debug --dry-run

kubectl get pods -l app.kubernetes.io/name=clickstack

默认情况下，ClickStack 将属性存储为 Map(LowCardinality(String), String) 列。这是可观测性 workloads 推荐使用的 schema。结合 bucketed map serialization 以及针对 map 键和值的文本索引，它可以实现有针对性的 lookup，同时避免动态 JSON 子列逐键摄取带来的额外开销。

JSON 类型的 schema 也已提供，目前处于 Beta 阶段，适合在属性键集合较小且稳定的 workloads 上进行评估。不建议将其作为默认选项。有关完整对比以及启用 JSON 支持所需的环境变量，请参见 Map vs JSON type。

• 部署选项 - 外部 ClickHouse、OTel collector 和最小部署
• 配置指南 - API keys、Secrets 和入口设置
• Cloud 部署 - GKE、EKS、AKS 配置和生产环境最佳实践
• 升级指南 - 从 v1.x 迁移到 v2.x
• 附加清单 - 与 图表 一起部署自定义 Kubernetes 对象

• Helm (v1.x) - v1.x 部署指南
• 配置 (v1.x) - v1.x 配置说明
• 部署选项 (v1.x) - v1.x 部署选项
• Cloud 部署 (v1.x) - v1.x Cloud 配置

• ClickStack 入门指南 - ClickStack 简介
• ClickStack Helm 图表仓库 - 图表源代码和 values 参考
• Kubernetes 文档 - Kubernetes 参考
• Helm 文档 - Helm 参考