Helm (v1.x)

Implantação do ClickStack com o Chart do Helm inline-template v1.x

Descontinuado — chart v1.x

Esta página documenta o chart do Helm com template inline v1.x, que está em modo de manutenção e não receberá novos recursos. Para novas implantações, use o chart v2.x. Para migrar uma implantação v1.x existente, consulte o guia de atualização.

O chart do Helm para o ClickStack pode ser encontrado aqui e é o método recomendado para implantações em produção.

Por padrão, o chart do Helm provisiona todos os componentes principais, incluindo:

• ClickHouse
• HyperDX
• collector OpenTelemetry (OTel)
• MongoDB (para o estado persistente da aplicação)

No entanto, ele pode ser facilmente personalizado para se integrar a uma implantação existente do ClickHouse — por exemplo, uma hospedada no ClickHouse Cloud.

O chart oferece suporte às práticas recomendadas do Kubernetes, incluindo:

• Configuração específica do ambiente via values.yaml
• Limites de recursos e escalonamento no nível de pod
• Configuração de TLS e Entrada
• Gerenciamento de Secrets e configuração de autenticação

​

Indicado para

• Provas de conceito
• Produção

​

Etapas de implantação

1. ​

   Pré-requisitos

   • Helm v3+
   • Cluster do Kubernetes (v1.20+ recomendado)
   • kubectl configurado para interagir com o cluster
2. ​

   Adicione o repositório Helm do ClickStack

   Adicione o repositório Helm do ClickStack:

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

   Instalando o ClickStack

   Para instalar o chart do ClickStack com os valores padrão:

   helm install my-clickstack clickstack/clickstack
   
4. ​

   Verifique a instalação

   Verifique a instalação:

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

   Quando todos os pods estiverem prontos, prossiga.

5. ​

   Encaminhamento de portas

   O encaminhamento de portas permite acessar e configurar o HyperDX. Usuários que implantam em produção devem, em vez disso, expor o serviço por meio de uma Entrada ou de um balanceador de carga para garantir acesso adequado à rede, terminação TLS e escalabilidade. O encaminhamento de portas é mais indicado para desenvolvimento local ou tarefas administrativas pontuais, e não para ambientes de longo prazo ou de alta disponibilidade.

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

   Configuração da Entrada em produção

   Para implantações em produção, configure a entrada com TLS em vez de usar encaminhamento de porta. Consulte o guia de Configuração da Entrada para ver instruções detalhadas de configuração.

6. ​

   Acesse a UI

   Acesse http://localhost:8080 para abrir a UI do HyperDX.

   Crie um usuário, informando um nome de usuário e uma senha que atendam aos requisitos.

   Ao clicar em Create, as fontes de dados serão criadas para a instância do ClickHouse implantada por meio do Chart do Helm.

   Substituir a conexão padrão

   Você pode substituir a conexão padrão da instância integrada do ClickHouse. Para mais detalhes, consulte “Using ClickHouse Cloud”.

7. ​

   Personalizando valores (opcional)

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

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

   Como alternativa, edite o values.yaml. 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
   ingress:
     enabled: true
     annotations:
       kubernetes.io/ingress.class: nginx
     hosts:
       - host: hyperdx.example.com
         paths:
           - path: /
             pathType: ImplementationSpecific
   

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

   Usando secrets (opcional)

   Para lidar com dados sensíveis, como chaves de API ou credenciais de banco de dados, use secrets do Kubernetes. Os charts do Helm do HyperDX fornecem arquivos de secret padrão que você pode modificar e aplicar ao cluster.

   ​

   Usando secrets pré-configurados

   O chart do Helm inclui um template de secret padrão 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 template 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

   Se preferir, você pode criar manualmente um Secret personalizado no Kubernetes:

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

   ​

   Como referenciar um Secret

   Para referenciar um Secret em values.yaml:

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

   Gerenciamento de chaves de API

   Para instruções detalhadas sobre como configurar chaves de API, incluindo diferentes métodos de configuração e procedimentos para reiniciar pods do Kubernetes, consulte o guia de configuração de chaves de API.

​

Usando o ClickHouse Cloud

Se estiver usando o ClickHouse Cloud, desative a instância do ClickHouse implantada pelo Chart do Helm e informe as credenciais do Cloud:

# especificar credenciais do ClickHouse Cloud
export CLICKHOUSE_URL=<CLICKHOUSE_CLOUD_URL> # url https completa
export CLICKHOUSE_USER=<CLICKHOUSE_USER>
export CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>

# como substituir a conexão padrão
helm install my-clickstack clickstack/clickstack \
  --set clickhouse.enabled=false \
  --set clickhouse.persistence.enabled=false \
  --set otel.clickhouseEndpoint=${CLICKHOUSE_URL} \
  --set clickhouse.config.users.otelUser=${CLICKHOUSE_USER} \
  --set clickhouse.config.users.otelUserPassword=${CLICKHOUSE_PASSWORD}

