Guia de atualização do Helm

Este guia aborda a migração do Chart do Helm do ClickStack com inline-template (v1.x) para a arquitetura baseada em subcharts (v2.x). Esta é uma mudança incompatível que substitui recursos do Kubernetes criados manualmente por recursos personalizados gerenciados por operadores para MongoDB e ClickHouse, e usa o Chart do Helm oficial do OpenTelemetry Collector.

Mudança incompatívelO chart v2.x não é compatível com a v1.x. Não há suporte para helm upgrade in-place. Recomendamos realizar uma nova instalação ao lado da implantação existente e migrar os dados, em vez de tentar uma atualização in-place.

Pré-requisitos

Faça backup dos seus dados antes de atualizar (MongoDB, PVCs do ClickHouse)
Revise as substituições atuais no values.yaml — a maioria das chaves foi movida ou renomeada

Instalação em duas fases

O chart v2.x usa uma instalação em duas etapas. Os operadores (que registram CRDs) devem ser instalados antes do chart principal (que cria CRs):

# Fase 1: Instalar operators e CRDs
helm install clickstack-operators clickstack/clickstack-operators

# Fase 2: Instalar o ClickStack
helm install my-clickstack clickstack/clickstack

Desinstale na ordem inversa:

helm uninstall my-clickstack
helm uninstall clickstack-operators

Persistência de dados

As PersistentVolumeClaims criadas pelos operadores do MongoDB e do ClickHouse não são removidas pelo helm uninstall. Isso é intencional, para evitar perda acidental de dados. Para limpar os PVCs após a desinstalação, consulte:

Documentação do MongoDB Kubernetes Operator

Classe de armazenamento

global.storageClassName and global.keepPVC foram removidos. A classe de armazenamento agora é configurada diretamente na seção spec do CR de cada operador:

mongodb:
  spec:
    statefulSet:
      spec:
        volumeClaimTemplates:
          - spec:
              storageClassName: "fast-ssd"

clickhouse:
  keeper:
    spec:
      dataVolumeClaimSpec:
        storageClassName: "fast-ssd"
  cluster:
    spec:
      dataVolumeClaimSpec:
        storageClassName: "fast-ssd"

O que mudou

Componente	Antes (v1.x)	Depois (v2.x)
MongoDB	Implantação inline + Serviço + PVC	MongoDB Kubernetes Operator (MCK) gerenciando um CR `MongoDBCommunity`
ClickHouse	Implantação inline + Serviço + ConfigMaps + PVCs	ClickHouse Operator gerenciando os CRs `ClickHouseCluster` + `KeeperCluster`
OTEL Collector	Implantação inline + Serviço (bloco `otel.*`)	Chart do Helm oficial do OpenTelemetry Collector (subchart `otel-collector:`)
HyperDX values	Chaves em `hyperdx.*` mais `tasks:` e `appUrl` no nível superior	Reorganizado por tipo de recurso do K8s em `hyperdx.*` (veja abaixo)
hdx-oss-v2	Chart legado obsoleto	Removido por completo

Reorganização dos values do HyperDX

O bloco hyperdx: agora está organizado por tipo de recurso do Kubernetes:

hyperdx:
  ports:          # Números de porta compartilhados (Implantação, Service, ConfigMap, Ingress)
    api: 8000
    app: 3000
    opamp: 4320

  frontendUrl: "http://localhost:3000"   # Substitui o appUrl removido

  config:         # → clickstack-config ConfigMap (variáveis de ambiente não sensíveis)
    APP_PORT: "3000"
    HYPERDX_LOG_LEVEL: "info"

  secrets:        # → clickstack-secret Secret (variáveis de ambiente sensíveis)
    HYPERDX_API_KEY: "..."
    CLICKHOUSE_PASSWORD: "otelcollectorpass"
    CLICKHOUSE_APP_PASSWORD: "hyperdx"
    MONGODB_PASSWORD: "hyperdx"

  deployment:     # Spec de Implantação K8s (imagem, réplicas, probes, etc.)
  service:        # Spec de Service K8s (tipo, annotations)
  ingress:        # Spec de Ingress K8s (host, tls, annotations)
  podDisruptionBudget:  # Spec de PDB K8s
  tasks:          # Specs de CronJob K8s (anteriormente tasks: no nível superior)

