DBeaver

Overview

DBeaver is a database administration tool that manages many database engines from one interface. This template deploys the self-hosted CloudBeaver web application — the browser-based edition of DBeaver — giving you a SQL editor, connection manager, and data browser for PostgreSQL, MySQL, MariaDB, MongoDB, Redis, SQLite, Oracle, SQL Server, and more. The template runs a single CloudBeaver instance on a persistent workspace volume. The admin account is bootstrapped from an opaque secret you create before installing, and the console is reachable only from inside the GVC until you deliberately publish it.

This template does not create a GVC. It deploys into an existing GVC that you already have.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-dbeaver`	CloudBeaver server and web UI on port `8978` (stateful, 1 replica; CPU autoscaling can add up to 3)	—
Volume Set	`RELEASE_NAME-dbeaver-vs`	10 GiB `ext4` volume at `/opt/cloudbeaver/workspace` holding server configuration, saved connections, and user accounts	—
Identity	`RELEASE_NAME-dbeaver-identity`	Identity bound to the workload	—
Policy	`RELEASE_NAME-dbeaver-policy`	Grants the identity `reveal` on exactly the admin-password secret you created	—

The chart creates no secret of its own. The only credential lives in the prerequisite secret you own.

Prerequisites

One opaque secret must exist before you install. The admin password guards a database administration console, and whoever holds it can query every database that console is connected to — so it is never a Helm value and never lands in the release.

Create the admin password secret

Choose your own strong password — at least 8 characters — and store it as the secret’s payload. Secrets are org-level, so there is no --gvc flag:

printf '%s' 'YOUR-STRONG-PASSWORD' | cpln secret create-opaque --name SECRET_NAME --encoding plain -f -

Set admin.passwordSecretName to this name.

Pick an admin login name

Set admin.name to the login name you want. It is not sensitive and stays a plain value; the default is cbadmin.

A missing prerequisite secret wedges the install rather than failing it. cpln helm install reports success and creates all four resources, but the workload never starts. There are no container logs to diagnose from, because the container never ran. The only place the missing secret is named is status.versions[].message:

cpln workload get-deployments RELEASE_NAME-dbeaver --gvc GVC_NAME -o yaml

Look for

The secret SECRET_NAME no longer exists. Workload updates are paused until the secret is added or the reference to the secret removed.

Create the secret and the deployment recovers on its own; to skip the wait, run cpln workload force-redeployment RELEASE_NAME-dbeaver --gvc GVC_NAME.

Nothing else is required for a default install.

Installation

Install the template into an existing GVC, naming the admin-password secret you created:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/dbeaver \
  --version 1.3.0 --gvc GVC_NAME \
  --set admin.passwordSecretName=SECRET_NAME

To install using another method, follow the instructions for your preferred tool:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

Image

image: dbeaver/cloudbeaver:25.2.0

admin:
  name: cbadmin # admin login name (not sensitive)
  passwordSecretName: my-dbeaver-admin-password # opaque secret holding the admin password; must EXIST BEFORE INSTALL

The chart passes admin.name to CloudBeaver as CB_ADMIN_NAME and references the secret as CB_ADMIN_PASSWORD: cpln://secret/SECRET_NAME.payload, so the password itself never appears in the workload spec or the Helm release.

Both values are applied only when an empty workspace is first initialized. On every later start CloudBeaver reads the account it already stored in its workspace database and ignores the environment. Rotating the secret or changing admin.name afterwards changes what the container sees and changes nothing about who can log in — the old password keeps working and the new one is rejected with Invalid user credentials.To change the password, use the CloudBeaver UI (see Changing the Admin Password), or uninstall — which deletes the volume set and every saved connection with it — and reinstall.

Access

publicAccess:
  # false = not reachable from the internet. Setting this true publishes a
  # database administration console, and its login form, to the whole internet.
  enabled: false

internalAccess:
  type: same-gvc # options: none, same-gvc, same-org, workload-list
  workloads: [] # used with workload-list
  # workloads:
  #   - //gvc/GVC_NAME/workload/WORKLOAD_NAME

publicAccess.enabled — when true, the workload’s external inbound firewall opens to 0.0.0.0/0 and Control Plane assigns a *.cpln.app canonical endpoint. With it off, requests to the canonical endpoint return 403 RBAC: access denied.
internalAccess.type — which workloads inside Control Plane may reach the console.
internalAccess.workloads — list of workload links, used only when type is workload-list.

Type	Description
`none`	No internal access allowed
`same-gvc`	Allow access from all workloads in the same GVC
`same-org`	Allow access from all workloads in the same organization
`workload-list`	Allow access only from the workloads listed in `internalAccess.workloads`

An access change takes up to a few minutes to take effect. Re-check before concluding the knob did nothing.

Outbound traffic is closed, and there is no value to open it. The workload ships with an empty outbound firewall, so CloudBeaver can only reach databases inside its own GVC. Managed databases such as Amazon RDS, Google Cloud SQL, and MongoDB Atlas cannot be connected. Point connections at in-GVC hosts over internal DNS, e.g. WORKLOAD_NAME.GVC_NAME.cpln.local:5432.

Resources and Storage

resources:
  cpu: 500m
  memory: 512Mi

volumeset:
  capacity: 10 # initial capacity in GiB (minimum is 10)

resources.cpu / resources.memory — CPU and memory allocated to the CloudBeaver container.
volumeset.capacity — persistent volume size in GiB for the workspace: server configuration, saved connections, and user accounts.

Connecting

What	Address	Notes
UI, private (default)	`cpln port-forward RELEASE_NAME-dbeaver 8978:8978 --gvc GVC_NAME`, then `http://localhost:8978`	Works while the console is closed to the internet. Fine for setup and administration; for everyday heavy use, publish the console or reach it from inside the GVC.
UI, public	`https://CANONICAL_ENDPOINT`	Only when `publicAccess.enabled` is `true`. Read it from `status.canonicalEndpoint` in `cpln workload get RELEASE_NAME-dbeaver --gvc GVC_NAME -o yaml`.
UI and API from other workloads	`http://RELEASE_NAME-dbeaver.GVC_NAME.cpln.local:8978`	Subject to `internalAccess.type`.
Admin credentials	`admin.name` from your values, plus the payload of the secret named in `admin.passwordSecretName`	Reveal the password with `cpln secret reveal SECRET_NAME -o yaml`.

