Configuração do CloudBeaver

ChartVersion3.0.1TypeapplicationAppVersion25.3.0

CompatibilidadeKubernetes1.32+OpenShift4.19+Rancher2.10.x+

Suporte a recursosLDAPsuportadoS3suportadoExternal DBsuportadoIngresssuportadoGateway APIsuportado

O que é o CloudBeaver?

O CloudBeaver é um gerenciador de bancos de dados em nuvem que oferece uma interface web completa para administração de bancos de dados. Suporta múltiplos tipos de bancos de dados e oferece recursos como edição de SQL, navegação de dados e gerenciamento de esquemas. É a versão web do DBeaver — acessível pelo navegador, sem necessidade de instalar nada no computador do usuário.

No contexto do TDP, o CloudBeaver é a interface centralizada para explorar e consultar dados no ClickHouse, Trino e PostgreSQL diretamente pelo browser, permitindo que desenvolvedores e analistas acessem dados sem instalação local de ferramentas.

O chart tdp-cloudbeaver empacota o CloudBeaver 25.3.0 para Kubernetes.

Para saber mais

Consulte CloudBeaver — Conceitos para uma visão completa da ferramenta, sua arquitetura e funcionamento.

Por que usar o CloudBeaver no TDP?

No TDP Kubernetes, os bancos de dados ficam dentro do cluster e não são acessíveis diretamente da sua máquina. O CloudBeaver resolve esse problema: roda dentro do cluster, tem acesso a todos os serviços de banco de dados, e você acessa tudo via um único endereço web.

Componentes implantados

Componente	Descrição
CloudBeaver Server	Servidor web que gerencia conexões e sessões
Workspace	Volume persistente com configurações e workspaces dos usuários
Integração com PostgreSQL externo (opcional)	Banco usado para metadados do CloudBeaver quando tdp-cloudbeaver.database.enabled: true

Estrutura de valores (Helm)

O chart tdp-cloudbeaver distribui a configuração em quatro blocos principais:

• tdp-cloudbeaver: — configuração do servidor CloudBeaver: imagem, serviço, persistência, credenciais admin, datasources, LDAP, banco de metadados externo.
• gatewayApi: — configuração de Gateway API (HTTPRoute e Gateway para a interface web).
• TDP-Settings: — chave de controle da exposição HTTP/HTTPS: escolhe entre Ingress e Gateway API.

TDP-Settings:
  gateway:
    ingress:
      enabled: false
    gatewayApi:
      enabled: false

tdp-cloudbeaver:
  persistence:
    size: 5Gi

Visão geral

Propriedade	Valor
Chart	tdp-cloudbeaver
Versão do CloudBeaver	25.3.0
Versão do chart	3.0.1
Registry (OCI)	oci://registry.tecnisys.com.br/tdp/charts/tdp-cloudbeaver
Porta padrão	8978
Persistência padrão	5Gi

Páginas relacionadas

• Integrações — CloudBeaver: ClickHouse, Trino, S3/Ozone e configuração automática (initialData).
• Segurança — CloudBeaver: autenticação LDAP.
• Exposição externa: exposição HTTP/HTTPS por Ingress ou Gateway API.

Pré-requisitos

Antes de instalar o CloudBeaver, certifique-se de que sua infraestrutura atende aos seguintes requisitos:

• Kubernetes 1.32+, Red Hat OpenShift 4.19+ ou Rancher Manager 2.10.x+
• Helm 3.2.0+

Instalação

Instalação

Instalação mínima via registry OCI:

Terminal input

helm upgrade --install <RELEASE_NAME> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-cloudbeaver \
  --version <CHART_VERSION> \
  -n <NAMESPACE> \
  --create-namespace \
  -f <VALUES_FILE>

Exemplo

Exemplo

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

OpenShift

O chart é compatível com OpenShift. Antes da instalação, confirme a política de SCC adotada no cluster e alinhe os ajustes de Security Context com o padrão operacional do ambiente.

Para contextualizar OpenShift e Rancher, use o tópico Compatibilidade do orquestrador e ajustes de segurança na página Configuração Geral, aba Decisões de ambiente que afetam a configuração.

Verificação pós-instalação

Após a instalação, verifique se o CloudBeaver iniciou corretamente:

Terminal input

# Estado dos pods
kubectl get pods -n <NAMESPACE>

# Serviço
kubectl get svc -n <NAMESPACE>

# PVC
kubectl get pvc -n <NAMESPACE>

# Logs do container
kubectl logs -n <NAMESPACE> -l app.kubernetes.io/name=tdp-cloudbeaver

Parâmetros principais

Parâmetros principais

