Integrações — CloudBeaver
Esta página detalha como configurar integrações do CloudBeaver com ClickHouse, Trino, S3/Ozone e initialData (provisionamento automático). O banco de metadados (PostgreSQL) é configurado na página de Configuração do CloudBeaver.
Visão geral das integrações
Escopo das integrações
Use cada bloco para uma finalidade diferente:
| Integração | Quando usar |
|---|---|
| ClickHouse | Pré-cadastrar uma conexão direta ao ClickHouse na UI do CloudBeaver |
| Trino | Pré-cadastrar uma conexão SQL federada pelo Trino |
| S3/Ozone | Injetar variáveis de ambiente para acesso S3 pela aplicação |
| initialData | Pular o assistente inicial e criar o administrador na primeira inicialização |
ClickHouse
Habilite esta integração quando os usuários precisarem consultar o ClickHouse nativo (HTTP 8123) — por exemplo explorar tabelas colunares e executar SQL diretamente no cluster analítico.
Se o fluxo principal da empresa passa só por Trino como camada SQL unificada, a integração Trino pode ser suficiente; ClickHouse direto continua útil para diagnóstico, tuning ou acesso a objetos expostos apenas no CH.
Arquitetura
O chart implementa uma configuração segura da fonte de dados com:
- Kubernetes Secret: armazena a senha do ClickHouse
- ConfigMap: contém o modelo
data-sources.json - InitContainer: copia a configuração para o workspace com as permissões corretas
- PVC: persiste a configuração
CloudBeaver Pod
InitContainer (busybox)
Mounts ConfigMap (read)
Copies to PVC (write)
Sets permissions
CloudBeaver Container
Reads workspace
Can modify via UI
Changes persist
ConfigMap Secret
Opção 1: Secret criado pelo Helm (desenvolvimento)
Para ambientes de desenvolvimento, deixe o Helm criar o Secret:
# values-clickhouse.yaml
tdp-cloudbeaver:
image:
registry: registry.tecnisys.com.br
repository: community/images/dbeaver/cloudbeaver
tag: latest
dataSources:
enabled: true
enabledClickhouse: true
clickhouseHost: "<CLICKHOUSE_SERVICE>.<NAMESPACE>.svc.cluster.local"
clickhousePort: 8123
database: "default"
user: "default"
# Criar Secret via Helm
secret:
enabled: true
name: <SECRET_NAME>
data:
password: "123456" # ALTERE EM PRODUÇÃO!
O campo dataSources.secret.data.password e dataSources.clickhouseTdpUser.password
gravam o valor diretamente no data-sources.json gerado pelo chart.
ConfigMaps não são criptografados no etcd por padrão.
Use esta abordagem apenas em desenvolvimento local.
Em produção, utilize dataSources.passwordSecret para referenciar um Kubernetes Secret
criado e gerenciado fora do chart.
Implante:
helm upgrade --install <RELEASE_NAME> oci://registry.tecnisys.com.br/tdp/charts/tdp-cloudbeaver \
-n <NAMESPACE> --create-namespace \
-f meu-values.yaml -f meu-values-clickhouse.yaml
Opção 2: Referência a um Secret existente (produção)
Em produção, crie o Secret manualmente e referencie-o:
Passo 1: criar o Secret:
kubectl create secret generic <SECRET_NAME> \
--from-literal=password='SecurePassword123!' \
-n <NAMESPACE>
Passo 2: referenciar no arquivo de valores:
tdp-cloudbeaver:
dataSources:
enabled: true
enabledClickhouse: true
clickhouseHost: "<CLICKHOUSE_SERVICE>.<NAMESPACE>.svc.cluster.local"
clickhousePort: 8123
database: "default"
user: "default"
# Referenciar Secret existente
passwordSecret:
name: <SECRET_NAME>
key: password
# Desativar Secret gerido pelo Helm
secret:
enabled: false
Passo 3: implantar:
helm upgrade --install <RELEASE_NAME> oci://registry.tecnisys.com.br/tdp/charts/tdp-cloudbeaver \
-n <NAMESPACE> --create-namespace \
-f meu-values.yaml
Para proteger credenciais em repositórios Git e no cluster, considere:
- Sealed Secrets — criptografa o Secret no Git; decripta no cluster via
kubeseal - External Secrets Operator (ESO) — sincroniza segredos de cofres externos (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, etc.)
- HashiCorp Vault — cofre centralizado com controle de acesso granular
Nunca commite senhas reais em repositórios Git.
Opção 3: Secret compartilhado entre componentes
Crie um Secret compartilhado usado pelo ClickHouse e pelo CloudBeaver:
kubectl create secret generic <SECRET_NAME> \
--from-literal=password='SharedPassword123!' \
-n <NAMESPACE>
Os dois charts referenciam o mesmo Secret:
ClickHouse:
helm upgrade --install <CLICKHOUSE_RELEASE> oci://registry.tecnisys.com.br/tdp/charts/tdp-clickhouse \
-n <NAMESPACE> --create-namespace \
--set tdp-clickhouse.clickhouse.defaultUser.password="SharedPassword123!"
CloudBeaver:
tdp-cloudbeaver:
dataSources:
enabledClickhouse: true
passwordSecret:
name: <SECRET_NAME>
key: password
O Secret referenciado em dataSources.passwordSecret.name deve existir no mesmo namespace
do release do CloudBeaver.
O Kubernetes não permite que pods acessem Secrets de outros namespaces sem configuração explícita.
Se precisar de acesso cross-namespace, utilize uma ferramenta de sincronização como
External Secrets Operator ou projete o Secret no namespace correto antes da instalação.
Secrets, RBAC e rotação
Para produção, prefira Secrets criados fora do chart e referenciados por dataSources.passwordSecret. Essa abordagem evita gravar senhas no data-sources.json e permite que a credencial seja gerida por ferramentas como Sealed Secrets, External Secrets Operator, Vault ou provedores de Secret externos.
Se o processo de deploy precisar ler Secrets de forma explícita, limite as permissões por RBAC ao nome do Secret necessário. Evite permissões amplas sobre todos os Secrets do namespace.
Para rotacionar a senha do ClickHouse:
- atualize o Secret referenciado por
dataSources.passwordSecret; - recrie o Pod do CloudBeaver para que a aplicação leia a credencial atualizada;
- confira os logs e valide a conexão na UI.
Sincronização de senhas
IMPORTANTE: a senha do ClickHouse no CloudBeaver TEM de coincidir com a senha real do ClickHouse.
Verificação manual
# Verificar senha do ClickHouse no Helm
helm get values <CLICKHOUSE_RELEASE> -n <NAMESPACE> | grep -A2 "defaultUser"
# Verificar ConfigMap do CloudBeaver
kubectl get configmap <CONFIGMAP_NAME> -n <NAMESPACE> -o yaml
# Verificar Secret do CloudBeaver
kubectl get secret <SECRET_NAME> -n <NAMESPACE> \
-o jsonpath='{.data.password}' | base64 -d && echo
Atualizar senhas
Para executar a rotação da senha do ClickHouse:
# 1. Atualizar Secret
kubectl create secret generic <SECRET_NAME> \
--from-literal=password='NewPassword456!' \
-n <NAMESPACE> \
--dry-run=client -o yaml | kubectl apply -f -
# 2. Apagar o pod para recriar com o novo Secret
kubectl delete pod -n <NAMESPACE> -l app.kubernetes.io/name=tdp-cloudbeaver
# 3. Verificar logs
kubectl logs -n <NAMESPACE> -l app.kubernetes.io/name=tdp-cloudbeaver | grep -i clickhouse
Parâmetros de configuração (ClickHouse)
| Parâmetro | Descrição | Padrão |
|---|---|---|
tdp-cloudbeaver.dataSources.enabled | Habilitar fonte ClickHouse | false |
tdp-cloudbeaver.dataSources.name | Nome do ConfigMap de datasources | tdp-cloudbeaver-data-sources |
tdp-cloudbeaver.dataSources.enabledClickhouse | Ativar ClickHouse | false |
tdp-cloudbeaver.dataSources.clickhouseHost | Host do ClickHouse | localhost |
tdp-cloudbeaver.dataSources.clickhousePort | Porta HTTP do ClickHouse | 8123 |
tdp-cloudbeaver.dataSources.database | Banco de dados padrão | default |
tdp-cloudbeaver.dataSources.user | Usuário | default |
tdp-cloudbeaver.dataSources.passwordSecret.name | Nome do Secret | "" |
tdp-cloudbeaver.dataSources.passwordSecret.key | Chave do Secret | password |
tdp-cloudbeaver.dataSources.secret.enabled | Criar Secret via Helm | false |
tdp-cloudbeaver.dataSources.clickhouseTdpUser.enabled | Criar Secret para o usuário TDP do ClickHouse | false |
tdp-cloudbeaver.dataSources.clickhouseTdpUser.password | Senha do usuário TDP (⚠️ não recomendado em produção) | "" |
Resolução de problemas (ClickHouse)
A conexão aparece, mas a senha está vazia
Se passwordSecret estiver configurado, a senha é deixada vazia de propósito em data-sources.json, para não guardar senhas em texto claro em ConfigMaps.
Solução: o CloudBeaver pedirá a senha no primeiro uso.
Informe uma vez e ela ficará armazenada no PVC.
Erro "Read-only file system"
O arquivo data-sources.json precisa ser gravável pelo CloudBeaver.
Verificar se o InitContainer executou:
kubectl logs -n <NAMESPACE> -l app.kubernetes.io/name=tdp-cloudbeaver \
-c sync-workspace-config
Verificar permissões do arquivo:
kubectl exec -n <NAMESPACE> deployment/<DEPLOYMENT_NAME> -- \
ls -la /opt/cloudbeaver/workspace/GlobalConfiguration/.dbeaver/data-sources.json
Esperado: -rw-rw-r-- 1 ...
Correção: apague o pod para forçar recriação:
kubectl delete pod -n <NAMESPACE> -l app.kubernetes.io/name=tdp-cloudbeaver
Trino
Use o conector Trino quando a equipe deve consultar fontes já expostas pelo Trino com a mesma experiência SQL na UI, em linha com o padrão de consumo do TDP descrito na introdução desta página.
O host e a porta devem apontar para o serviço Trino do cluster, não para o ClickHouse, salvo se a sua arquitetura explicitamente combinar outro desenho.
tdp-cloudbeaver:
dataSources:
enabled: true
enabledTrino: true
nameConnector: "Trino TDP"
trinoHost: "<TRINO_SERVICE>.<NAMESPACE>.svc.cluster.local"
trinoPort: 8080
database: "default"
user: "admin"
S3 compatível (Ozone, MinIO)
Use estas variáveis quando a equipe precisar que o CloudBeaver acesse arquivos ou exports em armazenamento compatível com S3 (Ozone, MinIO ou outro endpoint S3) a partir da aplicação — cenário distinto do cadastro de ClickHouse/Trino como data sources JDBC, embora possa coexistir com eles.
Passo 1: Criar Secret com credenciais S3:
kubectl create secret generic <S3_SECRET_NAME> \
--from-literal=access-key='<S3_ACCESS_KEY>' \
--from-literal=secret-key='<S3_SECRET_KEY>' \
-n <NAMESPACE>
Passo 2: Adicionar ao arquivo de valores:
tdp-cloudbeaver:
extraEnvVars:
- name: AWS_ACCESS_KEY_ID
valueFrom:
secretKeyRef:
name: "<S3_SECRET_NAME>"
key: access-key
- name: AWS_SECRET_ACCESS_KEY
valueFrom:
secretKeyRef:
name: "<S3_SECRET_NAME>"
key: secret-key
- name: AWS_DEFAULT_REGION
value: "<S3_REGION>"
- name: S3_ENDPOINT
value: "<S3_ENDPOINT>"
- name: S3_BUCKET
value: "<S3_BUCKET>"
Configuração automática (initialData)
Habilite esta opção para provisionar o CloudBeaver automaticamente, já com administrador e configurações iniciais pré-definidas, sem necessidade de assistente de configuração. Esse modo é indicado para GitOps, ambientes descartáveis e instalações sem intervenção manual.
O workspace deve estar vazio na primeira inicialização. Não reutilize o mesmo PVC de uma instalação interativa anterior sem limpeza ou ajuste prévio, pois os dados persistidos podem conflitar com a configuração automática.
Como funciona
A configuração automática utiliza um arquivo initial-data.conf montado no container do CloudBeaver em /opt/cloudbeaver/conf/.
Esse arquivo contém as configurações de administrador que o CloudBeaver lê na primeira inicialização, quando o workspace está vazio.
O arquivo é montado no container por extraVolumes e extraVolumeMounts.
Para habilitar esse modo, defina initialData.enabled: true e configure o Secret do administrador antes da instalação:
tdp-cloudbeaver:
initialData:
enabled: true
name: tdp-cloudbeaver-initial-data
adminName: cbadmin # Não pode ser "admin"
adminSecret:
enabled: true
name: tdp-cloudbeaver-admin-secret
data:
password: "<PASSWORD>" # Nunca commite a senha em repositórios Git
# Monta o arquivo initial-data.conf no container
extraVolumes:
- name: initial-data
configMap:
name: tdp-cloudbeaver-initial-data
extraVolumeMounts:
- name: initial-data
mountPath: /opt/cloudbeaver/conf/initial-data.conf
subPath: initial-data.conf
readOnly: true
Implantar com configuração automática
<RELEASE_NAME> é o nome do release Helm (o primeiro argumento de helm upgrade --install; costuma ser o identificador do projeto ou do ambiente).
O caminho .../charts/tdp-cloudbeaver no URL OCI é o nome do chart no registry da Tecnisys — não o substitua pelo nome do projeto.
Use o mesmo <NAMESPACE> da sua instalação.
Instalação nova (workspace limpo)
helm upgrade --install <RELEASE_NAME> \
oci://registry.tecnisys.com.br/tdp/charts/tdp-cloudbeaver \
--version <CHART_VERSION> \
-n <NAMESPACE> --create-namespace \
-f <VALUES_FILE>
helm upgrade --install cloudbeaver \
oci://registry.tecnisys.com.br/tdp/charts/tdp-cloudbeaver \
--version 3.0.1 \
-n tdp-project --create-namespace \
-f values-cloudbeaver.yaml
Acessar o CloudBeaver
kubectl -n <NAMESPACE> port-forward svc/<SERVICE_NAME> 8978:8978
A porta 8978 é a porta padrão da interface web do CloudBeaver.
Abra http://localhost:8978 e autentique-se com:
- Usuário:
cbadmin(valor padrão deinitialData.adminName; altere no seu arquivo de valores se necessário) - Senha: a senha configurada em
adminSecret.data.password
Workspace limpo obrigatório: a configuração automática só vale na primeira inicialização com workspace vazio.
Se o CloudBeaver já tiver sido configurado antes, remova o release e identifique o PVC de workspace antes de reinstalar:
helm uninstall <RELEASE_NAME> -n <NAMESPACE>
kubectl get pvc -n <NAMESPACE>
Remova apenas o PVC usado pelo workspace do CloudBeaver:
kubectl delete pvc -n <NAMESPACE> <PVC_NAME>
Não use kubectl delete pvc --all em namespaces compartilhados, pois esse comando remove todos os PVCs do namespace.
Para o comportamento exato de PVCs e rótulos, consulte a documentação do chart ou helm show values.
Validação após initialData
-
Confirmar se o ConfigMap está montado:
Terminal inputkubectl exec -n <NAMESPACE> <POD_NAME> -- ls -la /opt/cloudbeaver/conf/
kubectl exec -n <NAMESPACE> <POD_NAME> -- cat /opt/cloudbeaver/conf/initial-data.conf -
Confirmar se o workspace está limpo:
Terminal inputkubectl exec -n <NAMESPACE> <POD_NAME> -- ls -la /opt/cloudbeaver/workspace/.data/Se existir
.cloudbeaver.runtime.conf, o workspace não está limpo.
Remova o release, identifique o PVC do workspace e reinstale:Terminal inputhelm uninstall <RELEASE_NAME> -n <NAMESPACE>
kubectl get pvc -n <NAMESPACE>Remova apenas o PVC do workspace do CloudBeaver e volte a instalar:
Terminal inputkubectl delete pvc -n <NAMESPACE> <PVC_NAME>
helm upgrade --install <RELEASE_NAME> oci://registry.tecnisys.com.br/tdp/charts/tdp-cloudbeaver \
-n <NAMESPACE> --create-namespace \
-f meu-values.yamlNão use
kubectl delete pvc --allem namespaces compartilhados. -
Conteúdo do ConfigMap:
Terminal inputkubectl get configmap <CONFIGMAP_NAME> -n <NAMESPACE> -o yamlConfirme que o arquivo contém o formato JSON correto com
adminNameeadminPassword. -
Logs do CloudBeaver:
Terminal inputkubectl logs -n <NAMESPACE> -l app.kubernetes.io/name=tdp-cloudbeaver | grep -i configProcure mensagens sobre modo de configuração ou criação do administrador.
Combinando arquivos de valores
helm upgrade --install <RELEASE_NAME> \
oci://registry.tecnisys.com.br/tdp/charts/tdp-cloudbeaver \
-n <NAMESPACE> \
-f meu-values.yaml \
-f values-integracao.yaml
Esta abordagem permite separar configuração base e integrações em arquivos distintos para melhor legibilidade e reutilização.
Padrões Avançados
Múltiplas instâncias do CloudBeaver
Você pode instalar múltiplas instâncias em namespaces distintos (cada combinação <RELEASE_NAME> + <NAMESPACE> + <VALUES_FILE> representa um ambiente):
helm upgrade --install <RELEASE_NAME> \
oci://registry.tecnisys.com.br/tdp/charts/tdp-cloudbeaver \
-n <NAMESPACE> --create-namespace \
-f <VALUES_FILE>
Dois ambientes ilustrativos com nomes fixos:
helm upgrade --install cloudbeaver-dev \
oci://registry.tecnisys.com.br/tdp/charts/tdp-cloudbeaver \
-n cloudbeaver-dev --create-namespace \
-f values-dev.yaml
helm upgrade --install cloudbeaver-prod \
oci://registry.tecnisys.com.br/tdp/charts/tdp-cloudbeaver \
-n cloudbeaver-prod --create-namespace \
-f values-production.yaml
Compartilhar Secrets entre ClickHouse e CloudBeaver
Para sincronizar a mesma senha entre ClickHouse e CloudBeaver, use um Secret compartilhado (<SECRET_NAME>) e releases distintos (<CLICKHOUSE_RELEASE>, <CLOUDBEAVER_RELEASE>).
1. Criar Secret compartilhado:
# Defina a senha no shell (não commite em repositório)
export CLICKHOUSE_PASSWORD='<PASSWORD>'
kubectl create secret generic <SECRET_NAME> \
--from-literal=password="${CLICKHOUSE_PASSWORD}" \
-n <NAMESPACE>
export CLICKHOUSE_PASSWORD='MeuSenhaSegura123!'
kubectl create secret generic tdp-shared-clickhouse-password \
--from-literal=password="${CLICKHOUSE_PASSWORD}" \
-n <NAMESPACE>
2. Configurar ClickHouse para usar a senha:
helm upgrade --install <CLICKHOUSE_RELEASE> \
oci://registry.tecnisys.com.br/tdp/charts/tdp-clickhouse \
-n <NAMESPACE> --create-namespace \
--set tdp-clickhouse.clickhouse.defaultUser.password="${CLICKHOUSE_PASSWORD}"
helm upgrade --install tdp-clickhouse \
oci://registry.tecnisys.com.br/tdp/charts/tdp-clickhouse \
-n <NAMESPACE> --create-namespace \
--set tdp-clickhouse.clickhouse.defaultUser.password="${CLICKHOUSE_PASSWORD}"
3. Configurar CloudBeaver para referenciar o mesmo Secret:
tdp-cloudbeaver:
dataSources:
enabled: true
enabledClickhouse: true
clickhouseHost: "<CLICKHOUSE_SERVICE>.<NAMESPACE>.svc.cluster.local"
clickhousePort: 8123
database: "default"
user: "default"
# Referenciar o Secret compartilhado
passwordSecret:
name: <SECRET_NAME>
key: password
secret:
enabled: false
tdp-cloudbeaver:
dataSources:
passwordSecret:
name: tdp-shared-clickhouse-password
key: password
secret:
enabled: false
4. Implantar CloudBeaver:
helm upgrade --install <CLOUDBEAVER_RELEASE> \
oci://registry.tecnisys.com.br/tdp/charts/tdp-cloudbeaver \
-n <NAMESPACE> --create-namespace \
-f <VALUES_FILE>
helm upgrade --install tdp-cloudbeaver \
oci://registry.tecnisys.com.br/tdp/charts/tdp-cloudbeaver \
-n <NAMESPACE> --create-namespace \
-f values.yaml
Rotação de senhas coordenada
Para rotacionar a senha mantendo ambos os componentes sincronizados:
# 1. Atualizar Secret compartilhado
export NEW_PASSWORD='<PASSWORD>'
kubectl create secret generic <SECRET_NAME> \
--from-literal=password="${NEW_PASSWORD}" \
-n <NAMESPACE> \
--dry-run=client -o yaml | kubectl apply -f -
# 2. Atualizar ClickHouse
helm upgrade <CLICKHOUSE_RELEASE> \
oci://registry.tecnisys.com.br/tdp/charts/tdp-clickhouse \
-n <NAMESPACE> \
--set tdp-clickhouse.clickhouse.defaultUser.password="${NEW_PASSWORD}"
# 3. Aguardar ClickHouse estar pronto
kubectl rollout status statefulset/<STATEFULSET_NAME> -n <NAMESPACE>
# 4. Remover pod do CloudBeaver para forçar atualização
kubectl delete pod -n <NAMESPACE> -l app.kubernetes.io/name=tdp-cloudbeaver
# 5. Verificar conexão
kubectl logs -n <NAMESPACE> -l app.kubernetes.io/name=tdp-cloudbeaver | grep -i clickhouse
export NEW_PASSWORD='NovaSenhaSegura456!'
kubectl create secret generic tdp-shared-clickhouse-password \
--from-literal=password="${NEW_PASSWORD}" \
-n <NAMESPACE> \
--dry-run=client -o yaml | kubectl apply -f -
helm upgrade tdp-clickhouse \
oci://registry.tecnisys.com.br/tdp/charts/tdp-clickhouse \
-n <NAMESPACE> \
--set tdp-clickhouse.clickhouse.defaultUser.password="${NEW_PASSWORD}"
kubectl rollout status statefulset/tdp-clickhouse -n <NAMESPACE>
kubectl delete pod -n <NAMESPACE> -l app.kubernetes.io/name=tdp-cloudbeaver
kubectl logs -n <NAMESPACE> -l app.kubernetes.io/name=tdp-cloudbeaver | grep -i clickhouse