PodMonitor Management in CloudNativePG#

CloudNativePG manages PodMonitor resources (from the Prometheus Operator API) for both Cluster and Pooler objects. The operator creates, reconciles, and deletes these resources automatically when spec.monitoring.enablePodMonitor is set — though that field is now deprecated (see Deprecation below).

The operator requires get;create;list;watch;delete;patch RBAC on monitoring.coreos.com/podmonitors 1.

Core Reconciliation: createOrPatchPodMonitor#

Both Cluster and Pooler share a single generic reconciliation function, createOrPatchPodMonitor, which accepts any type implementing the podMonitorManager interface 2:

type podMonitorManager interface {
    IsPodMonitorEnabled() bool
    BuildPodMonitor() *monitoringv1.PodMonitor
}

The function's four-case reconciliation logic 3:

CRD guard: If the PodMonitor CRD is not installed in the cluster, the function logs a warning and returns early instead of erroring 4. This allows clusters to operate without the Prometheus Operator installed.

Ownership check on delete: Before deleting an existing PodMonitor when monitoring is disabled, the function verifies ownership with IsOwnedByCluster 5. This prevents accidental deletion of manually-created PodMonitors that share the same name/namespace — a bug that was fixed in PR #9340.

Metadata merging on update: When patching, the spec is fully replaced but labels/annotations are merged (not overwritten), preserving any user-managed metadata 6.

Cluster PodMonitor#

Entry point: createPostgresClusterObjects calls createOrPatchPodMonitor with a ClusterPodMonitorManager on every reconcile pass 7.

Spec builder: pkg/specs/podmonitor.go defines ClusterPodMonitorManager.BuildPodMonitor(), which:

• Names the PodMonitor after the Cluster 8
• Sets ownership via cluster.SetInheritedDataAndOwnership 9
• Selects pods matching cnpg.io/cluster: <name> + role: instance 10
• Optionally configures HTTPS with the server CA secret when IsMetricsTLSEnabled() is true 11

IsPodMonitorEnabled() delegates to cluster.IsPodMonitorEnabled() 12.

Pooler PodMonitor#

Entry point: updateOwnedObjects (the Pooler reconciler's main owned-resource sync function) calls createOrPatchPodMonitor last, after reconciling service accounts, RBAC, deployment, and service 13. This runs even when the Pooler's image cannot be resolved (i.e., Phase=Failed), so monitoring drift is corrected independently of deployment state 14.

Spec builder: pkg/specs/pgbouncer/podmonitor.go defines PoolerPodMonitorManager.BuildPodMonitor(), which:

• Names the PodMonitor after the Pooler 15
• Sets ownership via utils.SetAsOwnedBy 16
• Selects pods matching cnpg.io/pgbouncer: <name> + role: pooler 17
• When IsMetricsTLSEnabled() is true, configures HTTPS with InsecureSkipVerify: true (because Prometheus scrapes pods by IP, so the cert's SANs won't match) — users needing strict verification must disable enablePodMonitor and manage their own PodMonitor 18

IsPodMonitorEnabled() checks pooler.Spec.Monitoring.EnablePodMonitor 19.

Deprecation of spec.monitoring.enablePodMonitor#

spec.monitoring.enablePodMonitor is deprecated for both Cluster and Pooler as of PR #8753 (merged October 2025). The same PR also deprecated the companion relabeling fields:

• spec.monitoring.podMonitorMetricRelabelings
• spec.monitoring.podMonitorRelabelings

Migration path: Users should remove enablePodMonitor: true and create a PodMonitor resource manually. The admission webhook now emits warnings for both Cluster and Pooler when these deprecated fields are set 20. The Helm chart's podmonitor-pooler.yaml follows this pattern — it creates the PodMonitor directly rather than delegating to the operator via enablePodMonitor 21.

The operator continues to honor the deprecated fields during the deprecation period, reading them with //nolint:staticcheck annotations 22 23.

Key Source Files#