Principais mudanças

Antes (v1.x)	Depois (v2.x)
`appUrl`	Removido. Use `hyperdx.frontendUrl` (o padrão é `http://localhost:3000`)
`tasks.*` (nível superior)	`hyperdx.tasks.*`
`mongodb.password`	`hyperdx.secrets.MONGODB_PASSWORD`
`clickhouse.config.users.appUserPassword`	`hyperdx.secrets.CLICKHOUSE_APP_PASSWORD`
`clickhouse.config.users.otelUserPassword`	`hyperdx.secrets.CLICKHOUSE_PASSWORD`
sobrescritas de `otel.*` via variáveis de ambiente	`hyperdx.config.` (não sensível) e `hyperdx.secrets.` (sensível)

ConfigMap e Secret unificados

Agora, todas as variáveis de ambiente passam por dois recursos com nomes estáticos, compartilhados pela Implantação do HyperDX e pelo OTel collector via envFrom:

clickstack-config ConfigMap — preenchido a partir de hyperdx.config
clickstack-secret Secret — preenchido a partir de hyperdx.secrets

Não há mais um ConfigMap separado específico para OTel. Ambas as cargas de trabalho leem das mesmas fontes.

Migração do MongoDB

Valores removidos

Os seguintes valores mongodb.* não existem mais:

# REMOVIDO — não use
mongodb:
  image: "..."
  port: 27017
  strategy: ...
  nodeSelector: {}
  tolerations: []
  livenessProbe: ...
  readinessProbe: ...
  persistence:
    enabled: true
    dataSize: 10Gi

Novos valores

O MongoDB agora é gerenciado pelo operador MCK por meio de um recurso personalizado MongoDBCommunity. A especificação do CR é reproduzida literalmente a partir de mongodb.spec:

mongodb:
  enabled: true
  spec:
    members: 1
    type: ReplicaSet
    version: "5.0.32"
    security:
      authentication:
        modes: ["SCRAM"]
    users:
      - name: hyperdx
        db: hyperdx
        passwordSecretRef:
          name: '{{ include "clickstack.mongodb.fullname" . }}-password'
        roles:
          - name: dbOwner
            db: hyperdx
          - name: clusterMonitor
            db: admin
        scramCredentialsSecretName: '{{ include "clickstack.mongodb.fullname" . }}-scram'
    additionalMongodConfig:
      storage.wiredTiger.engineConfig.journalCompressor: zlib

A senha do MongoDB é definida em hyperdx.secrets.MONGODB_PASSWORD (não em mongodb.password). Ela é referenciada automaticamente pelo Secret da senha e pelo template mongoUri. Para adicionar persistência, adicione um bloco statefulSet dentro de mongodb.spec:

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

O subchart do operador MCK é configurado na seção mongodb-operator: (não em mongodb-kubernetes:). Consulte a documentação do MCK para conferir todos os campos de CRD disponíveis.

Migração do ClickHouse

Valores removidos

Os seguintes valores de clickhouse.* não existem mais:

# REMOVIDO — não usar
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: "..."

Novos valores

O ClickHouse agora é gerenciado pelo ClickHouse Operator por meio dos recursos personalizados ClickHouseCluster e KeeperCluster. Ambas as especificações dos CRs são geradas literalmente a partir dos 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

