> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Helm
> Implantação do ClickStack com Helm - a stack de observabilidade do ClickHouse
export const Image = ({img, alt, size}) => {
return
;
};
**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](/pt-BR/clickstack/deployment/helm-v1). Para as etapas de migração, consulte o [guia de upgrade](/pt-BR/clickstack/deployment/helm-upgrade).
O chart do Helm do ClickStack pode ser encontrado [aqui](https://github.com/ClickHouse/ClickStack-helm-charts) 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](/pt-BR/products/kubernetes-operator/overview) 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](https://github.com/open-telemetry/opentelemetry-helm-charts) como subchart
* **MongoDB** — gerenciado pelo [MongoDB Kubernetes Operator (MCK)](https://github.com/mongodb/mongodb-kubernetes) 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](/pt-BR/clickstack/deployment/helm-additional-manifests) 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](https://helm.sh/) 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:
```shell theme={null}
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:
```shell theme={null}
helm install clickstack-operators clickstack/clickstack-operators
```
Espere até que os pods do operador estejam prontos antes de prosseguir:
```shell theme={null}
kubectl get pods -l app.kubernetes.io/instance=clickstack-operators
```
### Instale o ClickStack
Quando os operators estiverem em execução, instale o chart principal:
```shell theme={null}
helm install my-clickstack clickstack/clickstack
```
### Verifique a instalação
Verifique a instalação:
```shell theme={null}
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.
```shell theme={null}
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](/pt-BR/clickstack/deployment/helm-configuration#ingress-setup) para ver instruções detalhadas de configuração.
### Acesse a UI
Acesse [http://localhost:8080](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"](#using-clickhouse-cloud).
### Personalizando os valores (opcional)
Você pode personalizar as configurações usando as flags `--set`. Por exemplo:
```shell theme={null}
helm install my-clickstack clickstack/clickstack --set key=value
```
Como alternativa, edite o `values.yaml`. Para obter os valores padrão:
```shell theme={null}
helm show values clickstack/clickstack > values.yaml
```
Exemplo de configuração:
```yaml theme={null}
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"
```
```shell theme={null}
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:
```yaml theme={null}
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:
```yaml theme={null}
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](/pt-BR/clickstack/deployment/helm-configuration#api-key-setup).
## Usando ClickHouse Cloud
Se estiver usando ClickHouse Cloud, desative a instância incorporada do ClickHouse e forneça suas credenciais da Cloud:
```yaml theme={null}
# 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:
```bash theme={null}
cat < 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
```
```shell theme={null}
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](/pt-BR/clickstack/deployment/helm-deployment-options).
## 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:
```yaml theme={null}
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](/pt-BR/clickstack/deployment/helm-configuration) - Gerenciamento de Entrada, TLS e Secrets
* [Implantações no Cloud](/pt-BR/clickstack/deployment/helm-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:
```shell theme={null}
helm upgrade my-clickstack clickstack/clickstack -f values.yaml
```
Para verificar as versões disponíveis do chart:
```shell theme={null}
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](/pt-BR/clickstack/deployment/helm-upgrade) 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:
```shell theme={null}
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](https://github.com/mongodb/mongodb-kubernetes/tree/master/docs/mongodbcommunity)
## Solução de problemas
### Verificando os logs
```shell theme={null}
kubectl logs -l app.kubernetes.io/name=clickstack
```
### Depuração de uma instalação que falhou
```shell theme={null}
helm install my-clickstack clickstack/clickstack --debug --dry-run
```
### Verificar a implantação
```shell theme={null}
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](/pt-BR/clickstack/deployment/helm-configuration#troubleshooting-ingress) - Carregamento de assets, reescrita de caminhos, problemas no navegador
* [Implantações no Cloud](/pt-BR/clickstack/deployment/helm-cloud#loadbalancer-dns-resolution-issue) - 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](/pt-BR/reference/data-types/map#bucketed-map-serialization) 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](/pt-BR/clickstack/ingesting-data/schema/map-vs-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](/pt-BR/clickstack/deployment/helm-deployment-options) - ClickHouse externo, OTel collector e implantações mínimas
* [Guia de configuração](/pt-BR/clickstack/deployment/helm-configuration) - API keys, Secrets e configuração de Entrada
* [Implantações no Cloud](/pt-BR/clickstack/deployment/helm-cloud) - Configurações de GKE, EKS e AKS e melhores práticas de produção
* [Guia de atualização](/pt-BR/clickstack/deployment/helm-upgrade) - Migração da v1.x para a v2.x
* [Manifestos adicionais](/pt-BR/clickstack/deployment/helm-additional-manifests) - Implantação de objetos personalizados do Kubernetes junto com o chart
### Documentação v1.x
* [Helm (v1.x)](/pt-BR/clickstack/deployment/helm-v1) - guia de implantação do v1.x
* [Configuração (v1.x)](/pt-BR/clickstack/deployment/helm-configuration-v1) - configuração do v1.x
* [Opções de implantação (v1.x)](/pt-BR/clickstack/deployment/helm-deployment-options-v1) - opções de implantação do v1.x
* [Implantações no Cloud (v1.x)](/pt-BR/clickstack/deployment/helm-cloud-v1) - configurações da Cloud no v1.x
### Recursos adicionais
* [Guia de primeiros passos do ClickStack](/pt-BR/clickstack/getting-started) - Introdução ao ClickStack
* [Repositório de Charts do Helm do ClickStack](https://github.com/ClickHouse/ClickStack-helm-charts) - Código-fonte do chart e referência de valores
* [Documentação do Kubernetes](https://kubernetes.io/docs/) - Referência do Kubernetes
* [Documentação do Helm](https://helm.sh/docs/) - Referência do Helm