PostgresCluster

Geltungsbereich: namespaced · Backend: CloudNativePG (type: cnpg)

Gemeinsam genutztes PostgreSQL mit Datenbanken je Konsument innerhalb eines Clusters. Die Engine ist über type austauschbar; cnpg ist implementiert, zalando und cockroachdb sind als Gerüst vorbereitet.

Spec

Feld	Typ	Beschreibung
type	enum cnpg (Standard) | zalando | cockroachdb	Backend-Implementierung
mode	enum managed | adopt | external (erforderlich)	Provenance-Modus
managed	object	Einstellungen bei mode: managed
adopt	object	Referenz auf einen bestehenden CNPG-Cluster
external	object	Verbindungs-Secret für eine externe Datenbank
databases[]	list	Innerhalb des Clusters sicherzustellende Datenbanken (eine je konsumierendem Workload)

managed

Feld	Standard	Beschreibung
instances	3	CNPG-HA-Replikatanzahl
storageSize	—	PVC-Größe je Instanz
storageClass	Cluster-Standard	StorageClass
resources	—	CPU-/Speicher-Requests & -Limits
backup	deaktiviert	Geplante Backups in einen Objektspeicher (siehe backup)

backup

Standardmäßig deaktiviert. Wenn aktiviert, konfiguriert der Operator die Objektspeicher-Backups von CNPG (integriertes Barman) sowie die kontinuierliche WAL-Archivierung — das liefert Ihnen geplante Voll-Backups und Point-in-Time-Recovery. Er erzeugt den Block Cluster.spec.backup zuzüglich eines ScheduledBackup. Die Anmeldedaten stammen aus einem Secret über SecretsManagement — niemals inline.

Feld	Standard	Beschreibung
enabled	false	Geplante Backups + WAL-Archivierung einschalten
provider	s3	s3, azure oder gcs
s3 / azure / gcs	—	Provider-Block (der zu provider passende ist erforderlich)
schedule	0 0 2 * * *	6-Feld-Cron mit Sekunden (CNPG-Format, nicht 5-Feld) — Standard: täglich 02:00
retentionPolicy	30d	Aufbewahrung als Recovery-Fenster, z. B. 30d, 4w

Provider-Blöcke — jeder erwartet einen destinationPath zuzüglich Anmeldedaten (oder einen Workload-Identity-Ausweg, sodass keine statischen Schlüssel gespeichert werden):

Provider	destinationPath	Secret-Schlüssel der Anmeldedaten	Workload Identity
s3	s3://bucket/path (+ optional endpointURL für MinIO/R2)	access-key-id, secret-access-key	inheritFromIAMRole: true
azure	https://<acct>.blob.core.windows.net/<container>/	connection-string	inheritFromAzureAD: true
gcs	gs://bucket/path	credentials (Service-Account-JSON)	gkeEnvironment: true

Der destinationPath muss ein Container-/Bucket-Segment enthalten — ein bloßes https://<acct>.blob.core.windows.net/ (Azure) oder s3:// ohne Bucket ergibt ein nicht beschreibbares Backup-Ziel. Die ClickHouse- und MongoDB-Backup-Jobs weisen einen Pfad ohne Container mit einem BackupMisconfigured-Warnereignis am Datastore zurück, statt einen CronJob zu erzeugen, dessen Pods fehlschlagen.

adopt / external

Feld	Beschreibung
adopt.clusterRef	Ein bestehender CNPG-Cluster (postgresql.cnpg.io/v1); namespace ist optional und darf auf einen anderen Namespace zeigen — siehe namespace-übergreifende Adoption
external.connectionSecretRef	Secret, das eine DATABASE_URL enthält

databases[]

Feld	Beschreibung
name	Datenbankname
owner	Besitzer-Rolle (optional)
credentialsSecretName	Secret, das der Operator für den Konsumenten materialisiert

Workloads, die diesen Cluster referenzieren, erhalten mit der auto-wiring-Lizenz ihre Datenbank auch dann, wenn sie hier nicht deklariert ist; status.databases[].claimedBy zeigt, wer welche nutzt. Ein Datenbankname, den Kubernetes nicht in Objektnamen verwenden kann (zum Beispiel langfuse_prod), erhält für seine CNPG-Database und sein Anmeldedaten-Secret einen bereinigten Namen. Siehe Datenbanken für Workloads, die einen Datenspeicher referenzieren.

Verhalten je Modus

