PostgresCluster

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

PostgreSQL condiviso con database per consumer all'interno di un unico cluster. Il motore è intercambiabile tramite type; cnpg è implementato, zalando e cockroachdb sono predisposti (scaffolded).

Spec

Campo	Tipo	Descrizione
type	enum cnpg (predefinito) | zalando | cockroachdb	Implementazione del backend
mode	enum managed | adopt | external (obbligatorio)	Modalità di provenienza
managed	object	Impostazioni quando mode: managed
adopt	object	Riferimento a un Cluster CNPG esistente
external	object	Secret di connessione per un database esterno
databases[]	list	Database da garantire all'interno del cluster (uno per ogni workload consumer)

managed

Campo	Predefinito	Descrizione
instances	3	Numero di repliche HA di CNPG
storageSize	—	Dimensione del PVC per istanza
storageClass	default del cluster	StorageClass
resources	—	Request e limit di CPU/memoria
backup	disattivato	Backup pianificati su object storage (vedi backup)

backup

Disattivato per default. Quando è abilitato, l'operatore configura i backup su object store di CNPG (Barman in-tree) e l'archiviazione WAL continua — offrendo backup completi pianificati e ripristino point-in-time. Emette il blocco Cluster.spec.backup più uno ScheduledBackup. Le credenziali provengono da un Secret tramite SecretsManagement — mai inline.

Campo	Predefinito	Descrizione
enabled	false	Attiva i backup pianificati + l'archiviazione WAL
provider	s3	s3, azure o gcs
s3 / azure / gcs	—	Blocco del provider (quello corrispondente a provider è obbligatorio)
schedule	0 0 2 * * *	Cron a 6 campi con i secondi (formato CNPG, non a 5 campi) — per default ogni giorno alle 02:00
retentionPolicy	30d	Retention della finestra di ripristino, ad es. 30d, 4w

Blocchi del provider — ciascuno accetta un destinationPath più le credenziali (o un'alternativa basata su workload identity, così non viene memorizzata alcuna chiave statica):

Provider	destinationPath	Chiavi del Secret delle credenziali	Workload identity
s3	s3://bucket/path (+ endpointURL facoltativo per 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 (JSON del service account)	gkeEnvironment: true

Il destinationPath deve includere un segmento container/bucket — un https://<acct>.blob.core.windows.net/ nudo (Azure) o un s3:// senza bucket produce una destinazione di backup su cui non si può scrivere. I job di backup di ClickHouse e MongoDB rifiutano un percorso senza container con un evento di warning BackupMisconfigured sul datastore, invece di emettere un CronJob i cui pod falliscono.

adopt / external

Campo	Descrizione
adopt.clusterRef	Un Cluster CNPG esistente (postgresql.cnpg.io/v1); namespace è facoltativo e può indicare un altro namespace — vedi l'adozione tra namespace
external.connectionSecretRef	Secret che contiene un DATABASE_URL

databases[]

Campo	Descrizione
name	Nome del database
owner	Ruolo proprietario (facoltativo)
credentialsSecretName	Secret che l'operatore materializza per il consumer

I workload che fanno riferimento a questo cluster ottengono il proprio database anche quando non è dichiarato qui, con la licenza auto-wiring; status.databases[].claimedBy mostra chi usa ciascuno. Un nome di database che Kubernetes non può usare nei nomi degli oggetti (ad esempio langfuse_prod) riceve un nome sanificato per il suo Database CNPG e il Secret delle credenziali. Vedi Database per i workload che fanno riferimento a un datastore.

Comportamento per modalità

• managed (type: cnpg) — garantisce l'operatore cloudnative-pg, crea un Cluster CNPG e crea un Database CNPG (più ruolo e Secret delle credenziali) per ogni voce di databases[].
• adopt — risolve il Cluster referenziato, garantisce i database al suo interno e non tocca mai il ciclo di vita del cluster. Quando il cluster si trova in un altro namespace, le risorse Database CNPG vengono create accanto a esso (CNPG risolve Database.spec.cluster nel namespace del Database stesso), mentre il Secret delle credenziali del consumer viene comunque materializzato in questo namespace. Eliminare questa risorsa rimuove quelle CR Database — mai il cluster adottato.
• external — espone il DATABASE_URL fornito; nessun operatore viene installato.
• zalando / cockroachdb — predisposti; la risorsa riporta Ready=False con reason BackendNotImplemented.

Esempio — managed, due database

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 }

Esempio — external (porta il tuo Postgres gestito)

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

Esempio — managed con backup S3 pianificati

spec:
  type: cnpg
  mode: managed
  managed:
    instances: 3
    storageSize: 20Gi
    backup:
      enabled: true
      provider: s3
      schedule: "0 0 2 * * *"   # daily 02:00 (6-field cron: sec min hour dom mon dow)
      retentionPolicy: 30d
      s3:
        destinationPath: s3://forge-backups/pg
        # endpointURL: https://minio.example.com:9000   # for S3-compatible stores
        credentialsSecretRef: { name: pg-backup }        # keys: access-key-id, secret-access-key
  databases:
    - { name: litellm, credentialsSecretName: litellm-db-credentials }

Ripristino

Un Postgres managed viene salvato in modo continuo da CNPG (backup di base + archiviazione WAL), quindi il ripristino è un point-in-time recovery (PITR) verso un nuovo cluster che si inizializza dallo stesso object store — CNPG non ripristina mai sul posto. Crea un secondo Cluster con una sorgente bootstrap.recovery che punta al barmanObjectStore del backup; l'operatore navique non modella il ripristino come CRD, quindi applica direttamente il Cluster CNPG:

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" }   # omit = latest
  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 }

Quando forge-pg-restored è healthy, ricollega i workload (oppure passa il PostgresCluster a mode: adopt facendo riferimento a esso). Riferimento completo: CNPG recovery. Il Lock creato automaticamente protegge l'originale da un'eliminazione accidentale durante il ripristino — mantienilo finché non hai verificato i dati ripristinati.

Condivisione tra workload

Un singolo PostgresCluster supporta tipicamente sia il Gateway (DB litellm) sia Langfuse (DB langfuse). Ogni consumer fa riferimento al cluster e indica il nome del proprio database; l'operatore predispone un database isolato e un Secret delle credenziali per ciascun consumer.

Status

Espone le coordinate di connessione e, per ogni database, lo stato di prontezza e il nome del Secret delle credenziali, oltre alle conditions e all'observedGeneration standard.