Helm

Implantação do ClickStack com Helm - a stack de observabilidade do ClickHouse

Versão 2.x do chart

Esta página documenta o chart do Helm baseado em subcharts v2.x. Se você ainda estiver usando o chart v1.x com templates inline, consulte o guia do Helm v1.x. Para as etapas de migração, consulte o guia de upgrade.

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

O chart v2.x usa uma instalação em duas fases. Os operators e as CRDs são instalados primeiro por meio do chart clickstack-operators, seguidos pelo chart principal clickstack, que cria recursos personalizados gerenciados por operator para ClickHouse, MongoDB e o OpenTelemetry Collector.

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

• ClickHouse — gerenciado pelo ClickHouse Operator por meio dos recursos personalizados ClickHouseCluster e KeeperCluster
• HyperDX — a UI e a API de observabilidade
• OpenTelemetry (OTel) collector — implantado por meio do chart oficial do Helm do OpenTelemetry Collector como subchart
• MongoDB — gerenciado pelo MongoDB Kubernetes Operator (MCK) por meio de um recurso personalizado MongoDBCommunity

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 padrão do Kubernetes, incluindo:

• Configuração específica por ambiente via values.yaml
• Limites de recursos e escalonamento no nível do pod
• Configuração de TLS e Entrada
• Gerenciamento de Secrets e configuração de autenticação
• manifestos adicionais para implantar objetos arbitrários do Kubernetes (NetworkPolicy, HPA, ALB Ingress etc.) junto com o chart

​

Indicado para

• Provas de conceito
• Produção

​

Etapas de implantação

1. ​

   Pré-requisitos

   • Helm v3+
   • cluster Kubernetes (v1.20+ recomendado)
   • kubectl configurado para interagir com o seu 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. ​

   Instale os operadores

   Instale primeiro o chart do operador. Isso registra as CRDs necessárias para o chart principal:

   helm install clickstack-operators clickstack/clickstack-operators
   

   Espere até que os pods do operador estejam prontos antes de prosseguir:

   kubectl get pods -l app.kubernetes.io/instance=clickstack-operators
   
4. ​

   Instale o ClickStack

   Quando os operators estiverem em execução, instale o chart principal:

   helm install my-clickstack clickstack/clickstack
   
5. ​

   Verifique a instalação

   Verifique a instalação:

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

   Quando todos os pods estiverem prontos, prossiga.

6. ​

   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, 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 de Entrada em produção

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

7. ​

   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 com o Chart do Helm.

   Substituindo 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”.

8. ​

   Personalizando os 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:

   hyperdx:
     frontendUrl: "https://hyperdx.example.com"
   
     deployment:
       replicas: 2
       resources:
         limits:
           cpu: "2"
           memory: 4Gi
         requests:
           cpu: 500m
           memory: 1Gi
   
     ingress:
       enabled: true
       host: hyperdx.example.com
       tls:
         enabled: true
         tlsSecretName: "hyperdx-tls"
   

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

   Usando Secrets (opcional)

   O chart v2.x usa um Secret unificado (clickstack-secret) preenchido a partir de hyperdx.secrets definidos nos seus values. Todas as variáveis de ambiente sensíveis — incluindo senhas do ClickHouse, senhas do MongoDB e a API key do HyperDX — passam por esse único Secret.

   Para substituir os valores do Secret:

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

   Para o gerenciamento externo de segredos (por exemplo, usando um operador de secrets), você pode fazer referência a um Secret do Kubernetes já existente:

   hyperdx:
     useExistingConfigSecret: true
     existingConfigSecret: "my-external-secret"
     existingConfigConnectionsKey: "connections.json"
     existingConfigSourcesKey: "sources.json"
   

   Gerenciamento de chaves de API

   Para obter instruções detalhadas sobre a configuração de chaves de API, incluindo vários métodos de configuração e procedimentos para reiniciar pods do Kubernetes, consulte o guia de configuração de chave de API.