As credenciais de usuário do ClickHouse agora vêm de hyperdx.secrets (não de clickhouse.config.users). A especificação do cluster faz referência a elas por meio de expressões de template. O subchart do ClickHouse Operator é configurado em clickhouse-operator:. Webhooks e cert-manager são desabilitados por padrão. Consulte o guia de configuração do operador para ver todos os campos de CRD disponíveis.

Migração do OTel collector

Valores removidos

O bloco inteiro otel: não existe mais:

# REMOVIDO — não 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: ...

Novos valores

O OTel collector agora é implantado por meio do Chart do Helm oficial do OpenTelemetry Collector, como o subchart otel-collector:. Não há um wrapper otel: no chart pai — configure o subchart diretamente. As variáveis de ambiente (endpoint do ClickHouse, URL do OpAMP etc.) são compartilhadas por meio do ConfigMap unificado clickstack-config e do Secret clickstack-secret. O extraEnvsFrom do subchart já vem pré-configurado:

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

Para configurar os recursos (anteriormente otel.resources):

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

Para configurar réplicas (anteriormente otel.replicas):

otel-collector:
  replicaCount: 3

Para configurar nodeSelector/tolerations (antes otel.nodeSelector/otel.tolerations):

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

Consulte o Chart do Helm do OpenTelemetry Collector para ver todos os valores disponíveis do subchart.

Valores não alterados

As seções a seguir não são afetadas por esta migração:

global.* (imageRegistry, imagePullSecrets)

Nova instalação vs. atualização no local

Para uma nova instalação, nenhuma etapa especial é necessária. Os valores padrão funcionam imediatamente. Para uma atualização no local de um lançamento existente, esteja ciente de que:

Os operadores (MCK, ClickHouse Operator) serão instalados como novas implantações no seu espaço de nomes
A implantação existente do MongoDB e a implantação do ClickHouse serão excluídas pelo Helm (elas não estão mais nos templates do chart)
Os operadores criarão novos StatefulSets para gerenciar o MongoDB e o ClickHouse
Os PVCs do chart antigo não são reutilizados automaticamente pelos StatefulSets gerenciados pelo operador

Recomendamos fazer uma nova instalação ao lado da implantação existente e migrar os dados, em vez de realizar uma atualização no local.

Próximas etapas

Guia principal do Helm - Instalação básica com v2.x
Guia de configuração - API keys, secrets e entrada
Manifestos adicionais - Objetos personalizados do Kubernetes
Repositório dos charts do Helm do ClickStack - Código-fonte do chart e referência dos values

Primeiros passos

Recursos

Gerenciamento do ClickStack

Guias

Parceiros de integração

Pré-requisitos

Instalação em duas fases

Persistência de dados

Classe de armazenamento

O que mudou

Reorganização dos values do HyperDX

Principais mudanças

ConfigMap e Secret unificados

Migração do MongoDB

Valores removidos

Novos valores

Migração do ClickHouse

Valores removidos

Novos valores

Migração do OTel collector

Valores removidos

Novos valores

Valores não alterados

Nova instalação vs. atualização no local

Próximas etapas

​Pré-requisitos

​Instalação em duas fases

​Persistência de dados

​Classe de armazenamento

​O que mudou

​Reorganização dos values do HyperDX

​Principais mudanças

​ConfigMap e Secret unificados

​Migração do MongoDB

​Valores removidos

​Novos valores

​Migração do ClickHouse

​Valores removidos

​Novos valores

​Migração do OTel collector

​Valores removidos

​Novos valores

​Valores não alterados

​Nova instalação vs. atualização no local

​Próximas etapas

Pré-requisitos

Instalação em duas fases

Persistência de dados

Classe de armazenamento

O que mudou

Reorganização dos values do HyperDX

Principais mudanças

ConfigMap e Secret unificados

Migração do MongoDB

Valores removidos

Novos valores

Migração do ClickHouse

Valores removidos

Novos valores

Migração do OTel collector

Valores removidos

Novos valores

Valores não alterados

Nova instalação vs. atualização no local

Próximas etapas