Database monitoring on Kubernetes

On Kubernetes, the cluster collector monitors the databases in your cluster. The flow is the same as on a virtual machine, with three differences: the agent must be in managed mode, passwords come from a Kubernetes Secret, and log file coverages aren’t available. For the general model, see the Database monitoring overview.

One collector per cluster

Database monitoring runs in the cluster’s Deployment collector, which runs once per cluster. Each database is monitored once, not once per node.

Discovery fills in the endpoint

The agent discovers databases exposed through Kubernetes Services and lists them under Discovered in this cluster. Clicking Monitor fills in the engine, the instance name, and the endpoint <service>.<namespace>.svc.cluster.local:<port>. Keep that address. It’s the name your applications connect to, so the database’s metrics and traces line up.

Each discovered database stays listed until a database with the same endpoint is monitored. Databases outside the cluster aren’t discovered, so add them with Add database.

Managed mode is required

In Settings → Agents, open the cluster’s agent and go to its Databases tab. If the agent is in manual mode, click Switch to managed. In managed mode, KloudMate generates the agent’s configuration from its integrations and replaces any manual configuration. See the configuration model.

Available coverages

Every coverage is available on Kubernetes except those that read log files on the database host: Server logs (JSON, PostgreSQL 15+), Logs (stderr, PostgreSQL <15), and the MySQL Slow query log. API-based coverages such as MongoDB Atlas logs still work. See Engines and coverages.

Provide credentials with a Kubernetes Secret

The wizard defaults to reading the password from an environment variable, and shows the variable’s name, such as KM_SECRET_POSTGRESQL_PASSWORD. On Kubernetes, that variable comes from a Secret you create. Set it up before you configure a database, because the collector reads the Secret when its pod starts.

Find the variable name. Open the wizard, choose the engine, and set the Instance name you’ll use. The Password field shows the variable to create. The name is built from the instance name, or the engine when there isn’t one, plus the field, for example KM_SECRET_ORDERS_DB_PASSWORD for an instance named Orders DB.

Create a Secret with that key:

kubectl create secret generic km-db-creds \
  --namespace km-agent \
  --from-literal=KM_SECRET_POSTGRESQL_PASSWORD='YOUR_PASSWORD'

Add one key per database password. You can keep them all in one Secret.

Point the Helm release at the Secret and upgrade. The cluster collector loads it with envFrom.

helm upgrade kloudmate-release kloudmate/km-kube-agent \
  --namespace km-agent --reuse-values \
  --set dbMonitoring.secretName=km-db-creds

Save the database in the wizard. The password stays in the cluster and never reaches KloudMate.

Worked example: PostgreSQL

Create the monitoring user in PostgreSQL:

CREATE USER kmmonitor WITH PASSWORD 'YOUR_PASSWORD';
GRANT pg_monitor TO kmmonitor;

Enable pg_stat_statements if you’ll use query performance. Add it to shared_preload_libraries, restart PostgreSQL, then in each monitored database run:
```
CREATE EXTENSION pg_stat_statements;
```
Store the password under KM_SECRET_POSTGRESQL_PASSWORD in a Secret and set dbMonitoring.secretName, as above.
Monitor the discovered database. Click Monitor next to it under Discovered in this cluster, turn on Query performance, Locks & blocking, and any other coverages you want, enter kmmonitor as the user, and click Save and apply.

The cluster collector starts collecting within a minute. Its metrics carry the same database identity as the application spans that call it.

Next steps

Credentials How credential modes and variable names work.

Kubernetes platform notes Fleet manager, collector pods, and ConfigMaps.

Telemetry identity Build dashboards that join metrics and traces.