Parâmetros do servidor

Parâmetro	Descrição	Padrão
tdp-cloudbeaver.image.registry	Registry da imagem de container	docker.io
tdp-cloudbeaver.image.repository	Repositório da imagem	dbeaver/cloudbeaver
tdp-cloudbeaver.image.tag	Tag da imagem	25.3.0
tdp-cloudbeaver.service.type	Tipo de Service	ClusterIP
tdp-cloudbeaver.service.nodePorts.http	NodePort HTTP (só quando service.type: NodePort)	""
tdp-cloudbeaver.persistence.enabled	Habilitar persistência	true
tdp-cloudbeaver.persistence.size	Tamanho do volume persistente	5Gi
tdp-cloudbeaver.persistence.storageClass	StorageClass (vazio = padrão do cluster)	""
tdp-cloudbeaver.persistence.existingClaim	PVC existente (vazio = cria novo)	""
tdp-cloudbeaver.resources.limits.cpu	Limite de CPU	1
tdp-cloudbeaver.resources.limits.memory	Limite de memória	2Gi
tdp-cloudbeaver.resources.requests.cpu	Requisição de CPU	500m
tdp-cloudbeaver.resources.requests.memory	Requisição de memória	1Gi
tdp-cloudbeaver.ingress.ingressClassName	IngressClass	""
tdp-cloudbeaver.ingress.hostname	Hostname para Ingress	cloudbeaver.tdp.local
tdp-cloudbeaver.ingress.path	Path do Ingress	/
tdp-cloudbeaver.ingress.pathType	Tipo de path	ImplementationSpecific
tdp-cloudbeaver.ingress.annotations	Anotações do Ingress (ex.: timeouts nginx)	{}
tdp-cloudbeaver.ingress.tls	Habilitar TLS no Ingress	false
TDP-Settings.gateway.ingress.enabled	Criar recurso Ingress	false
TDP-Settings.gateway.gatewayApi.enabled	Criar recursos Gateway API	false

Parâmetros de configuração automática (initialData)

Parâmetro	Descrição	Padrão
tdp-cloudbeaver.initialData.enabled	Habilitar configuração automática	false
tdp-cloudbeaver.initialData.name	Nome do ConfigMap para initial-data	""
tdp-cloudbeaver.initialData.adminName	Usuário administrador (não pode ser admin)	""
tdp-cloudbeaver.initialData.adminPassword	Senha do administrador (⚠️ use Secret em produção)	""
tdp-cloudbeaver.adminSecret.enabled	Criar Secret para credenciais do admin	false
tdp-cloudbeaver.adminSecret.name	Nome do Secret	""
tdp-cloudbeaver.adminSecret.data	Dados do Secret (pares chave-valor)	{}

Parâmetros de banco de dados externo

Parâmetro	Descrição	Padrão
tdp-cloudbeaver.database.enabled	Habilitar banco de dados PostgreSQL externo	false
tdp-cloudbeaver.database.type	Tipo do banco de dados	postgresql
tdp-cloudbeaver.database.host	Host do PostgreSQL	""
tdp-cloudbeaver.database.port	Porta do PostgreSQL	5432
tdp-cloudbeaver.database.databaseName	Nome do banco de dados a criar	""
tdp-cloudbeaver.database.schema	Schema do banco de dados	public
tdp-cloudbeaver.database.user	Usuário do banco de dados do CloudBeaver	""
tdp-cloudbeaver.database.driver	Driver do banco de dados do CloudBeaver	postgres-jdbc
tdp-cloudbeaver.database.passwordSecret.name	Nome do Secret com a senha do banco	""
tdp-cloudbeaver.database.passwordSecret.key	Chave do Secret com a senha do banco	password
tdp-cloudbeaver.database.postgresSecret.name	Nome do Secret com a senha do admin do postgres	""
tdp-cloudbeaver.database.postgresSecret.key	Chave do Secret com a senha do admin do postgres	postgres-password
tdp-cloudbeaver.database.secret.enabled	Criar Secret de senha do banco via Helm	false

Detalhes de configuração

Como funciona o PostgreSQL externo

Quando tdp-cloudbeaver.database.enabled: true, o chart configura o CloudBeaver para usar um PostgreSQL externo como banco de metadados em vez do banco embutido. Esse modo é indicado para produção porque facilita backup, escala e gestão operacional.

O fluxo executado pelo chart é:

1. criar um Job de pré-instalação para conectar ao PostgreSQL e preparar o banco dedicado do CloudBeaver;
2. criar o usuário dedicado do CloudBeaver com as permissões necessárias;
3. configurar o container do CloudBeaver por variáveis de ambiente CLOUDBEAVER_DB_*;
4. iniciar o CloudBeaver já apontando para o banco externo.

