Version 3.0

Integrations — CloudBeaver

ChartVersion3.0.1TypeapplicationAppVersion25.3.0

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

This page details how to configure CloudBeaver integrations with ClickHouse, Trino, S3/Ozone and automatic configuration (initialData). The metadata database (PostgreSQL) is configured on the CloudBeaver Configuration page.

Integrations overview

Integration Scope

Use each block for a different purpose:

Integration	When to use
ClickHouse	Pre-register a direct ClickHouse connection in the CloudBeaver UI
Trino	Pre-register a federated SQL connection through Trino
S3/Ozone	Inject environment variables for S3 access by the application
initialData	Skip the initial wizard and create the administrator on first startup

ClickHouse

Enable this integration when users need to query native ClickHouse (HTTP 8123) — for example to explore columnar tables and execute SQL directly on the analytics cluster.
If the main flow passes only through Trino as a unified SQL layer, the Trino integration may be sufficient; direct ClickHouse access remains useful for diagnostics, tuning, or accessing objects exposed only in CH.

Architecture

The chart implements a secure datasource configuration with:

Kubernetes Secret: stores the ClickHouse password
ConfigMap: contains the data-sources.json template
InitContainer: copies the configuration to the workspace with correct permissions
PVC: persists the configuration

   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

Option 1: Secret created by Helm (development)

For development environments, let Helm create the 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"

    # Create Secret via Helm
    secret:
      enabled: true
      name: <SECRET_NAME>
      data:
        password: "123456"  # CHANGE IN PRODUCTION!

Password in plain text in values.yaml

The dataSources.secret.data.password and dataSources.clickhouseTdpUser.password fields write the value directly into the data-sources.json generated by the chart.
ConfigMaps are not encrypted in etcd by default.
Use this approach only in local development.
In production, use dataSources.passwordSecret to reference a Kubernetes Secret created and managed outside the chart.

Deploy:

Terminal input
helm upgrade --install <RELEASE_NAME> oci://registry.tecnisys.com.br/tdp/charts/tdp-cloudbeaver \
  -n <NAMESPACE> --create-namespace \
  -f my-values.yaml -f my-values-clickhouse.yaml

Option 2: Reference to an existing Secret (production)

In production, create the Secret manually and reference it:

Step 1: create the Secret:

Terminal input
kubectl create secret generic <SECRET_NAME> \
  --from-literal=password='SecurePassword123!' \
  -n <NAMESPACE>

Step 2: reference it in the values file:

tdp-cloudbeaver:
  dataSources:
    enabled: true
    enabledClickhouse: true
    clickhouseHost: "<CLICKHOUSE_SERVICE>.<NAMESPACE>.svc.cluster.local"
    clickhousePort: 8123
    database: "default"
    user: "default"

    # Reference existing Secret
    passwordSecret:
      name: <SECRET_NAME>
      key: password

    # Disable Helm-managed Secret
    secret:
      enabled: false

Step 3: deploy:

Terminal input
helm upgrade --install <RELEASE_NAME> oci://registry.tecnisys.com.br/tdp/charts/tdp-cloudbeaver \
  -n <NAMESPACE> --create-namespace \
  -f my-values.yaml

Secure Secret management in production

To protect credentials in Git repositories and on the cluster, consider:

Sealed Secrets — encrypts the Secret in Git; decrypts it on the cluster via kubeseal
External Secrets Operator (ESO) — synchronizes secrets from external vaults (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, etc.)
HashiCorp Vault — centralized vault with granular access control

Never commit real passwords to Git repositories.

Option 3: Shared Secret between components

Create a shared Secret used by both ClickHouse and CloudBeaver:

Terminal input
kubectl create secret generic <SECRET_NAME> \
  --from-literal=password='SharedPassword123!' \
  -n <NAMESPACE>

Both charts reference the same Secret:

ClickHouse:

Terminal input
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

RBAC for Secrets

The Secret referenced in dataSources.passwordSecret.name must exist in the same namespace as the CloudBeaver release.
Kubernetes does not allow pods to access Secrets from other namespaces without explicit configuration.
If you need cross-namespace access, use a synchronization tool such as External Secrets Operator or project the Secret into the correct namespace before installation.

Secrets, RBAC, and Rotation

