Helm (v1.x)

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

• Provas de conceito
• Produção

Pré-requisitos

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

Instalando o ClickStack

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

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, 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

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.

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

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

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

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

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:

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

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á.

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

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

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

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.

• 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

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

• 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