As credenciais envolvem dois Secrets distintos:

Secret	Uso
tdp-cloudbeaver.database.passwordSecret	Senha do usuário de banco usado pelo CloudBeaver
tdp-cloudbeaver.database.postgresSecret	Senha do usuário administrador do PostgreSQL usada pelo Job de criação

Variáveis usadas pelo CloudBeaver para conexão:

Variável	Uso
CLOUDBEAVER_DB_DRIVER	Driver JDBC, como postgres-jdbc
CLOUDBEAVER_DB_URL	URL JDBC do PostgreSQL
CLOUDBEAVER_DB_SCHEMA	Schema de banco usado pelo CloudBeaver
CLOUDBEAVER_DB_USER	Usuário de banco do CloudBeaver
CLOUDBEAVER_DB_PASSWORD	Senha lida por secretKeyRef

Para validar a criação do banco, verifique o Job e os logs:

Terminal input

kubectl get jobs -n <NAMESPACE>
kubectl describe job <RELEASE_NAME>-create-db -n <NAMESPACE>
kubectl logs -n <NAMESPACE> -l job-name=<RELEASE_NAME>-create-db

Se o CloudBeaver não conectar ao banco externo, confirme as variáveis de ambiente no Pod e procure erros de banco nos logs:

Terminal input

kubectl get pod -n <NAMESPACE> -o yaml | grep -A 20 "env:"
kubectl logs -n <NAMESPACE> -l app.kubernetes.io/name=tdp-cloudbeaver | grep -i database

Para a lista completa de parâmetros, consulte helm show values oci://registry.tecnisys.com.br/tdp/charts/tdp-cloudbeaver.

Configuração automática (initialData)

O chart suporta initialData.enabled: true para provisionar o CloudBeaver automaticamente, com administrador e configurações iniciais pré-definidas, sem necessidade de assistente de configuração.

Pré-requisito: workspace limpo

A configuração automática só funciona na primeira inicialização com workspace vazio. Se o CloudBeaver já foi configurado, remova o PVC do workspace antes de reinstalar.

Para habilitar a configuração automática, defina initialData.enabled: true e crie ou referencie o Secret com a senha 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

Para detalhes de initialData, validação e resolução de problemas, consulte Integrações — CloudBeaver.

Integrações (ClickHouse, Trino, S3)

Configure integrações com fontes de dados e armazenamento no arquivo de valores. Consulte Integrações — CloudBeaver para instruções detalhadas, exemplos e resolução de problemas.

Ambiente de desenvolvimento (recursos menores)

O trecho abaixo reduz CPU, memória e tamanho de PVC para clusters de desenvolvimento ou laboratório com poucos usuários simultâneos.

tdp-cloudbeaver:
  service:
    type: ClusterIP
  resources:
    limits:
      cpu: "500m"
      memory: "1Gi"
    requests:
      cpu: "250m"
      memory: "512Mi"
  persistence:
    size: 2Gi

PVC existente

Se quiser usar um PVC existente em vez de criar um novo:

Terminal input

helm upgrade --install <RELEASE_NAME> oci://registry.tecnisys.com.br/tdp/charts/tdp-cloudbeaver \
  -n <NAMESPACE> --create-namespace \
  -f <VALUES_FILE> \
  --set tdp-cloudbeaver.persistence.existingClaim=<PVC_NAME>

note

O PVC informado em existingClaim deve existir previamente no namespace de instalação antes de executar este comando.

Acesso & Segurança

Acesso

Com service.type: ClusterIP (padrão), o acesso é feito por port-forward para validação local ou por Ingress / Gateway API para acesso externo com hostname estável.

Port-forward

Para acesso local:

Terminal input

kubectl -n <NAMESPACE> port-forward svc/<RELEASE_NAME> 8978:8978

Em seguida, acesse o CloudBeaver em http://localhost:8978.

NodePort (opcional)

Se o Service for configurado com service.type: NodePort, acesse pelo IP de um nó e a NodePort alocada:

Terminal input

kubectl -n <NAMESPACE> get svc <RELEASE_NAME>
kubectl -n <NAMESPACE> get nodes -o wide

Em seguida, acesse o CloudBeaver em http://<NODE_IP>:<NODE_PORT>.

Exposição externa

Para publicar a interface web com hostname estável, use Ingress ou Gateway API. Consulte Exposição externa — CloudBeaver para os exemplos completos de Ingress, Gateway API, TLS e resolução de problemas.

Segurança (LDAP)

Para autenticação LDAP, consulte Segurança — CloudBeaver.

