CloudBeaver Configuration

ChartVersion3.0.1TypeapplicationAppVersion25.3.0

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

Feature SupportLDAPsupportedS3supportedExternal DBsupportedIngresssupportedGateway APIsupported

What is CloudBeaver?

CloudBeaver is a cloud database manager that provides a rich web interface for database administration. It supports multiple database types and offers features like SQL editing, data browsing, and schema management. It is the web version of DBeaver — accessible via browser, without needing to install anything locally.

In the TDP context, CloudBeaver is the centralized interface for exploring and querying data in ClickHouse, Trino, and PostgreSQL directly from the browser, allowing developers and analysts to access data without local tool installation.

The tdp-cloudbeaver chart packages CloudBeaver 25.3.0 for Kubernetes.

Learn more

See CloudBeaver — Concepts for a complete overview of the tool, its architecture, and operation.

Why use CloudBeaver in TDP?

In TDP Kubernetes, databases run inside the cluster and are not directly accessible from your machine. CloudBeaver solves this: it runs inside the cluster, has access to all database services, and you access everything via a single web address.

Deployed components

Component	Description
CloudBeaver Server	Web server managing connections and sessions
Workspace	Persistent volume with user configurations and workspaces
External PostgreSQL integration (optional)	Database for CloudBeaver metadata when tdp-cloudbeaver.database.enabled: true

Helm Values Structure

The tdp-cloudbeaver chart distributes configuration across four main blocks:

• tdp-cloudbeaver: — CloudBeaver server configuration: image, service, persistence, admin credentials, datasources, LDAP, external metadata database.
• gatewayApi: — Gateway API configuration (HTTPRoute and Gateway for the web interface).
• TDP-Settings: — HTTP/HTTPS exposure control: chooses between Ingress and Gateway API.

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

tdp-cloudbeaver:
  persistence:
    size: 5Gi

Overview

Property	Value
Chart	tdp-cloudbeaver
CloudBeaver version	25.3.0
Chart version	3.0.1
Registry (OCI)	oci://registry.tecnisys.com.br/tdp/charts/tdp-cloudbeaver
Default port	8978
Default persistence	5Gi

Related pages

• Integrations — CloudBeaver: ClickHouse, Trino, S3/Ozone and automatic configuration (initialData).
• Security — CloudBeaver: LDAP authentication.
• External exposure: HTTP/HTTPS exposure via Ingress or Gateway API.

Prerequisites

Before installing CloudBeaver, ensure your infrastructure meets the following requirements:

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

Installation

Installation

Minimum installation via OCI registry:

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>

Example

Example

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

The chart is compatible with OpenShift. Before installation, confirm the SCC policy used by the cluster and align Security Context adjustments with the environment's operational standard.

For OpenShift and Rancher context, use the Orchestrator compatibility and security adjustments topic on the General Configuration page, in the Environment decisions that affect configuration tab.

Post-installation verification

After installation, verify that CloudBeaver started correctly:

Terminal input

# Pod status
kubectl get pods -n <NAMESPACE>

# Service
kubectl get svc -n <NAMESPACE>

# PVC
kubectl get pvc -n <NAMESPACE>

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

Main parameters

Main parameters

Server parameters

Parameter	Description	Default
tdp-cloudbeaver.image.registry	Container image registry	docker.io
tdp-cloudbeaver.image.repository	Image repository	dbeaver/cloudbeaver
tdp-cloudbeaver.image.tag	Image tag	25.3.0
tdp-cloudbeaver.service.type	Service type	ClusterIP
tdp-cloudbeaver.service.nodePorts.http	NodePort HTTP (only when service.type: NodePort)	""
tdp-cloudbeaver.persistence.enabled	Enable persistence	true
tdp-cloudbeaver.persistence.size	Persistent volume size	5Gi
tdp-cloudbeaver.persistence.storageClass	StorageClass (empty = cluster default)	""
tdp-cloudbeaver.persistence.existingClaim	Existing PVC (empty = create new)	""
tdp-cloudbeaver.resources.limits.cpu	CPU limit	1
tdp-cloudbeaver.resources.limits.memory	Memory limit	2Gi
tdp-cloudbeaver.resources.requests.cpu	CPU request	500m
tdp-cloudbeaver.resources.requests.memory	Memory request	1Gi
tdp-cloudbeaver.ingress.ingressClassName	IngressClass	""
tdp-cloudbeaver.ingress.hostname	Hostname for Ingress	cloudbeaver.tdp.local
tdp-cloudbeaver.ingress.path	Ingress path	/
tdp-cloudbeaver.ingress.pathType	Path type	ImplementationSpecific
tdp-cloudbeaver.ingress.annotations	Ingress annotations (e.g. nginx timeouts)	{}
tdp-cloudbeaver.ingress.tls	Enable TLS on Ingress	false
TDP-Settings.gateway.ingress.enabled	Create Ingress resource	false
TDP-Settings.gateway.gatewayApi.enabled	Create Gateway API resources	false