Verify the server is answering through the tunnel:

cpln port-forward RELEASE_NAME-dbeaver 8978:8978 --gvc GVC_NAME

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8978/

A 200 means CloudBeaver is serving its UI.

First Run

The chart supplies all four of CloudBeaver’s automatic-setup parameters (CB_SERVER_NAME, CB_SERVER_URL, CB_ADMIN_NAME, CB_ADMIN_PASSWORD), so the server configures itself on first start and there is no setup wizard to complete. The recommended sequence keeps the console private until the admin account is confirmed working:

Install with public access off

Keep the shipped publicAccess.enabled: false. Wait for the workload to report ready:

cpln workload get-deployments RELEASE_NAME-dbeaver --gvc GVC_NAME -o yaml

Tunnel to the UI and sign in

cpln port-forward RELEASE_NAME-dbeaver 8978:8978 --gvc GVC_NAME

Open http://localhost:8978, choose Settings (the cog icon, top right) → Login, and sign in with admin.name and the password from your secret. The administration panel is under Settings → Administration, or directly at http://localhost:8978/#/admin.

Add a database connection

Click + in the top menu and choose New Connection. For a database running in the same GVC, use its fully qualified internal hostname as Host, e.g. WORKLOAD_NAME.GVC_NAME.cpln.local, with the engine’s port. As the admin you can save a connection to the Shared project and grant users or teams access to it on the connection’s Access tab; a Private connection is visible only to you.

Publish the console only if you need to

Run a Helm upgrade with public access on, then allow a few minutes for the firewall change to take effect before testing the canonical endpoint:

cpln helm upgrade RELEASE_NAME oci://ghcr.io/controlplane-com/templates/dbeaver \
  --version 1.3.0 --gvc GVC_NAME \
  --set admin.passwordSecretName=SECRET_NAME \
  --set publicAccess.enabled=true

Operations

Backing Up

There is no scheduled-backup feature. The volume set takes no scheduled snapshots; the only automatic snapshot is the final one taken when the volume set is deleted, kept for 7 days. Take a manual snapshot of the workspace before a risky change:

