Grafana Dashboards

Two curated Grafana Dashboards for monitoring Alauda CloudNativePG (CNPG) clusters, built on the CNPG built-in metrics exporter:

static/grafana/cluster-overview.json — cluster health: instance status, primary identity, replication lag, connections, transactions per second, cache hit ratio, storage and WAL usage (24 panels).
static/grafana/backup-monitoring.json — continuous-backup health: time since last successful backup, backup failure indicator, point-in-time-recovery window, WAL archiving rate and backlog, WAL volume (15 panels).

Both dashboards were validated against a live 2-instance CNPG cluster on Alauda Container Platform (barman-cloud plugin backups to object storage, pgbench workload): every panel query verified to return data from the platform Prometheus.

The built-in exporter vs `postgres-exporter`

If you are coming from the Zalando-based PostgreSQL stack, monitoring used a separate postgres-exporter sidecar. CNPG embeds an exporter in every instance pod (port 9187) — nothing extra to deploy:

	CNPG built-in exporter	`postgres-exporter` (Zalando stack)
Deployment	inside every instance pod, port `9187`	extra sidecar/Deployment per cluster
Connection	pod-local socket, dedicated `cnpg_metrics_exporter` role, no password secret	TCP DSN via env vars (secret to manage)
Metric prefix	`cnpg_`	`pg_`
Operator awareness	fencing, sync-replica counts, nodes used, WAL archive status, backup timestamps	database-level only
Custom queries	per-cluster `spec.monitoring.customQueriesConfigMap`	exporter-global `queries.yaml`

Do not attach postgres-exporter to a CNPG cluster — you would duplicate scrapes and still lack the operator-level health metrics. If you depended on pg_stat_user_tables / pg_stat_statements panels, port those queries into a customQueriesConfigMap (the query YAML dialect is essentially the same); rename dashboard series from pg_* to cnpg_pg_*.

What the exporter exposes

Native metrics (cnpg_collector_*): instance up, PostgreSQL version, fencing, manual-switchover-required, nodes used, sync replica counts, WAL segment counts/sizes, WAL archive status (ready/done), and (PG ≥ 14) WAL write/sync statistics.
Default queries (cnpg_<query>_*, from the operator-managed cnpg-default-monitoring ConfigMap): backends, pg_database, pg_replication, pg_replication_slots, pg_stat_archiver, pg_stat_bgwriter/pg_stat_checkpointer, pg_stat_database, pg_stat_replication, pg_settings, pg_extensions.
Plugin metrics: CNPG-i plugins publish through the same endpoint. The barman-cloud plugin (the backup method shipped with this product) exposes barman_cloud_cloudnative_pg_io_last_available_backup_timestamp, ..._last_failed_backup_timestamp and ..._first_recoverability_point.

WARNING

With plugin-managed backups, the legacy cnpg_collector_last_available_backup_timestamp / ..._first_recoverability_point metrics stay 0 — they read in-tree status fields the plugin does not set. The backup dashboard queries the plugin series first and falls back to the in-tree ones, so it works with plugin, volume-snapshot, and legacy in-tree barman backups alike.

Install

1. Create a PodMonitor with the platform-required label

The exporter is always on; what you must add is a PodMonitor so the platform Prometheus scrapes it. On Alauda Container Platform the platform Prometheus (kube-prometheus-0 in cpaas-system) selects monitors in all namespaces, but only those carrying the label prometheus: kube-prometheus:

apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: <cluster-name>
  namespace: <cluster-namespace>
  labels:
    prometheus: kube-prometheus        # REQUIRED on ACP
spec:
  selector:
    matchLabels:
      cnpg.io/cluster: <cluster-name>
  podMetricsEndpoints:
    - port: metrics

TIP

spec.monitoring.enablePodMonitor: true on the Cluster also works but is deprecated in CNPG 1.29 and generates a PodMonitor without the required label — if you use it, propagate the label through spec.inheritedMetadata.labels.

Verify the scrape:

kubectl -n cpaas-system port-forward svc/kube-prometheus-0-web 9090 &
curl -s 'http://127.0.0.1:9090/api/v1/query?query=cnpg_collector_up' | jq .data.result

2. Point Grafana at the platform Prometheus

Grafana ≥ 9.x with a Prometheus datasource.

WARNING

The ACP Prometheus services (kube-prometheus-0-web.cpaas-system.svc:9090 and the Thanos query service) sit behind an OAuth (dex) proxy — a plain-URL datasource receives redirects, not data. Either configure the datasource with an Authorization: Bearer <platform id_token> custom HTTP header, or for a Grafana running inside the cluster, target the Prometheus container port directly (port 9090 on the prometheus-kube-prometheus-0-0 pod is not proxied; the OAuth sidecar only fronts the service target port).

3. Import the dashboards

UI: Dashboards → New → Import → Upload JSON file — download cluster-overview.json and backup-monitoring.json, pick your Prometheus datasource when prompted. Both dashboards expose namespace and cluster template variables (discovered from cnpg_collector_up), so one import covers every CNPG cluster on the platform.

Panel-to-metric map

Need	Panel (dashboard)	Backing series
Instance up/down	Instances up (overview)	`cnpg_collector_up`
Which pod is primary	Primary instance (overview)	`cnpg_pg_replication_in_recovery == 0`
Replication lag	Replication lag (overview)	`cnpg_pg_replication_lag`, `cnpg_pg_stat_replication_*_lag_seconds`
Connections	Backends by state, Connection usage (overview)	`cnpg_backends_total`, `cnpg_pg_settings_setting`
TPS	Transactions per second (overview)	`rate(cnpg_pg_stat_database_xact_commit[5m])`
Cache hit	Cache hit ratio (overview)	`cnpg_pg_stat_database_blks_hit` vs `blks_read`
Last backup / failure	Time since last successful backup (backup)	`barman_cloud_cloudnative_pg_io_last_available_backup_timestamp` (plugin) with `cnpg_collector_*` fallback
PITR window	Recovery window (backup)	`barman_cloud_cloudnative_pg_io_first_recoverability_point` (plugin) with fallback
WAL archive health	WAL segments awaiting archive, WAL archive rate (backup)	`cnpg_collector_pg_wal_archive_status`, `cnpg_pg_stat_archiver_*`

Backup size is intentionally absent: CNPG does not export it as a metric. Read it from the Backup resource status (kubectl get backup <name> -o jsonpath='{.status}') or from the object store; the Database size / WAL on disk panels serve as capacity proxies.

Known limitations

pg_stat_replication-based panels only produce data on a primary with at least one streaming replica — on a 1-instance cluster they are legitimately empty.
Backup-freshness panels cover the barman-cloud plugin and in-tree methods; other backup plugins would need their series added.
Grafana itself is not shipped by the CNPG plugin; bring your own (validated with Grafana 9.5).

#Grafana Dashboards

#TOC

#The built-in exporter vs postgres-exporter

#What the exporter exposes

#Install

#1. Create a PodMonitor with the platform-required label

#2. Point Grafana at the platform Prometheus

#3. Import the dashboards

#Panel-to-metric map

#Known limitations