Helm upgrade guide

The MongoDB password is set in `hyperdx.secrets.MONGODB_PASSWORD` (not `mongodb.password`). It is referenced automatically by the password Secret and the `mongoUri` template.

To add persistence, add a `statefulSet` block inside `mongodb.spec`:

```
mongodb:
  spec:
    statefulSet:
      spec:
        volumeClaimTemplates:
          - metadata:
              name: data-volume
            spec:
              accessModes: ["ReadWriteOnce"]
              storageClassName: "your-storage-class"
              resources:
                requests:
                  storage: 10Gi
```

The MCK operator subchart is configured under `mongodb-operator:` (not `mongodb-kubernetes:`). See the [MCK documentation](https://github.com/mongodb/mongodb-kubernetes/tree/master/docs/mongodbcommunity) for all available CRD fields.

## ClickHouse migration[​](#clickhouse-migration "Direct link to ClickHouse migration")

### Removed values[​](#clickhouse-removed-values "Direct link to Removed values")

The following `clickhouse.*` values no longer exist:

```
# REMOVED — do not use
clickhouse:
  image: "..."
  terminationGracePeriodSeconds: 90
  resources: {}
  livenessProbe: ...
  readinessProbe: ...
  startupProbe: ...
  nodeSelector: {}
  tolerations: []
  service:
    type: ClusterIP
    annotations: {}
  persistence:
    enabled: true
    dataSize: 10Gi
    logSize: 5Gi
  config:
    clusterCidrs: [...]
    users:
      appUserPassword: "..."
      otelUserPassword: "..."
      otelUserName: "..."
```

### New values[​](#clickhouse-new-values "Direct link to New values")

ClickHouse is now managed by the ClickHouse Operator via `ClickHouseCluster` and `KeeperCluster` custom resources. Both CR specs are rendered verbatim from values:

```
clickhouse:
  enabled: true
  port: 8123
  nativePort: 9000
  prometheus:
    enabled: true
    port: 9363
  keeper:
    spec:
      replicas: 1
      dataVolumeClaimSpec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 5Gi
  cluster:
    spec:
      replicas: 1
      shards: 1
      keeperClusterRef:
        name: '{{ include "clickstack.clickhouse.keeper" . }}'
      dataVolumeClaimSpec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 10Gi
      settings:
        extraUsersConfig:
          users:
            app:
              password: '{{ .Values.hyperdx.secrets.CLICKHOUSE_APP_PASSWORD }}'
            otelcollector:
              password: '{{ .Values.hyperdx.secrets.CLICKHOUSE_PASSWORD }}'
        extraConfig:
          max_connections: 4096
          keep_alive_timeout: 64
          max_concurrent_queries: 100
```

ClickHouse user credentials are now sourced from `hyperdx.secrets` (not `clickhouse.config.users`). The cluster spec references them with template expressions.

The ClickHouse Operator subchart is configured under `clickhouse-operator:`. Webhooks and cert-manager are disabled by default. See the [operator configuration guide](https://clickhouse.com/docs/clickhouse-operator/guides/configuration) for all available CRD fields.

## OTEL Collector migration[​](#otel-collector-migration "Direct link to OTEL Collector migration")

### Removed values[​](#otel-removed-values "Direct link to Removed values")

The entire `otel:` block no longer exists:

```
# REMOVED — do not use
otel:
  enabled: true
  image: ...
  replicas: 1
  resources: {}
  clickhouseEndpoint: ...
  clickhouseUser: ...
  clickhousePassword: ...
  clickhouseDatabase: "default"
  opampServerUrl: ...
  port: 13133
  nativePort: 24225
  grpcPort: 4317
  httpPort: 4318
  healthPort: 8888
  env: []
  customConfig: ...
```

### New values[​](#otel-new-values "Direct link to New values")

The OTEL Collector is now deployed via the official OpenTelemetry Collector Helm chart as the `otel-collector:` subchart. There is no parent-chart `otel:` wrapper — configure the subchart directly.

Environment variables (ClickHouse endpoint, OpAMP URL, etc.) are shared via the unified `clickstack-config` ConfigMap and `clickstack-secret` Secret. The subchart's `extraEnvsFrom` is pre-wired:

```
otel-collector:
  enabled: true
  mode: deployment
  image:
    repository: docker.clickhouse.com/clickhouse/clickstack-otel-collector
    tag: ""
  extraEnvsFrom:
    - configMapRef:
        name: clickstack-config
    - secretRef:
        name: clickstack-secret
  ports:
    otlp:
      enabled: true
      containerPort: 4317
      servicePort: 4317
    otlp-http:
      enabled: true
      containerPort: 4318
      servicePort: 4318
```

To set resources (previously `otel.resources`):

```
otel-collector:
  resources:
    requests:
      memory: "128Mi"
      cpu: "100m"
    limits:
      memory: "256Mi"
      cpu: "200m"
```

To set replicas (previously `otel.replicas`):

```
otel-collector:
  replicaCount: 3
```

To set nodeSelector/tolerations (previously `otel.nodeSelector`/`otel.tolerations`):

```
otel-collector:
  nodeSelector:
    node-role: monitoring
  tolerations:
    - key: monitoring
      operator: Equal
      value: otel
      effect: NoSchedule
```

See the [OpenTelemetry Collector Helm chart](https://github.com/open-telemetry/opentelemetry-helm-charts/tree/main/charts/opentelemetry-collector) for all available subchart values.

## Unchanged values[​](#unchanged-values "Direct link to Unchanged values")

The following sections are **not affected** by this migration:

- `global.*` (imageRegistry, imagePullSecrets)

## Fresh install vs. in-place upgrade[​](#fresh-install-vs-in-place-upgrade "Direct link to Fresh install vs. in-place upgrade")

For a **fresh install**, no special steps are needed. The default values work out of the box.

For an **in-place upgrade** of an existing release, be aware that:

1. The operators (MCK, ClickHouse Operator) will be installed as new deployments in your namespace
2. The existing MongoDB Deployment and ClickHouse Deployment will be deleted by Helm (they are no longer in the chart's templates)
3. The operators will create new StatefulSets to manage MongoDB and ClickHouse
4. **PVCs from the old chart are not automatically reused** by the operator-managed StatefulSets

We recommend performing a fresh install alongside the existing deployment and migrating data, rather than an in-place upgrade.

## Next steps[​](#next-steps "Direct link to Next steps")

- [Main Helm guide](/docs/use-cases/observability/clickstack/deployment/helm) - Basic installation with v2.x
- [Configuration guide](/docs/use-cases/observability/clickstack/deployment/helm-configuration) - API keys, secrets, and ingress
- [Additional manifests](/docs/use-cases/observability/clickstack/deployment/helm-additional-manifests) - Custom Kubernetes objects
- [ClickStack Helm charts repository](https://github.com/ClickHouse/ClickStack-helm-charts) - Chart source code and values reference

- [Prerequisites](#prerequisites)- [Two-phase installation](#two-phase-installation)
    - [Data persistence](#data-persistence)- [Storage class](#storage-class)- [What changed](#what-changed)- [HyperDX values reorganization](#hyperdx-values-reorganization)
        - [Key moves](#key-moves)- [Unified ConfigMap and Secret](#unified-configmap-and-secret)- [MongoDB migration](#mongodb-migration)
          - [Removed values](#mongodb-removed-values)- [New values](#mongodb-new-values)- [ClickHouse migration](#clickhouse-migration)
            - [Removed values](#clickhouse-removed-values)- [New values](#clickhouse-new-values)- [OTEL Collector migration](#otel-collector-migration)
              - [Removed values](#otel-removed-values)- [New values](#otel-new-values)- [Unchanged values](#unchanged-values)- [Fresh install vs. in-place upgrade](#fresh-install-vs-in-place-upgrade)- [Next steps](#next-steps)

Was this page helpful?