cpln volumeset snapshot create RELEASE_NAME-dbeaver-vs --gvc GVC_NAME --snapshot-name NAME

cpln volumeset snapshot get RELEASE_NAME-dbeaver-vs --gvc GVC_NAME

Restoring a workspace from a volume set snapshot has not been verified on this template. Before uninstalling, export anything you cannot lose from the CloudBeaver UI.

Changing the Admin Password

The password in your secret is applied only when the workspace is first initialized, so rotate it in CloudBeaver itself: sign in as an administrator, open Settings → Administration → Users and Teams → Users, select the user, and assign a new password on the Info tab. Update the secret too if you want it to reflect the current password, but doing so on its own changes nothing. If no administrator can sign in, CloudBeaver documents an admin password recovery procedure that edits .cloudbeaver.runtime.conf under the workspace’s .data directory and restarts the server. On this template the workspace is the volume set mounted at /opt/cloudbeaver/workspace; the procedure has not been verified here, and because the chart also supplies the automatic-setup variables, the server may re-configure itself from them rather than show the wizard the upstream page describes.

Upgrading From 1.2.1 or Earlier

Version 1.3.0 is a security fix that changes the behavior of an existing install. Versions up to 1.2.1 shipped a working admin password (Password123) as a values.yaml default and hardcoded the workload’s inbound firewall to 0.0.0.0/0 with no way to turn it off. In 1.3.0 the password moved to a prerequisite secret and public access became an opt-in knob that defaults to off. After upgrading, the console is no longer reachable from the internet, and your existing admin login is unchanged — both the name and the password stay whatever the workspace was first bootstrapped with. Treat the old default password as compromised and change it in the UI after the upgrade.

Behavior	1.2.1 and earlier	1.3.0
Admin password	`admin.password` value, defaulting to `Password123`	`admin.passwordSecretName`, naming an opaque secret you create
Admin login name	`admin.name`, defaulting to `adminusername`	`admin.name`, defaulting to `cbadmin` — applies to new installs only; an existing workspace keeps the name it was bootstrapped with
Public access	Hardcoded `0.0.0.0/0` inbound, no knob	`publicAccess.enabled`, defaulting to `false`
Internal access	Hardcoded `none`	`internalAccess.type`, defaulting to `same-gvc`
Chart-created secret	A secret holding the admin name and password	None — the chart creates no secret

Create the admin password secret

The workload will not start without it, even though it will not change the account you already log in with. Use the password your install currently uses so nothing is ambiguous later:

printf '%s' 'YOUR-EXISTING-PASSWORD' | cpln secret create-opaque --name SECRET_NAME --encoding plain -f -

Set admin.passwordSecretName to that name, and remove admin.password from your values — it no longer exists in the chart.

Decide whether you still want public access

If you were relying on the internet-facing URL, set publicAccess.enabled: true explicitly. If you were not, do nothing and the console becomes internal-only. Either way, allow a few minutes for the firewall change to take effect.

Keep signing in with your old login

The account already exists in the workspace database, so the upgrade does not re-bootstrap it. Sign in with the name and password the workspace was bootstrapped with — typically adminusername, not the new cbadmin default — then change the password in the UI (see Changing the Admin Password).

Scaling and Availability

This template is single-instance. CloudBeaver Community Edition has no clustering, and the workspace is one volume bound to one replica, so do not scale the workload out. Be aware that this chart version sets CPU autoscaling to a maximum of 3 replicas, which you cannot change in values: under sustained CPU load extra replicas can start, each with its own empty workspace volume, so a session may land on a replica that lacks your saved connections. The first helm upgrade after an install restarts the workload even when no value changed, making the UI briefly unavailable; later no-op upgrades do not.

Troubleshooting

The workload never starts after install

Symptom: cpln helm install succeeded, but the workload has no running replica and cpln logs returns nothing.Cause: The secret named in admin.passwordSecretName does not exist. The deployment is paused waiting for it.Fix: Confirm with cpln workload get-deployments RELEASE_NAME-dbeaver --gvc GVC_NAME -o yaml — status.versions[].message reads

The secret SECRET_NAME no longer exists. Workload updates are paused until the secret is added or the reference to the secret removed.

