Configuração do Helm

Este guia aborda as opções de configuração para implantações do ClickStack com Helm. Para a instalação básica, consulte o guia principal de implantação com Helm.

O chart v2.x organiza os valores por tipo de recurso do Kubernetes no bloco hyperdx::

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

  frontendUrl: "http://localhost:3000"

  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 Entrada K8s (host, tls, annotations)
  podDisruptionBudget:  # Spec de PDB K8s
  tasks:          # Specs de CronJob K8s

Todas as variáveis de ambiente são repassadas por meio de dois recursos com nomes fixos, compartilhados pela Implantação do HyperDX e pelo OTel collector via envFrom:

• clickstack-config ConfigMap — preenchido com hyperdx.config
• clickstack-secret Secret — preenchido com hyperdx.secrets

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

Após implantar o ClickStack com sucesso, configure a API key para habilitar a coleta de dados de telemetria:

1. Acesse sua instância do HyperDX por meio da Entrada ou do endpoint de serviço configurado
2. Faça login no dashboard do HyperDX e navegue até as configurações da equipe para gerar ou recuperar sua API key
3. Atualize sua implantação com a API key usando um dos seguintes métodos:

Adicione a API key ao seu values.yaml:

hyperdx:
  secrets:
    HYPERDX_API_KEY: "your-api-key-here"

Em seguida, atualize sua implantação:

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

helm upgrade my-clickstack clickstack/clickstack \
  --set hyperdx.secrets.HYPERDX_API_KEY="your-api-key-here"

Após atualizar a API key, reinicie os pods para que carreguem a nova configuração:

kubectl rollout restart deployment my-clickstack-clickstack-app

Para lidar com dados sensíveis, como API keys ou credenciais de acesso ao banco de dados, o chart v2.x fornece um recurso unificado clickstack-secret, preenchido a partir de hyperdx.secrets.

O chart inclui valores padrão para todos os Secrets. Substitua-os no seu values.yaml:

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

Para implantações em produção nas quais você queira manter as credenciais separadas dos valores do helm, use um Secret externo do Kubernetes:

# Crie seu Secret
kubectl create secret generic my-clickstack-secrets \
  --from-literal=HYPERDX_API_KEY=my-secret-api-key \
  --from-literal=CLICKHOUSE_PASSWORD=my-ch-password \
  --from-literal=CLICKHOUSE_APP_PASSWORD=my-ch-app-password \
  --from-literal=MONGODB_PASSWORD=my-mongo-password

Em seguida, referencie isso no seu values:

hyperdx:
  useExistingConfigSecret: true
  existingConfigSecret: "my-clickstack-secrets"

Para expor a UI e a API do HyperDX por meio de um nome de domínio, habilite o recurso de Entrada no seu values.yaml.

hyperdx:
  frontendUrl: "https://hyperdx.yourdomain.com"  # Deve corresponder ao host de entrada

  ingress:
    enabled: true
    host: "hyperdx.yourdomain.com"

Para proteger sua implantação com HTTPS:

1. Crie um Secret TLS com seu certificado e chave:

kubectl create secret tls hyperdx-tls \
  --cert=path/to/tls.crt \
  --key=path/to/tls.key

2. Habilite o TLS na sua configuração de Entrada:

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

Como referência, veja como fica o recurso de entrada gerado:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: hyperdx-app-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$1
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  ingressClassName: nginx
  rules:
    - host: hyperdx.yourdomain.com
      http:
        paths:
          - path: /(.*)
            pathType: ImplementationSpecific
            backend:
              service:
                name: my-clickstack-clickstack-app
                port:
                  number: 3000
  tls:
    - hosts:
        - hyperdx.yourdomain.com
      secretName: hyperdx-tls

Configuração de caminho e reescrita:

• Para Next.js e outras SPAs, sempre use um caminho regex e uma anotação de reescrita, como mostrado acima
• N'ão use apenas path: / sem reescrita, pois isso quebrará o carregamento de arquivos estáticos

frontendUrl e ingress.host incompatíveis:

• Se eles não corresponderem, você poderá ter problemas com cookies, redirecionamentos e carregamento de arquivos estáticos

Configuração incorreta de TLS:

• Certifique-se de que seu Secret TLS seja válido e esteja referenciado corretamente na Entrada
• Os navegadores podem bloquear conteúdo inseguro se você acessar o aplicativo por HTTP quando o TLS estiver habilitado

Versão do controlador de Entrada:

• Alguns recursos (como caminhos regex e reescritas) exigem versões recentes do controlador de Entrada do nginx
• Verifique sua versão com:

