Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Helm

View as MarkdownEdit this pageReport an issueSet up docs MCP

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:

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


Pré-requisitos

  • Helm v3+
  • cluster Kubernetes (v1.20+ recomendado)
  • kubectl configurado para interagir com o seu cluster

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

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

Instale o ClickStack

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

helm install my-clickstack clickstack/clickstack

Verifique a instalação

Verifique a instalação:

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

Quando todos os pods estiverem prontos, prossiga.

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

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

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"

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

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

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

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:

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

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.

Guias de implantação

Documentação v1.x

Recursos adicionais

Navigation