• managed (type: cnpg) — stellt den cloudnative-pg-Operator sicher, erstellt einen CNPG-Cluster und erstellt je databases[]-Eintrag eine CNPG-Database (zuzüglich Rolle und Anmeldedaten-Secret).
• adopt — löst den referenzierten Cluster auf, stellt die Datenbanken darin sicher und berührt niemals den Lebenszyklus des Clusters. Liegt der Cluster in einem anderen Namespace (namespace-übergreifende Adoption), werden die CNPG-Database-Ressourcen neben ihm angelegt (CNPG löst Database.spec.cluster im eigenen Namespace der Database auf), während das Anmeldedaten-Secret für Konsumenten weiterhin in diesem Namespace materialisiert wird. Das Löschen dieser Ressource entfernt jene Database-CRs — niemals den adoptierten Cluster.
• external — stellt die bereitgestellte DATABASE_URL zur Verfügung; es wird kein Operator installiert.
• zalando / cockroachdb — als Gerüst vorbereitet; die Ressource meldet Ready=False mit dem Grund BackendNotImplemented.

Beispiel — managed, zwei Datenbanken

apiVersion: core.navique.com/v1alpha1
kind: PostgresCluster
metadata:
  name: forge-pg
  namespace: forge-data
spec:
  type: cnpg
  mode: managed
  managed:
    instances: 3
    storageSize: 20Gi
  databases:
    - { name: litellm,  credentialsSecretName: litellm-db-credentials }
    - { name: langfuse, credentialsSecretName: langfuse-db-credentials }

Beispiel — external (eigenes verwaltetes Postgres mitbringen)

spec:
  type: cnpg
  mode: external
  external:
    connectionSecretRef: { name: azure-postgres, key: DATABASE_URL }
  databases:
    - { name: litellm, credentialsSecretName: litellm-db-credentials }

Beispiel — managed mit geplanten S3-Backups

spec:
  type: cnpg
  mode: managed
  managed:
    instances: 3
    storageSize: 20Gi
    backup:
      enabled: true
      provider: s3
      schedule: "0 0 2 * * *"   # täglich 02:00 (6-Feld-Cron: Sek Min Std Tag Mon Wochentag)
      retentionPolicy: 30d
      s3:
        destinationPath: s3://forge-backups/pg
        # endpointURL: https://minio.example.com:9000   # für S3-kompatible Speicher
        credentialsSecretRef: { name: pg-backup }        # Schlüssel: access-key-id, secret-access-key
  databases:
    - { name: litellm, credentialsSecretName: litellm-db-credentials }

Wiederherstellung

Ein verwaltetes Postgres wird von CNPG kontinuierlich gesichert (Base-Backups + WAL-Archivierung); die Wiederherstellung ist daher eine Point-in-Time-Recovery (PITR) in einen neuen Cluster, der aus demselben Objektspeicher bootstrappt — CNPG stellt nie an Ort und Stelle wieder her. Legen Sie einen zweiten Cluster mit einer bootstrap.recovery-Quelle an, die auf den barmanObjectStore des Backups zeigt; der navique-Operator modelliert die Wiederherstellung nicht als CRD, wenden Sie also den CNPG-Cluster direkt an:

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata: { name: forge-pg-restored, namespace: forge }
spec:
  instances: 1
  bootstrap:
    recovery:
      source: forge-pg
      # recoveryTarget: { targetTime: "2026-06-27 14:00:00+00" }   # weglassen = neueste
  externalClusters:
    - name: forge-pg
      barmanObjectStore:
        destinationPath: s3://my-bucket/postgres
        s3Credentials:
          accessKeyId:     { name: pg-backup, key: access-key-id }
          secretAccessKey: { name: pg-backup, key: secret-access-key }

Sobald forge-pg-restored healthy ist, leiten Sie die Workloads dorthin um (oder setzen Sie den PostgresCluster auf mode: adopt mit Verweis darauf). Volle Referenz: CNPG-Recovery. Das automatisch erstellte Lock schützt das Original vor versehentlichem Löschen während der Wiederherstellung — behalten Sie es, bis die wiederhergestellten Daten bestätigt sind.

Gemeinsame Nutzung über Workloads hinweg

Ein einzelnes PostgresCluster versorgt typischerweise sowohl das Gateway (litellm-DB) als auch Langfuse (langfuse-DB). Jeder Konsument referenziert den Cluster und benennt seine Datenbank; der Operator stellt je Konsument eine isolierte Datenbank und ein Anmeldedaten-Secret bereit.

Status

Stellt Verbindungskoordinaten bereit sowie je Datenbank den Bereitschaftszustand und den Namen des Anmeldedaten-Secrets, zuzüglich der standardmäßigen conditions und des observedGeneration.