Como alternativa, use o arquivo values.yaml:

clickhouse:
  enabled: false
  persistence:
    enabled: false
  config:
    users:
      otelUser: ${CLICKHOUSE_USER}
      otelUserPassword: ${CLICKHOUSE_PASSWORD}

otel:
  clickhouseEndpoint: ${CLICKHOUSE_URL}

hyperdx:
  defaultConnections: |
    [
      {
        "name": "External ClickHouse",
        "host": "http://your-clickhouse-server:8123",
        "port": 8123,
        "username": "your-username",
        "password": "your-password"
      }
    ]

helm install my-clickstack clickstack/clickstack -f values.yaml
# ou se já estiver instalado...
# helm upgrade my-clickstack clickstack/clickstack -f values.yaml

Configurações externas avançadas

Para implantações em produção com configuração baseada em Secret, OTel collectors externos ou configurações mínimas, consulte o guia de Opções de implantação.

​

Observações sobre produção

Por padrão, este chart também instala o ClickHouse e o OTel collector. No entanto, em produção, é recomendável gerenciar o ClickHouse e o OTel collector separadamente.

Para desabilitar o ClickHouse e o OTel collector, defina os seguintes valores:

helm install my-clickstack clickstack/clickstack \
  --set clickhouse.enabled=false \
  --set clickhouse.persistence.enabled=false \
  --set otel.enabled=false

Boas práticas para produção

Para implantações em produção, incluindo configuração de alta disponibilidade, gerenciamento de recursos, configuração de Entrada/TLS e configurações específicas de Cloud (GKE, EKS, AKS), consulte:

• Guia de configuração - Gerenciamento de Entrada, TLS e Secrets
• Implantações na Cloud - Configurações específicas de Cloud e checklist de produção

​

Configuração da tarefa

Por padrão, há uma tarefa na configuração do chart como um cronjob, responsável por verificar se os alertas devem ser acionados. Estas são as opções de configuração:

Parâmetro	Descrição	Padrão
tasks.enabled	Habilita/desabilita tarefas cron no cluster. Por padrão, a imagem do HyperDX executa as tarefas cron no processo. Altere para true se preferir usar uma tarefa cron separada no cluster.	false
tasks.checkAlerts.schedule	Agendamento cron da tarefa check-alerts	*/1 * * * *
tasks.checkAlerts.resources	Solicitações e limites de recursos da tarefa check-alerts	Consulte values.yaml

​

Atualizando o chart

Para atualizar para uma versão mais recente:

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

Para verificar as versões de chart disponíveis:

helm search repo clickstack

Atualização para v2.x

Se você quiser migrar para o chart v2.x baseado em subcharts, consulte o guia de atualização para ver as instruções de migração. Esta é uma mudança disruptiva — um helm upgrade no local não é compatível.

​

Desinstalar o ClickStack

Para remover a implantação:

helm uninstall my-clickstack

Isso removerá todos os recursos associados à release, mas os dados persistentes (se houver) poderão continuar lá.

​

Solução de problemas

​

Verificar logs

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

​

Depuração de uma instalação que falhou

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

​

Verificar a implantação

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

Recursos adicionais de solução de problemas

Para problemas relacionados à Entrada, problemas de TLS ou solução de problemas de implantação na nuvem, consulte:

• Solução de problemas de Entrada - Fornecimento de recursos, reescritas de caminho, problemas no navegador
• Implantações em Cloud - Problemas de OpAMP no GKE e problemas específicos de Cloud

​

Escolha de esquema: Map vs JSON

O ClickStack armazena atributos como colunas Map(LowCardinality(String), String) por padrão. Esse é o esquema recomendado para cargas de trabalho de observabilidade. Em combinação com a serialização de map em buckets e índices de texto nas chaves e nos valores do map, ele permite lookups seletivos sem a sobrecarga de ingestão por chave das subcolunas JSON dinâmicas.

Um esquema do tipo JSON está disponível em beta para avaliação em cargas de trabalho com um conjunto pequeno e estável de chaves de atributo. Ele não é recomendado como padrão. Consulte Map vs tipo JSON para ver a comparação completa e as variáveis de ambiente necessárias para habilitar o suporte a JSON.

​

Documentação relacionada

​

Guias de implantação v1.x

• Opções de implantação (v1.x) - ClickHouse externo, OTel collector e implantações mínimas
• Guia de configuração (v1.x) - API keys, Secrets e configuração de Entrada
• Implantações na Cloud (v1.x) - Configurações de GKE, EKS e AKS e melhores práticas para produção

​

documentação da v2.x

• Helm (v2.x) - guia de implantação da v2.x
• Guia de atualização - Migração da v1.x para a v2.x

​

Recursos adicionais

• Guia de primeiros passos do ClickStack - Introdução ao ClickStack
• Repositório dos charts do Helm do ClickStack - Código-fonte do chart e referência de valores
• Documentação do Kubernetes - Referência do Kubernetes
• Documentação do Helm - Referência do Helm