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 gestor de bases de dados em nuvem que fornece uma interface web completa para administração de bases de dados. Suporta múltiplos tipos de bases de dados e oferece funcionalidades como edição de SQL, navegação de dados e gestão de esquemas. É a versão web do DBeaver — acessível pelo navegador, sem necessidade de instalar nada localmente.

No contexto do TDP, o CloudBeaver é a interface centralizada para explorar e consultar dados no ClickHouse, Trino e PostgreSQL directamente pelo navegador, permitindo que programadores e analistas acedam a 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, a sua arquitectura e funcionamento.

Por que usar o CloudBeaver no TDP?

No TDP Kubernetes, as bases de dados ficam dentro do cluster e não são acessíveis directamente a partir da sua máquina. O CloudBeaver resolve este problema: corre dentro do cluster, tem acesso a todos os serviços de bases de dados, e acede a tudo através de um único endereço web.

Componentes implantados

Componente	Descrição
CloudBeaver Server	Servidor web que gere conexões e sessões
Workspace	Volume persistente com configurações e workspaces dos usuários
Integração com PostgreSQL externo (opcional)	Base de dados 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 do administrador, datasources, LDAP, base de dados de metadados externa.
• gatewayApi: — configuração de Gateway API (HTTPRoute e Gateway para a interface web).
• TDP-Settings: — chave de controlo 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 predefinida	8978
Persistência predefinida	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 a sua infraestrutura cumpre os 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 adoptada 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, separador 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 correctamente:

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	Valor por omissã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 = criar 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	Valor por omissã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	Palavra-passe do administrador (⚠️ use Secret em produção)	""
tdp-cloudbeaver.adminSecret.enabled	Criar Secret para credenciais do administrador	false
tdp-cloudbeaver.adminSecret.name	Nome do Secret	""
tdp-cloudbeaver.adminSecret.data	Dados do Secret (pares chave-valor)	{}

Parâmetros de base de dados externa

Parâmetro	Descrição	Valor por omissão
tdp-cloudbeaver.database.enabled	Habilitar base de dados PostgreSQL externa	false
tdp-cloudbeaver.database.type	Tipo de base de dados	postgresql
tdp-cloudbeaver.database.host	Host do PostgreSQL	""
tdp-cloudbeaver.database.port	Porta do PostgreSQL	5432
tdp-cloudbeaver.database.databaseName	Nome da base de dados a criar	""
tdp-cloudbeaver.database.schema	Schema da base de dados	public
tdp-cloudbeaver.database.user	Usuário da base de dados do CloudBeaver	""
tdp-cloudbeaver.database.driver	Driver da base de dados do CloudBeaver	postgres-jdbc
tdp-cloudbeaver.database.passwordSecret.name	Nome do Secret com a palavra-passe da base de dados	""
tdp-cloudbeaver.database.passwordSecret.key	Chave do Secret com a palavra-passe da base de dados	password
tdp-cloudbeaver.database.postgresSecret.name	Nome do Secret com a palavra-passe do administrador do postgres	""
tdp-cloudbeaver.database.postgresSecret.key	Chave do Secret com a palavra-passe do administrador do postgres	postgres-password
tdp-cloudbeaver.database.secret.enabled	Criar Secret de palavra-passe da base de dados 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 base de dados de metadados em vez da base de dados embutida. Este modo é recomendado 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 a base de dados dedicada do CloudBeaver;
2. criar o usuário dedicado do CloudBeaver com as permissões necessárias;
3. configurar o contentor do CloudBeaver por variáveis de ambiente CLOUDBEAVER_DB_*;
4. iniciar o CloudBeaver já apontando para a base de dados externa.

As credenciais envolvem dois Secrets distintos:

Secret	Uso
tdp-cloudbeaver.database.passwordSecret	Palavra-passe do usuário de base de dados usado pelo CloudBeaver
tdp-cloudbeaver.database.postgresSecret	Palavra-passe do 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 base de dados usado pelo CloudBeaver
CLOUDBEAVER_DB_USER	Usuário de base de dados do CloudBeaver
CLOUDBEAVER_DB_PASSWORD	Palavra-passe lida por secretKeyRef

Para validar a criação da base de dados, 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 à base de dados externa, confirme as variáveis de ambiente no Pod e procure erros de base de dados 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, execute 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á tiver sido configurado, remova o PVC do workspace antes de reinstalar.

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

Para utilizar 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>

nota

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

Acesso & Segurança

Acesso

Com service.type: ClusterIP (predefiniçã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, aceda ao CloudBeaver em http://localhost:8978.

NodePort (opcional)

Se o Service for configurado com service.type: NodePort, aceda 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, aceda ao 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.

Resolução de problemas

Resolução de problemas

Pod não inicia

Verifique os logs do pod:

Terminal input

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

Configuração automática não funciona (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 encontrar .cloudbeaver.runtime.conf, o workspace não está limpo. Elimine 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 da base de dados

1. Verifique o estado do job:

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

2. Consulte os logs do job:

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

3. Problemas frequentes:

   • Secret não encontrado: verifique se database.postgresSecret e database.passwordSecret existem
   • Conexão recusada: confirme host e porta do PostgreSQL
   • Falha de autenticação: verifique a palavra-passe do administrador do PostgreSQL no secret
   • Permissão negada: confirme que o usuário postgres tem permissão para criar bases 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 à base de dados externa

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 base de dados:

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

3. Teste a conexão com a base 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 omissã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

Eliminar o namespace

Terminal input

kubectl delete namespace <NAMESPACE>

aviso

Isto irá eliminar todos os recursos do namespace, incluindo volumes persistentes sem política de retenção.