For production, prefer Secrets created outside the chart and referenced through dataSources.passwordSecret. This avoids writing passwords to data-sources.json and allows credentials to be managed through tools such as Sealed Secrets, External Secrets Operator, Vault, or external Secret providers.

If the deployment process needs to read Secrets explicitly, limit RBAC permissions to the required Secret name. Avoid broad permissions over all Secrets in the namespace.

To rotate the ClickHouse password:

update the Secret referenced by dataSources.passwordSecret;
recreate the CloudBeaver Pod so the application reads the updated credential;
check the logs and validate the connection in the UI.

Password synchronization

IMPORTANT: the ClickHouse password in CloudBeaver MUST match the actual ClickHouse password.

Manual verification

Terminal input
# Check ClickHouse password in Helm
helm get values <CLICKHOUSE_RELEASE> -n <NAMESPACE> | grep -A2 "defaultUser"

# Check CloudBeaver ConfigMap
kubectl get configmap <CONFIGMAP_NAME> -n <NAMESPACE> -o yaml

# Check CloudBeaver Secret
kubectl get secret <SECRET_NAME> -n <NAMESPACE> \
  -o jsonpath='{.data.password}' | base64 -d && echo

Update passwords

To rotate the ClickHouse password:

Terminal input
# 1. Update Secret
kubectl create secret generic <SECRET_NAME> \
  --from-literal=password='NewPassword456!' \
  -n <NAMESPACE> \
  --dry-run=client -o yaml | kubectl apply -f -

# 2. Delete the pod to recreate with the new Secret
kubectl delete pod -n <NAMESPACE> -l app.kubernetes.io/name=tdp-cloudbeaver

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

Configuration parameters (ClickHouse)

Parameter	Description	Default
`tdp-cloudbeaver.dataSources.enabled`	Enable ClickHouse data source	`false`
`tdp-cloudbeaver.dataSources.name`	Datasources ConfigMap name	`tdp-cloudbeaver-data-sources`
`tdp-cloudbeaver.dataSources.enabledClickhouse`	Enable ClickHouse	`false`
`tdp-cloudbeaver.dataSources.clickhouseHost`	ClickHouse host	`localhost`
`tdp-cloudbeaver.dataSources.clickhousePort`	ClickHouse HTTP port	`8123`
`tdp-cloudbeaver.dataSources.database`	Default database	`default`
`tdp-cloudbeaver.dataSources.user`	User	`default`
`tdp-cloudbeaver.dataSources.passwordSecret.name`	Secret name	`""`
`tdp-cloudbeaver.dataSources.passwordSecret.key`	Secret key	`password`
`tdp-cloudbeaver.dataSources.secret.enabled`	Create Secret via Helm	`false`
`tdp-cloudbeaver.dataSources.clickhouseTdpUser.enabled`	Create Secret for the ClickHouse TDP user	`false`
`tdp-cloudbeaver.dataSources.clickhouseTdpUser.password`	TDP user password (⚠️ not recommended in production)	`""`

Troubleshooting (ClickHouse)

Connection appears but password is empty

If passwordSecret is configured, the password is intentionally left empty in data-sources.json to avoid storing passwords in plain text in ConfigMaps.

Solution: CloudBeaver will ask for the password on first use.
Enter it once and it will be stored in the PVC.

Error "Read-only file system"

The data-sources.json file must be writable by CloudBeaver.

Check that the InitContainer ran:

Terminal input

kubectl logs -n <NAMESPACE> -l app.kubernetes.io/name=tdp-cloudbeaver \
  -c sync-workspace-config

Check file permissions:

Terminal input

kubectl exec -n <NAMESPACE> deployment/<DEPLOYMENT_NAME> -- \
  ls -la /opt/cloudbeaver/workspace/GlobalConfiguration/.dbeaver/data-sources.json

Expected: -rw-rw-r-- 1 ...

Fix: delete the pod to force recreation:

Terminal input

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

Trino

Use the Trino connector when the team needs to query sources already exposed by Trino with the same SQL experience in the UI, in line with the TDP consumption standard described in the introduction of this page.
The host and port must point to the Trino service in the cluster, not to ClickHouse, unless your architecture explicitly combines a different design.

