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/

For manifest examples, see [references/cluster-reference.md](references/cluster-reference.md).

Workflow: Add a Database for a New App (Shared Cluster)

Steps 1-3 edit files in kubernetes/platform/config/database/. Steps 4-5 are in the app's cluster config.

Step 1: Add managed role to cluster.yaml spec.managed.roles. Template: see [references/cluster-reference.md](references/cluster-reference.md#managed-role-fields).

Step 2: Create role password secret in role-secrets.yaml. Template: see [references/credentials.md](references/credentials.md#role-password-secret-template).

Step 3: Create Database CRD in databases.yaml. Template: see [references/cluster-reference.md](references/cluster-reference.md#database-crd-fields).

Note: Apps with multiple databases (sonarr-main, sonarr-log) share one role; create separate Database CRs with the same owner.

Step 4: Create credential replica in kubernetes/clusters/<cluster>/config/<app>/. Template: see [references/credentials.md](references/credentials.md#app-namespace-replica-template).

Step 5: Add network policy access label access.network-policy.homelab/postgres: "true" to the namespace entry in kubernetes/platform/namespaces.yaml.

Step 6: Register the credential replica in the app's kustomization.yaml.

For credential chain diagrams, see [references/credentials.md](references/credentials.md).

Workflow: Create a Dedicated CNPG Cluster

Use when the app needs custom PostgreSQL extensions or performance/data isolation.

Step 1: Define the Cluster at kubernetes/clusters/<cluster>/config/<app>/<app>-cluster.yaml. Set inheritedMetadata to allow replication of the auto-generated app secret. For a full manifest example, see [references/cluster-reference.md](references/cluster-reference.md).

Key differences vs shared cluster:

Step 2: Replicate app credentials to the consumer namespace. CNPG auto-generates <cluster-name>-app in database. The inheritedMetadata annotations enable replication. Template: see [references/credentials.md](references/credentials.md#app-namespace-replica-template).

Real example: kubernetes/clusters/live/config/immich/database-secret-replication.yaml

Step 3: Add the access.network-policy.homelab/postgres: "true" label to the app namespace and register all files in kustomization.yaml.

Monitoring

Both Cluster and Pooler set monitoring.enablePodMonitor: true — Prometheus discovers them automatically. No manual ServiceMonitor needed.

CNPG alerts are in kubernetes/platform/config/database/prometheus-rules.yaml:

Key metrics: cnpgpgreplicationstreaming, cnpgpgstatactivitycount, cnpgpgsettingssetting{name="maxconnections"}, cnpgpgreplicationiswalreceiver_up.

Debugging

Use scripts/check-connection.sh <cluster> <app-namespace> [app-name] for structured health checks.

Common issues:

Manual connectivity test: kubectl run -n <app-ns> pg-test --rm -it --image=postgres:17 -- psql "postgresql://user:[email protected]:5432/dbname"

Cross-References