> ## 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 (v1.x)

> Implantação do ClickStack com o Chart do Helm inline-template v1.x

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

<Warning>
  **Descontinuado — chart v1.x**

  Esta página documenta o chart do Helm com template inline **v1.x**, que está em modo de manutenção e não receberá novos recursos. Para novas implantações, use o [chart v2.x](/pt-BR/clickstack/deployment/helm). Para migrar uma implantação v1.x existente, consulte o [guia de atualização](/pt-BR/clickstack/deployment/helm-upgrade).
</Warning>

O chart do Helm para o ClickStack pode ser encontrado [aqui](https://github.com/ClickHouse/ClickStack-helm-charts) 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

<div id="suitable-for">
  ### Indicado para
</div>

* Provas de conceito
* Produção

<div id="deployment-steps">
  ## Etapas de implantação
</div>

<br />

<Steps>
  <Step>
    ### Pré-requisitos

    * [Helm](https://helm.sh/) v3+
    * Cluster do Kubernetes (v1.20+ recomendado)
    * `kubectl` configurado para interagir com o cluster
  </Step>

  <Step>
    ### 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
    ```
  </Step>

  <Step>
    ### Instalando o ClickStack

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

    ```shell theme={null}
    helm install my-clickstack clickstack/clickstack
    ```
  </Step>

  <Step>
    ### 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.
  </Step>

  <Step>
    ### 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.

    ```shell theme={null}
    kubectl port-forward \
      pod/$(kubectl get pod -l app.kubernetes.io/name=clickstack -o jsonpath='{.items[0].metadata.name}') \
      8080:3000
    ```

    <Tip>
      **Configuração da Entrada em produção**

      Para implantações em produção, configure a entrada com TLS em vez de usar encaminhamento de porta. Consulte o [guia de Configuração da Entrada](/pt-BR/clickstack/deployment/helm-configuration-v1#ingress-setup) para ver instruções detalhadas de configuração.
    </Tip>
  </Step>

  <Step>
    ### 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.

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/16jdCy1HTWZ9Bvmz/images/use-cases/observability/hyperdx-login.png?fit=max&auto=format&n=16jdCy1HTWZ9Bvmz&q=85&s=6584c04fd42475189e28a0827d14d0f6" alt="UI do HyperDX" size="lg" width="3600" height="1900" data-path="images/use-cases/observability/hyperdx-login.png" />

    Ao clicar em `Create`, as fontes de dados serão criadas para a instância do ClickHouse implantada por meio do Chart do Helm.

    <Info>
      **Substituir 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).
    </Info>
  </Step>

  <Step>
    ### Personalizando 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}
    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
    ```

    ```shell theme={null}
    helm install my-clickstack clickstack/clickstack -f values.yaml
    ```
  </Step>

  <Step>
    ### 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`](https://github.com/ClickHouse/ClickStack-helm-charts/blob/main/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:

    ```yaml theme={null}
    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:

    ```shell theme={null}
    kubectl apply -f secrets.yaml
    ```

    #### Criando um Secret personalizado

    Se preferir, você pode criar manualmente um Secret personalizado no Kubernetes:

    ```shell theme={null}
    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`:

    ```yaml theme={null}
    hyperdx:
      apiKey:
        valueFrom:
          secretKeyRef:
            name: hyperdx-secret
            key: API_KEY
    ```

    <Tip>
      **Gerenciamento de chaves de API**

      Para instruções detalhadas sobre como configurar chaves de API, incluindo diferentes métodos de configuração e procedimentos para reiniciar pods do Kubernetes, consulte o [guia de configuração de chaves de API](/pt-BR/clickstack/deployment/helm-configuration-v1#api-key-setup).
    </Tip>
  </Step>
</Steps>

<div id="using-clickhouse-cloud">
  ## Usando o ClickHouse Cloud
</div>

Se estiver usando o ClickHouse Cloud, desative a instância do ClickHouse implantada pelo Chart do Helm e informe as credenciais do Cloud:

```shell theme={null}
# 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`:

```yaml theme={null}
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"
      }
    ]
```

```shell theme={null}
helm install my-clickstack clickstack/clickstack -f values.yaml
# ou se já estiver instalado...
# helm upgrade my-clickstack clickstack/clickstack -f values.yaml
```

<Tip>
  **Configurações externas avançadas**

  Para implantações em 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-v1).
</Tip>

<div id="production-notes">
  ## Observações sobre produção
</div>

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:

```shell theme={null}
helm install my-clickstack clickstack/clickstack \
  --set clickhouse.enabled=false \
  --set clickhouse.persistence.enabled=false \
  --set otel.enabled=false
```

<Tip>
  **Boas práticas para produção**

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

  * [Guia de configuração](/pt-BR/clickstack/deployment/helm-configuration-v1) - Gerenciamento de Entrada, TLS e Secrets
  * [Implantações na Cloud](/pt-BR/clickstack/deployment/helm-cloud-v1) - Configurações específicas de Cloud e checklist de produção
</Tip>

<div id="task-configuration">
  ## Configuração da tarefa
</div>

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:

| Parâmetro                     | Descrição                                                                                                                                                                                  | Padrão                 |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- |
| `tasks.enabled`               | Habilita/desabilita tarefas cron no cluster. Por padrão, a imagem do HyperDX executa as tarefas cron no processo. Altere para `true` se preferir usar uma tarefa cron separada no cluster. | `false`                |
| `tasks.checkAlerts.schedule`  | Agendamento cron da tarefa check-alerts                                                                                                                                                    | `*/1 * * * *`          |
| `tasks.checkAlerts.resources` | Solicitações e limites de recursos da tarefa check-alerts                                                                                                                                  | Consulte `values.yaml` |

<div id="upgrading-the-chart">
  ## Atualizando o chart
</div>

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 de chart disponíveis:

```shell theme={null}
helm search repo clickstack
```

<Info>
  **Atualização para v2.x**

  Se você quiser migrar para o chart v2.x baseado em subcharts, consulte o [guia de atualização](/pt-BR/clickstack/deployment/helm-upgrade) para ver as instruções de migração. Esta é uma mudança disruptiva — um `helm upgrade` no local não é compatível.
</Info>

<div id="uninstalling-clickstack">
  ## Desinstalar o ClickStack
</div>

Para remover a implantação:

```shell theme={null}
helm uninstall my-clickstack
```

Isso removerá todos os recursos associados à release, mas os dados persistentes (se houver) poderão continuar lá.

<div id="troubleshooting">
  ## Solução de problemas
</div>

<div id="checking-logs">
  ### Verificar logs
</div>

```shell theme={null}
kubectl logs -l app.kubernetes.io/name=clickstack
```

<div id="debugging-a-failed-install">
  ### Depuração de uma instalação que falhou
</div>

```shell theme={null}
helm install my-clickstack clickstack/clickstack --debug --dry-run
```

<div id="verifying-deployment">
  ### Verificar a implantação
</div>

```shell theme={null}
kubectl get pods -l app.kubernetes.io/name=clickstack
```

<Tip>
  **Recursos adicionais de solução de problemas**

  Para problemas relacionados à Entrada, problemas de TLS ou solução de problemas de implantação na nuvem, consulte:

  * [Solução de problemas de Entrada](/pt-BR/clickstack/deployment/helm-configuration-v1#troubleshooting-ingress) - Fornecimento de recursos, reescritas de caminho, problemas no navegador
  * [Implantações em Cloud](/pt-BR/clickstack/deployment/helm-cloud-v1#loadbalancer-dns-resolution-issue) - Problemas de OpAMP no GKE e problemas específicos de Cloud
</Tip>

<div id="schema-choice-map-vs-json">
  ## Escolha de esquema: Map vs JSON
</div>

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.

<div id="related-documentation">
  ## Documentação relacionada
</div>

<div id="deployment-guides">
  ### Guias de implantação v1.x
</div>

* [Opções de implantação (v1.x)](/pt-BR/clickstack/deployment/helm-deployment-options-v1) - ClickHouse externo, OTel collector e implantações mínimas
* [Guia de configuração (v1.x)](/pt-BR/clickstack/deployment/helm-configuration-v1) - API keys, Secrets e configuração de Entrada
* [Implantações na Cloud (v1.x)](/pt-BR/clickstack/deployment/helm-cloud-v1) - Configurações de GKE, EKS e AKS e melhores práticas para produção

<div id="v2x-documentation">
  ### documentação da v2.x
</div>

* [Helm (v2.x)](/pt-BR/clickstack/deployment/helm) - guia de implantação da v2.x
* [Guia de atualização](/pt-BR/clickstack/deployment/helm-upgrade) - Migração da v1.x para a v2.x

<div id="additional-resources">
  ### Recursos adicionais
</div>

* [Guia de primeiros passos do ClickStack](/pt-BR/clickstack/getting-started) - Introdução ao ClickStack
* [Repositório dos 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