tdp-cloudbeaver:
  dataSources:
    enabled: true
    enabledTrino: true
    nameConnector: "Trino TDP"
    trinoHost: "<TRINO_SERVICE>.<NAMESPACE>.svc.cluster.local"
    trinoPort: 8080
    database: "default"
    user: "admin"

S3-compatible storage (Ozone, MinIO)

Use these variables when the team needs CloudBeaver to access files or exports in S3-compatible storage (Ozone, MinIO, or another S3 endpoint) from the application — a distinct scenario from registering ClickHouse/Trino as JDBC data sources, although they can coexist.

Step 1: Create Secret with S3 credentials:

Terminal input
kubectl create secret generic <S3_SECRET_NAME> \
  --from-literal=access-key='<S3_ACCESS_KEY>' \
  --from-literal=secret-key='<S3_SECRET_KEY>' \
  -n <NAMESPACE>

Step 2: Add to the values file:

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>"

Automatic configuration (initialData)

Enable this option to provision CloudBeaver automatically, already with a pre-defined administrator and initial settings, without needing the configuration wizard. This mode is recommended for GitOps, disposable environments, and installations without manual intervention.

The workspace must be empty on first startup. Do not reuse the same PVC from a previous interactive installation without prior cleanup or adjustment, as persisted data may conflict with the automatic configuration.

How it works

Automatic configuration uses an initial-data.conf file mounted in the CloudBeaver container at /opt/cloudbeaver/conf/. This file contains the administrator settings that CloudBeaver reads on first startup, when the workspace is empty. The file is mounted in the container through extraVolumes and extraVolumeMounts.

To enable this mode, set initialData.enabled: true and configure the admin 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 repositories

  # Mount the initial-data.conf file in the 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

Deploy with automatic configuration

<RELEASE_NAME> is the Helm release name (the first argument of helm upgrade --install; usually the project or environment identifier).
The path .../charts/tdp-cloudbeaver in the OCI URL is the chart name in the Tecnisys registry — do not substitute it with the project name.
Use the same <NAMESPACE> as your installation.

New installation (clean workspace)

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

Access CloudBeaver

Terminal input

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

Port 8978 is the default port of the CloudBeaver web interface.

Open http://localhost:8978 and authenticate with:

User: cbadmin (default value of initialData.adminName; change in your values file if needed)
Password: the password configured in adminSecret.data.password

Important notices

Clean workspace required: automatic configuration only applies on the first startup with an empty workspace.

If CloudBeaver has already been configured, remove the release and identify the workspace PVC before reinstalling:

Terminal input

helm uninstall <RELEASE_NAME> -n <NAMESPACE>
kubectl get pvc -n <NAMESPACE>

Remove only the PVC used by the CloudBeaver workspace:

Terminal input

kubectl delete pvc -n <NAMESPACE> <PVC_NAME>

Do not use kubectl delete pvc --all in shared namespaces, as this command removes all PVCs in the namespace.

For the exact PVC behavior and labels, consult the chart documentation or helm show values.

Validation after initialData

Confirm the ConfigMap is mounted:

Terminal input

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

Confirm the workspace is clean:

Terminal input

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

If .cloudbeaver.runtime.conf exists, the workspace is not clean.
Remove the release, identify the workspace PVC, and reinstall:

Terminal input

helm uninstall <RELEASE_NAME> -n <NAMESPACE>
kubectl get pvc -n <NAMESPACE>

Remove only the CloudBeaver workspace PVC and reinstall:

Terminal input
kubectl 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 my-values.yaml

Do not use kubectl delete pvc --all in shared namespaces.

ConfigMap content:
Terminal input
```
kubectl get configmap <CONFIGMAP_NAME> -n <NAMESPACE> -o yaml
```
Ensure the file contains the correct JSON format with adminName and adminPassword.
CloudBeaver logs:
Terminal input
```
kubectl logs -n <NAMESPACE> -l app.kubernetes.io/name=tdp-cloudbeaver | grep -i config
```
Look for messages about configuration mode or admin creation.

Combining values files

Terminal input
helm upgrade --install <RELEASE_NAME> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-cloudbeaver \
  -n <NAMESPACE> \
  -f my-values.yaml \
  -f values-integration.yaml

This approach separates base configuration and integrations into distinct files for better readability and reuse.

