Skip to content

CloudNativePG (PostgreSQL Operator)#

CloudNativePG is a Kubernetes operator that covers the full lifecycle of a highly available PostgreSQL database cluster with a primary/standby architecture, using native Kubernetes resources and patterns.

Overview#

  • Component Type: Database Operator & Clusters
  • Namespace: cnpg-system (Operator), media (Immich Cluster), ai (n8n Cluster)
  • Source: CloudNativePG Charts
  • Version: 0.24.0 (Pinned in Production)

Architecture#

The deployment consists of the CNPG Operator which manages the lifecycle of Cluster custom resources.

Operator#

  • Deployment: Deployed via HelmRelease.
  • Scope: Cluster-wide management of PostgreSQL resources.

Database Clusters#

The environment currently defines PostgreSQL clusters using the Cluster CRD. Notably, these clusters use a specialized image supporting VectorChord for vector similarity search capabilities.

1. Immich Database (immich-postgres)#

  • Namespace: media
  • Image: ghcr.io/tensorchord/cloudnative-vectorchord:17.5-0.3.0
  • Replicas: 1 instance (Primary only).
  • Extensions: vchord (VectorChord) loaded via shared_preload_libraries and postInitSQL.

2. n8n Vector Store (n8n-vector-store)#

Inactive Resource

This resource exists in the repository but does not appear to be active in the production kustomization.yaml.

  • Namespace: ai
  • Image: ghcr.io/tensorchord/cloudnative-vectorchord:17.5-0.3.0
  • Purpose: Vector store for AI workflows.

Connectivity#

Database clusters are exposed internally and, in some specific configurations, via LoadBalancers for direct access.

Immich Cluster#

  • Service: immich-db-lb
  • Type: LoadBalancer
  • Role: rw (Read-Write) access.
  • Credentials: Managed via immich-postgres-user secret.

Configuration#

Storage#

Both clusters utilize Longhorn for persistent storage.

  • StorageClass: longhorn-1-replica
  • Size: 10Gi (Data), 10Gi (WAL)

Bootstrapping#

Clusters are bootstrapped with specific owners and databases.

  • Immich: Owner/DB immich.
  • n8n: Owner/DB n8n.
  • Post-Init: Automatically runs CREATE EXTENSION IF NOT EXISTS vchord CASCADE; to enable vector search.

GitOps Strategy#

The configuration is split between the operator installation and the specific cluster definitions.

  • Base: apps/base/cnpg defines the HelmRepository and the base HelmRelease for the operator.
  • Production: apps/production/cnpg contains:
    • cnpg-operator.yaml: Patches the operator version.
    • immich-db.yaml: Defines the Immich database cluster.
    • n8n-vector-store.yaml: Defines the n8n database cluster.

File Locations#

  • Operator Base: apps/base/cnpg/cnpg-operator.yaml
  • Production Overlay: apps/production/cnpg/cnpg-operator.yaml
  • Cluster Definitions: apps/production/cnpg/*.yaml

Recommendations#

n8n Cluster Activation

The n8n-vector-store.yaml file exists in apps/production/cnpg but is missing from apps/production/kustomization.yaml. If this database is intended to be deployed, it must be added to the resources list.

High Availability

Current clusters are configured with instances: 1. For production workloads requiring high availability, consider increasing instances to 3 to enable leader election and failover.

Backups Missing

No backup scheduledBackup configuration was observed in the cluster manifests. It is recommended to configure WAL archiving and scheduled backups to S3/MinIO for disaster recovery.