kubectl -n ingress-nginx get pods -l app.kubernetes.io/name=ingress-nginx -o jsonpath="{.items[0].spec.containers[0].image}"

Se você precisar expor os endpoints do seu OTel collector (para traces, métricas e logs) via Entrada, use a configuração additionalIngresses. Isso é útil para enviar dados de telemetria de fora do cluster ou para usar um domínio personalizado para o collector.

hyperdx:
  ingress:
    enabled: true
    additionalIngresses:
      - name: otel-collector
        annotations:
          nginx.ingress.kubernetes.io/ssl-redirect: "false"
          nginx.ingress.kubernetes.io/force-ssl-redirect: "false"
          nginx.ingress.kubernetes.io/use-regex: "true"
        ingressClassName: nginx
        hosts:
          - host: collector.yourdomain.com
            paths:
              - path: /v1/(traces|metrics|logs)
                pathType: Prefix
                port: 4318
                name: otel-collector
        tls:
          - hosts:
              - collector.yourdomain.com
            secretName: collector-tls

• Isso cria um recurso de Entrada separado para os endpoints do OTel collector
• Você pode usar um domínio diferente, configurar opções específicas de TLS e aplicar anotações personalizadas
• A regra de caminho com regex permite rotear todos os sinais OTLP (traces, métricas, logs) por meio de uma única regra

Como alternativa, você pode usar additionalManifests para definir recursos de Entrada totalmente personalizados, como uma Entrada ALB da AWS.

O OTel collector é implantado usando o Chart do Helm oficial do OpenTelemetry Collector como subchart otel-collector:. Configure-o diretamente em otel-collector: nos seus values:

otel-collector:
  enabled: true
  mode: deployment
  replicaCount: 3
  resources:
    requests:
      memory: "128Mi"
      cpu: "100m"
    limits:
      memory: "256Mi"
      cpu: "200m"
  nodeSelector:
    node-role: monitoring
  tolerations:
    - key: monitoring
      operator: Equal
      value: otel
      effect: NoSchedule

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á está configurado para ler de ambos.

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

O MongoDB é 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"]
    statefulSet:
      spec:
        volumeClaimTemplates:
          - metadata:
              name: data-volume
            spec:
              accessModes: ["ReadWriteOnce"]
              storageClassName: "your-storage-class"
              resources:
                requests:
                  storage: 10Gi

A senha do MongoDB é definida em hyperdx.secrets.MONGODB_PASSWORD. Consulte a documentação do MCK para conhecer todos os campos de CRD disponíveis.

O ClickHouse é gerenciado pelo ClickHouse Operator por meio dos recursos personalizados ClickHouseCluster e KeeperCluster. As especificações de ambos os 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
      dataVolumeClaimSpec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 10Gi

As credenciais do usuário do ClickHouse vêm de hyperdx.secrets (e não de clickhouse.config.users, como na v1.x). Consulte o guia de configuração do ClickHouse Operator para conhecer todos os campos de CRD disponíveis.

Verifique o recurso de entrada:

kubectl get ingress -A
kubectl describe ingress <ingress-name>

Verifique os logs do controlador de Entrada:

kubectl logs -l app.kubernetes.io/name=ingress-nginx -n ingress-nginx

Teste das URLs dos ativos:

Use curl para verificar se os ativos estáticos estão sendo servidos como JS, e não como HTML:

curl -I https://hyperdx.yourdomain.com/_next/static/chunks/main-xxxx.js
# Deve retornar Content-Type: application/javascript

Ferramentas do desenvolvedor do navegador:

• Verifique a guia Network em busca de erros 404 ou de recursos que estejam retornando HTML em vez de JS
• Procure erros como Unexpected token < no console (isso indica que HTML foi retornado no lugar de JS)

Verifique se há reescrita de caminho:

• Certifique-se de que a Entrada não esteja removendo ou reescrevendo incorretamente os caminhos dos recursos

Limpe o cache do navegador e da CDN:

• Após as alterações, limpe o cache do navegador e qualquer cache de CDN/proxy para evitar recursos desatualizados

Você pode personalizar as configurações usando as flags --set:

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

Como alternativa, crie um values.yaml personalizado. Para obter os valores padrão:

helm show values clickstack/clickstack > values.yaml

Aplique seus valores personalizados:

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

• Opções de implantação - Sistemas externos e implantações mínimas
• Implantações na Cloud - Configurações de GKE, EKS e AKS
• Guia de atualização - Migração da v1.x para a v2.x
• Manifests adicionais - Objetos personalizados do Kubernetes
• Guia principal do Helm - Instalação básica
• Configuração (v1.x) - Guia de configuração da v1.x