Advanced patterns

Multiple CloudBeaver instances

You can install multiple instances in separate namespaces (each <RELEASE_NAME> + <NAMESPACE> + <VALUES_FILE> combination represents an environment):

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

Example

Two illustrative environments with fixed names:

Example
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

To synchronize the same password between ClickHouse and CloudBeaver, use a shared Secret (<SECRET_NAME>) and separate releases (<CLICKHOUSE_RELEASE>, <CLOUDBEAVER_RELEASE>).

1. Create shared Secret:

Terminal input
# Set the password in the shell (do not commit to repository)
export CLICKHOUSE_PASSWORD='<PASSWORD>'

kubectl create secret generic <SECRET_NAME> \
  --from-literal=password="${CLICKHOUSE_PASSWORD}" \
  -n <NAMESPACE>

Example

Example
export CLICKHOUSE_PASSWORD='MySecurePassword123!'

kubectl create secret generic tdp-shared-clickhouse-password \
  --from-literal=password="${CLICKHOUSE_PASSWORD}" \
  -n <NAMESPACE>

2. Configure ClickHouse to use the password:

Terminal input
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}"

Example

Example
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. Configure CloudBeaver to reference the same Secret:

tdp-cloudbeaver:
  dataSources:
    enabled: true
    enabledClickhouse: true
    clickhouseHost: "<CLICKHOUSE_SERVICE>.<NAMESPACE>.svc.cluster.local"
    clickhousePort: 8123
    database: "default"
    user: "default"

    # Reference the shared Secret
    passwordSecret:
      name: <SECRET_NAME>
      key: password

    secret:
      enabled: false

Example

Example
tdp-cloudbeaver:
  dataSources:
    passwordSecret:
      name: tdp-shared-clickhouse-password
      key: password
    secret:
      enabled: false

4. Deploy CloudBeaver:

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

Example

Example
helm upgrade --install tdp-cloudbeaver \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-cloudbeaver \
  -n <NAMESPACE> --create-namespace \
  -f values.yaml

Coordinated password rotation

To rotate the password while keeping both components synchronized:

Terminal input
# 1. Update shared Secret
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. Update 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. Wait for ClickHouse to be ready
kubectl rollout status statefulset/<STATEFULSET_NAME> -n <NAMESPACE>

# 4. Delete the CloudBeaver pod to force update
kubectl delete pod -n <NAMESPACE> -l app.kubernetes.io/name=tdp-cloudbeaver

# 5. Verify connection
kubectl logs -n <NAMESPACE> -l app.kubernetes.io/name=tdp-cloudbeaver | grep -i clickhouse

Example

Example
export NEW_PASSWORD='NewSecurePassword456!'

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

Integrations overview​

Integration Scope​

ClickHouse​

Architecture​

Option 1: Secret created by Helm (development)​

Option 2: Reference to an existing Secret (production)​

Option 3: Shared Secret between components​

Secrets, RBAC, and Rotation​

Password synchronization​

Manual verification​

Update passwords​

Configuration parameters (ClickHouse)​

Troubleshooting (ClickHouse)​

Connection appears but password is empty​

Error "Read-only file system"​

Trino​

S3-compatible storage (Ozone, MinIO)​

Automatic configuration (initialData)​

How it works​

Deploy with automatic configuration​

Validation after initialData​

Combining values files​

Advanced patterns​

Multiple CloudBeaver instances​

Sharing Secrets between ClickHouse and CloudBeaver​

Coordinated password rotation​

Integrations overview

Integration Scope

ClickHouse

Architecture

Option 1: Secret created by Helm (development)

Option 2: Reference to an existing Secret (production)

Option 3: Shared Secret between components

Secrets, RBAC, and Rotation

Password synchronization

Manual verification

Update passwords

Configuration parameters (ClickHouse)

Troubleshooting (ClickHouse)

Connection appears but password is empty

Error "Read-only file system"

Trino

S3-compatible storage (Ozone, MinIO)

Automatic configuration (initialData)

How it works

Deploy with automatic configuration

Validation after initialData

Combining values files

Advanced patterns

Multiple CloudBeaver instances

Sharing Secrets between ClickHouse and CloudBeaver

Coordinated password rotation