cnpg-database

name	cnpg-database
description	CloudNative-PG (CNPG) PostgreSQL database management for the Kubernetes homelab. Covers shared platform cluster, dedicated per-app clusters, credential provisioning, cross-namespace replication via kubernetes-replicator, and monitoring. Use when: (1) Adding a new database for an application, (2) Creating a dedicated CNPG cluster, (3) Setting up database credentials and cross-namespace replication, (4) Debugging database connectivity or CNPG cluster health, (5) Adding PostgreSQL extensions for specialized workloads. Triggers: "database", "postgresql", "postgres", "cnpg", "cloudnative-pg", "pooler", "pgbouncer", "database credentials", "db password", "managed roles", "Database CRD", "database cluster", "shared database", "dedicated database", "cnpg cluster"
user-invocable	false

CNPG Database Management

Architecture Overview

All clusters live in the database namespace. The shared platform cluster (platform-0/1/2) uses spec.managed.roles + Database CRDs per app, with PgBouncer pooler at platform-pooler-rw.database.svc. Dedicated clusters (e.g., Immich) bootstrap their own DB and owner via initdb. In both cases, credentials are replicated via kubernetes-replicator to the consumer app namespace.

Decision Tree: Shared vs Dedicated Cluster

Standard workload, no special extensions → shared cluster (platform-pooler-rw.database.svc) Needs custom extensions (vector, PostGIS) or isolation → dedicated cluster with custom imageName Unclear → start with shared, migrate if needed

---

Key Files (Shared Cluster)

Location: kubernetes/platform/config/database/