Solução de problemas

Solução de problemas

Pod não iniciando

Verifique os logs do pod:

Terminal input

kubectl logs -n <NAMESPACE> -l app.kubernetes.io/name=tdp-cloudbeaver

Configuração automática não funcionando (assistente de configuração ainda aparece)

1. Verifique se o ConfigMap está montado:

   kubectl exec -n <NAMESPACE> <POD_NAME> -- ls -la /opt/cloudbeaver/conf/
   kubectl exec -n <NAMESPACE> <POD_NAME> -- cat /opt/cloudbeaver/conf/initial-data.conf

2. Verifique se o workspace está limpo:

   kubectl exec -n <NAMESPACE> <POD_NAME> -- ls -la /opt/cloudbeaver/workspace/.data/

   Se você encontrar .cloudbeaver.runtime.conf, o workspace não está limpo. Exclua o PVC e reinstale:

   helm uninstall <RELEASE_NAME> -n <NAMESPACE>
   kubectl delete pvc -n <NAMESPACE> --all
   helm upgrade --install <RELEASE_NAME> oci://registry.tecnisys.com.br/tdp/charts/tdp-cloudbeaver \
     -n <NAMESPACE> --create-namespace \
     -f <VALUES_FILE>

3. Verifique o conteúdo do ConfigMap:

   kubectl get configmap tdp-cloudbeaver-initial-data -n <NAMESPACE> -o yaml

4. Verifique os logs do CloudBeaver:

   kubectl logs -n <NAMESPACE> -l app.kubernetes.io/name=tdp-cloudbeaver | grep -i config

Problemas com volume persistente

Verifique o status do PVC:

Terminal input

kubectl get pvc -n <NAMESPACE>
kubectl describe pvc -n <NAMESPACE>

Serviço não acessível

Verifique os endpoints do serviço:

Terminal input

kubectl get endpoints -n <NAMESPACE>
kubectl describe svc <SERVICE_NAME> -n <NAMESPACE>

Falha no job de criação do banco de dados

1. Verifique o status do job:

   kubectl get jobs -n <NAMESPACE>
   kubectl describe job <RELEASE_NAME>-create-db -n <NAMESPACE>

2. Veja os logs do job:

   kubectl logs -n <NAMESPACE> -l job-name=<RELEASE_NAME>-create-db

3. Problemas comuns:

   • Secret não encontrado: Verifique se database.postgresSecret e database.passwordSecret existem
   • Conexão recusada: Confirme que host e porta do PostgreSQL estão corretos
   • Falha de autenticação: Verifique a senha do admin do PostgreSQL no secret
   • Permissão negada: Confirme que o usuário postgres tem permissão para criar bancos de dados

4. Limpeza manual (se necessário):

   kubectl delete job <RELEASE_NAME>-create-db -n <NAMESPACE>
   
   helm upgrade --install <RELEASE_NAME> oci://registry.tecnisys.com.br/tdp/charts/tdp-cloudbeaver \
     -n <NAMESPACE> \
     -f <VALUES_FILE>

CloudBeaver não conecta ao banco de dados externo

1. Verifique as variáveis de ambiente:

   kubectl get pod -n <NAMESPACE> -o yaml | grep -A 20 "env:"

2. Verifique os logs do CloudBeaver em busca de erros de banco de dados:

   kubectl logs -n <NAMESPACE> -l app.kubernetes.io/name=tdp-cloudbeaver | grep -i database

3. Teste a conexão com o banco de dados a partir do pod:

   kubectl exec -it -n <NAMESPACE> <POD_NAME> -- /bin/bash
   
   # Instale o cliente psql (se necessário)
   apt-get update && apt-get install -y postgresql-client
   
   # Teste a conexão
   psql -h <DATABASE_HOST> -U <DATABASE_USER> -d <DATABASE_NAME>

Desinstalação

Desinstalação

Remover o release Helm

Terminal input

helm uninstall <RELEASE_NAME> -n <NAMESPACE>

Exemplo

Exemplo

helm uninstall cloudbeaver -n tdp-project

Este comando remove os recursos do release (pods, services, ConfigMaps, Secrets). Os PVCs (volumes) são mantidos por padrão para preservar dados e configurações.

Para remover também os PVCs associados ao chart (operação destrutiva e irreversível):

Terminal input

kubectl delete pvc -n <NAMESPACE> -l app.kubernetes.io/name=tdp-cloudbeaver

Excluir o namespace

Terminal input

kubectl delete namespace <NAMESPACE>

warning

Isso irá excluir todos os recursos do namespace, incluindo volumes persistentes que não tiverem política de retenção.