Automatic configuration parameters (initialData)

Parameter	Description	Default
tdp-cloudbeaver.initialData.enabled	Enable automatic configuration	false
tdp-cloudbeaver.initialData.name	ConfigMap name for initial-data	""
tdp-cloudbeaver.initialData.adminName	Admin username (cannot be admin)	""
tdp-cloudbeaver.initialData.adminPassword	Administrator password (⚠️ use a Secret in production)	""
tdp-cloudbeaver.adminSecret.enabled	Create Secret for admin credentials	false
tdp-cloudbeaver.adminSecret.name	Secret name	""
tdp-cloudbeaver.adminSecret.data	Secret data (key-value pairs)	{}

External database parameters

Parameter	Description	Default
tdp-cloudbeaver.database.enabled	Enable external PostgreSQL database	false
tdp-cloudbeaver.database.type	Database type	postgresql
tdp-cloudbeaver.database.host	PostgreSQL host	""
tdp-cloudbeaver.database.port	PostgreSQL port	5432
tdp-cloudbeaver.database.databaseName	Database name to create	""
tdp-cloudbeaver.database.schema	Database schema	public
tdp-cloudbeaver.database.user	CloudBeaver database user	""
tdp-cloudbeaver.database.driver	CloudBeaver database driver	postgres-jdbc
tdp-cloudbeaver.database.passwordSecret.name	Secret name with DB password	""
tdp-cloudbeaver.database.passwordSecret.key	Secret key with DB password	password
tdp-cloudbeaver.database.postgresSecret.name	Secret name with postgres admin password	""
tdp-cloudbeaver.database.postgresSecret.key	Secret key with postgres admin password	postgres-password
tdp-cloudbeaver.database.secret.enabled	Create DB password Secret via Helm	false

Configuration details

How external PostgreSQL works

When tdp-cloudbeaver.database.enabled: true, the chart configures CloudBeaver to use an external PostgreSQL database for metadata instead of the embedded database. This mode is recommended for production because it improves backup, scaling, and operational management.

The chart flow is:

1. create a pre-install Job that connects to PostgreSQL and prepares the dedicated CloudBeaver database;
2. create the dedicated CloudBeaver database user with the required permissions;
3. configure the CloudBeaver container through CLOUDBEAVER_DB_* environment variables;
4. start CloudBeaver already pointing to the external database.

The setup uses two distinct Secrets:

Secret	Use
tdp-cloudbeaver.database.passwordSecret	Password for the database user used by CloudBeaver
tdp-cloudbeaver.database.postgresSecret	PostgreSQL admin password used by the database creation Job

Variables used by CloudBeaver for the connection:

Variable	Use
CLOUDBEAVER_DB_DRIVER	JDBC driver, such as postgres-jdbc
CLOUDBEAVER_DB_URL	PostgreSQL JDBC URL
CLOUDBEAVER_DB_SCHEMA	Database schema used by CloudBeaver
CLOUDBEAVER_DB_USER	CloudBeaver database user
CLOUDBEAVER_DB_PASSWORD	Password read through secretKeyRef

To validate database creation, check the Job and its 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

If CloudBeaver does not connect to the external database, confirm the environment variables in the Pod and look for database errors in the 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

