Helm - ClickHouse Documentation

Versão 2.x do chartEsta 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

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

Configuração de Entrada em produçãoPara 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.

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ãoVocê pode substituir a conexão padrão da instância integrada do ClickHouse. Para mais detalhes, consulte “Using ClickHouse Cloud”.

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"

Gerenciamento de chaves de APIPara 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çadasPara 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çãoPara 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.xSe 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 problemasPara 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.

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

​Indicado para

​Etapas de implantação

​Pré-requisitos

​Adicione o repositório Helm do ClickStack

​Instale os operadores

​Instale o ClickStack

​Verifique a instalação

​Encaminhamento de portas

​Acesse a UI

​Personalizando os valores (opcional)

​Usando Secrets (opcional)

​Usando ClickHouse Cloud

​Notas de produção

​Configuração de tarefa

​Atualizando o chart

​Desinstalando o ClickStack

​Solução de problemas

​Verificando os logs

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

​Verificar a implantação

​Escolha de esquema: Map vs JSON

​Documentação relacionada

​Guias de implantação

​Documentação v1.x

​Recursos adicionais

Indicado para

Etapas de implantação

Pré-requisitos

Adicione o repositório Helm do ClickStack

Instale os operadores

Instale o ClickStack

Verifique a instalação

Encaminhamento de portas

Acesse a UI

Personalizando os valores (opcional)

Usando Secrets (opcional)

Usando ClickHouse Cloud

Notas de produção

Configuração de tarefa

Atualizando o chart

Desinstalando o ClickStack

Solução de problemas

Verificando os logs

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

Verificar a implantação

Escolha de esquema: Map vs JSON

Documentação relacionada

Guias de implantação

Documentação v1.x

Recursos adicionais