Configuração do Helm (v1.x)

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.

Configuração da API key

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

Acesse sua instância do HyperDX por meio da Entrada configurada ou do endpoint do serviço
Faça login no painel do HyperDX e acesse Team Settings para gerar ou recuperar sua API key
Atualize sua Implantação com a API key usando um dos métodos a seguir:

Método 1: Atualizar com `helm upgrade` usando arquivo de values

Adicione a API key ao seu values.yaml:

hyperdx:
  apiKey: "your-api-key-here"

Em seguida, atualize sua implantação:

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

Método 2: Atualização via helm upgrade com a flag –set

helm upgrade my-clickstack clickstack/clickstack --set hyperdx.apiKey="your-api-key-here"

Reinicie os pods para aplicar as alterações

Depois de atualizar a API key, reinicie os pods para que passem a usar a nova configuração:

kubectl rollout restart deployment my-clickstack-clickstack-app my-clickstack-clickstack-otel-collector

Gerenciamento de Secrets

Para lidar com dados sensíveis, como API keys ou credenciais de banco de dados, use Secrets do Kubernetes.

Usando Secrets pré-configurados

O Chart do Helm inclui um modelo padrão de Secret localizado em charts/clickstack/templates/secrets.yaml. Esse arquivo fornece uma estrutura básica para gerenciar Secrets.

Se você precisar aplicar manualmente um Secret, modifique e aplique o modelo secrets.yaml fornecido:

apiVersion: v1
kind: Secret
metadata:
  name: hyperdx-secret
  annotations:
    "helm.sh/resource-policy": keep
type: Opaque
data:
  API_KEY: <base64-encoded-api-key>

Aplique o Secret ao seu cluster:

kubectl apply -f secrets.yaml

Criando um Secret personalizado

Crie manualmente um Secret personalizado do Kubernetes:

kubectl create secret generic hyperdx-secret \
  --from-literal=API_KEY=my-secret-api-key

Referenciando um Secret no values.yaml

hyperdx:
  apiKey:
    valueFrom:
      secretKeyRef:
        name: hyperdx-secret
        key: API_KEY

Configuração da Entrada

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

Configuração geral da Entrada

hyperdx:
  frontendUrl: "https://hyperdx.yourdomain.com"  # Deve corresponder ao host de Entrada
  ingress:
    enabled: true
    host: "hyperdx.yourdomain.com"

Ativando o TLS (HTTPS)

Para proteger sua implantação com HTTPS:

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

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

2. Habilite o TLS na configuração da Entrada:

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

Exemplo de configuração de Entrada

Para referência, veja como é 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

Armadilhas comuns de entrada

Configuração de caminho e reescrita:

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

Incompatibilidade entre frontendUrl e ingress.host:

Se eles não coincidirem, você poderá ter problemas com cookies, redirecionamentos e carregamento de recursos

Configuração incorreta de TLS:

Verifique se seu Secret de TLS é válido e está referenciado corretamente na entrada
Os navegadores podem bloquear conteúdo inseguro se você acessar a aplicação por HTTP quando o TLS estiver habilitado

Versão do controlador de entrada:

Alguns recursos (como caminhos com regex e reescritas) exigem versões recentes do controlador de entrada 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}"

Entrada do OTel collector

Se você precisar expor os endpoints do seu OTel collector (para traces, métricas e logs) por meio de Entrada, use a configuração additionalIngresses. Isso é útil para enviar dados de telemetria de fora do cluster ou para usar um domínio personalizado no 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 definições específicas de TLS e aplicar annotations personalizadas
A regra de caminho com regex permite rotear todos os sinais OTLP (traces, metrics, logs) por meio de uma única regra

Solução de problemas da Entrada

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 recursos:

Use curl para verificar se os recursos 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

DevTools do navegador:

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

Verifique se há regravações de caminho:

Certifique-se de que a Entrada não esteja removendo nem regravando 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

Como personalizar values

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

Exemplo de configuração:

replicaCount: 2

resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi

hyperdx:
  ingress:
    enabled: true
    host: hyperdx.example.com

Aplique seus values personalizados:

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

Próximos passos

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