​

Usando ClickHouse Cloud

Se estiver usando ClickHouse Cloud, desative a instância incorporada do ClickHouse e forneça suas credenciais da Cloud:

# values-clickhouse-cloud.yaml
clickhouse:
  enabled: false

hyperdx:
  secrets:
    CLICKHOUSE_PASSWORD: "your-cloud-password"
    CLICKHOUSE_APP_PASSWORD: "your-cloud-password"

  useExistingConfigSecret: true
  existingConfigSecret: "clickhouse-cloud-config"
  existingConfigConnectionsKey: "connections.json"
  existingConfigSourcesKey: "sources.json"

Crie o Secret de conexão separadamente:

cat <<EOF > connections.json
[
  {
    "name": "ClickHouse Cloud",
    "host": "https://your-cloud-instance.clickhouse.cloud",
    "port": 8443,
    "username": "default",
    "password": "your-cloud-password"
  }
]
EOF

kubectl create secret generic clickhouse-cloud-config \
  --from-file=connections.json=connections.json

rm connections.json

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

Configurações Externas Avançadas

Para implantações de 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.

​

Notas de produção

Por padrão, este chart instala ClickHouse, MongoDB e o OTel collector. Em produção, é recomendável gerenciar o ClickHouse e o OTel collector separadamente.

Para desativar o ClickHouse e o OTel collector:

clickhouse:
  enabled: false

otel-collector:
  enabled: false

Práticas recomendadas para produção

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

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

​

Configuração de 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. Na v2.x, a configuração da tarefa foi movida para hyperdx.tasks:

Parâmetro	Descrição	Padrão
hyperdx.tasks.enabled	Ativa/desativa tarefas cron no cluster. Por padrão, a imagem do HyperDX executa as tarefas cron no próprio processo. Altere para true se preferir usar uma tarefa cron separada no cluster.	false
hyperdx.tasks.checkAlerts.schedule	Agendamento cron da tarefa check-alerts	*/1 * * * *
hyperdx.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 disponíveis do chart:

helm search repo clickstack

Atualizando da v1.x

Se você está atualizando a partir do chart inline-template da v1.x, consulte o guia de atualização para obter instruções de migração. Esta é uma alteração incompatível — um helm upgrade in-place não é suportado.

​

Desinstalando o ClickStack

Desinstale na ordem inversa:

helm uninstall my-clickstack            # Remove o app + CRs primeiro
helm uninstall clickstack-operators     # Remove os operators + CRDs

Observação: As PersistentVolumeClaims criadas pelos operadores do MongoDB e do ClickHouse não são removidas com helm uninstall. Isso é intencional, para evitar perda acidental de dados. Para remover os PVCs, consulte:

• documentação do MongoDB Kubernetes Operator

​

Solução de problemas

​

Verificando os 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 específicos de Entrada, problemas de TLS ou para solucionar problemas em implantações no Cloud, consulte:

• Solução de problemas de Entrada - Carregamento de assets, reescrita de caminhos, problemas no navegador
• Implantações no Cloud - Problemas de OpAMP no GKE e problemas específicos do 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

• Opções de implantação - ClickHouse externo, OTel collector e implantações mínimas
• Guia de configuração - API keys, Secrets e configuração de Entrada
• Implantações no Cloud - Configurações de GKE, EKS e AKS e melhores práticas de produção
• Guia de atualização - Migração da v1.x para a v2.x
• Manifestos adicionais - Implantação de objetos personalizados do Kubernetes junto com o chart

​

Documentação v1.x

• Helm (v1.x) - guia de implantação do v1.x
• Configuração (v1.x) - configuração do v1.x
• Opções de implantação (v1.x) - opções de implantação do v1.x
• Implantações no Cloud (v1.x) - configurações da Cloud no v1.x

​

Recursos adicionais

• Guia de primeiros passos do ClickStack - Introdução ao ClickStack
• Repositório de 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