For the full list of parameters, run helm show values oci://registry.tecnisys.com.br/tdp/charts/tdp-cloudbeaver.

Automatic configuration (initialData)

The chart supports initialData.enabled: true to automatically provision CloudBeaver with pre-configured admin and initial settings, without the setup wizard.

Prerequisite: clean workspace

Automatic configuration only works on the first startup with an empty workspace. If CloudBeaver has already been configured, remove the workspace PVC before reinstalling.

To enable automatic configuration, set initialData.enabled: true and create or reference the admin password Secret before installation:

tdp-cloudbeaver:
  initialData:
    enabled: true
    name: tdp-cloudbeaver-initial-data
    adminName: cbadmin  # Cannot be "admin"

  adminSecret:
    enabled: true
    name: tdp-cloudbeaver-admin-secret
    data:
      password: "<PASSWORD>"  # Never commit passwords to Git

For details on initialData, validation, and troubleshooting, see Integrations — CloudBeaver.

Integrations (ClickHouse, Trino, S3)

Configure integrations with data sources and storage in your values file. See Integrations — CloudBeaver for detailed instructions, examples, and troubleshooting.

Development environment (smaller resources)

The snippet below reduces CPU, memory, and PVC size for development or lab clusters with few simultaneous users.

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

Existing PVC

To use an existing PVC instead of creating a new one:

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

The PVC specified in existingClaim must already exist in the installation namespace before running this command.

Access & Security

Access

With service.type: ClusterIP (default), access is via port-forward for local validation or via Ingress / Gateway API for external access with a stable hostname.

Port-forward

For local access:

Terminal input

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

Access CloudBeaver at http://localhost:8978.

NodePort (optional)

If the Service is configured with service.type: NodePort, access via a node IP and the allocated NodePort:

Terminal input

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

Access CloudBeaver at http://<NODE_IP>:<NODE_PORT>.

External exposure

To publish the web UI with a stable hostname, use Ingress or Gateway API. See External Exposure - CloudBeaver for complete Ingress, Gateway API, TLS, and troubleshooting examples.

Security (LDAP)

For LDAP authentication, see Security — CloudBeaver.

Troubleshooting

Troubleshooting

Pod not starting

Check pod logs:

Terminal input

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

Automatic configuration not working (setup wizard still appears)

1. Verify the ConfigMap is mounted:

   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. Check if the workspace is clean:

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

   If you find .cloudbeaver.runtime.conf, the workspace is not clean. Delete the PVC and reinstall:

   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. Verify ConfigMap content:

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

4. Check CloudBeaver logs:

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

Persistent volume issues

Check PVC status:

Terminal input

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

Service not accessible

Check service endpoints:

Terminal input

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

Database creation job failed

1. Check job status:

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

2. View job logs:

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

3. Common issues:

   • Secret not found: Ensure database.postgresSecret and database.passwordSecret exist
   • Connection refused: Verify PostgreSQL host and port are correct
   • Authentication failed: Check PostgreSQL admin password in secret
   • Permission denied: Ensure postgres user has permission to create databases

4. Manual cleanup (if needed):

   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 not connecting to external database

1. Verify environment variables:

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

2. Check CloudBeaver logs for database errors:

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

3. Test database connection from pod:

   kubectl exec -it -n <NAMESPACE> <POD_NAME> -- /bin/bash
   
   # Install psql client (if needed)
   apt-get update && apt-get install -y postgresql-client
   
   # Test connection
   psql -h <DATABASE_HOST> -U <DATABASE_USER> -d <DATABASE_NAME>

Uninstallation

Uninstallation

Remove the Helm release

Terminal input

helm uninstall <RELEASE_NAME> -n <NAMESPACE>

Example

Example

helm uninstall cloudbeaver -n tdp-project

This command removes the release resources (pods, services, ConfigMaps, Secrets). PVCs (volumes) are retained by default to preserve data and configurations.

To also remove PVCs associated with the chart (destructive and irreversible operation):

Terminal input

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

Delete the namespace

Terminal input

kubectl delete namespace <NAMESPACE>

warning

This will delete all resources in the namespace, including persistent volumes without a retention policy.