Create the secret as shown in Prerequisites; the deployment recovers on its own, or run cpln workload force-redeployment RELEASE_NAME-dbeaver --gvc GVC_NAME to skip the wait.

Invalid user credentials after changing the secret

Symptom: You rotated the admin password secret, the workload restarted, and the new password is rejected with Invalid user credentials while the old one still works.Cause: CloudBeaver reads CB_ADMIN_PASSWORD only when it initializes an empty workspace. The account stored on the volume set is authoritative afterwards.Fix: Change the password in the UI under Settings → Administration → Users and Teams → Users (see Changing the Admin Password).

Cannot connect to an external or managed database

Symptom: A connection to Amazon RDS, Google Cloud SQL, MongoDB Atlas, or any host outside Control Plane fails to connect from CloudBeaver, with no obvious explanation.Cause: The workload’s outbound firewall is closed and the chart exposes no value to open it.Fix: Connect to databases running in the same GVC using their fully qualified internal hostname, WORKLOAD_NAME.GVC_NAME.cpln.local, with the engine’s port.

Canonical endpoint returns 403 RBAC access denied

Symptom: Requests to the *.cpln.app endpoint return 403 RBAC: access denied.Cause: publicAccess.enabled is false (the default), so the external inbound firewall is closed.Fix: Reach the UI with cpln port-forward RELEASE_NAME-dbeaver 8978:8978 --gvc GVC_NAME, or run a Helm upgrade with --set publicAccess.enabled=true and allow a few minutes for the change to take effect.

An access change appears to do nothing

Symptom: You changed publicAccess.enabled or internalAccess.type and the console still behaves as before.Cause: Firewall changes take up to a few minutes to take effect.Fix: Wait a few minutes and test again before concluding the setting is wrong.

Important Notes

Create the admin-password secret before installing. A missing secret does not fail the install — the workload waits on it with no container logs to diagnose from.
The admin name and password are read only when the workspace is first initialized. Change the password in the CloudBeaver UI; rotating the secret alone changes nothing.
Anyone who can read this workload’s logs can authenticate as the admin. CloudBeaver logs the submitted password hash at its default log level, and its API accepts that hash in place of the password. This is upstream behavior the chart does not configure; treat log access to this workload as admin access to every database it is connected to.
publicAccess.enabled: true puts a database administration console on the public internet. Anyone who reaches it needs only the admin password to query every connected database. Set a strong password first, and prefer leaving it off.
Outbound traffic is closed and there is no knob for it — only databases inside the same GVC can be connected.
Saved connections and users live on the volume set and survive redeploys and upgrades. cpln helm uninstall deletes the volume set, taking every saved connection with it; the final snapshot is kept for 7 days.
The prerequisite secret is not owned by the release — it survives cpln helm uninstall and must be deleted separately if you no longer need it.
Upgrading from 1.2.1 or earlier closes public access and requires the secret — see Upgrading From 1.2.1 or Earlier before you upgrade.

External References

CloudBeaver Documentation

Official DBeaver CloudBeaver documentation

Server Configuration

Reference for CloudBeaver server settings and automatic setup

User Management

Creating users and assigning passwords in the administration panel

Admin Password Recovery

Upstream procedure for regaining admin access

DBeaver Template

View the source files, default values, and chart definition

Template Catalog

Templates

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Image

Access

Resources and Storage

Connecting

First Run

Operations

Backing Up

Changing the Admin Password

Upgrading From 1.2.1 or Earlier

Scaling and Availability

Troubleshooting

Important Notes

External References

CloudBeaver Documentation

Server Configuration

User Management

Admin Password Recovery

DBeaver Template

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Image

​Admin Login

​Access

​Resources and Storage

​Connecting

​First Run

​Operations

​Backing Up

​Changing the Admin Password

​Upgrading From 1.2.1 or Earlier

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

CloudBeaver Documentation

Server Configuration

User Management

Admin Password Recovery

DBeaver Template

Overview

What Gets Created

Prerequisites

Installation

Configuration

Image

Admin Login

Access

Resources and Storage

Connecting

First Run

Operations

Backing Up

Changing the Admin Password

Upgrading From 1.2.1 or Earlier

Scaling and Availability

Troubleshooting

Important Notes

External References