Explanation

CNPG Operator Architecture

Understanding how the CloudNativePG operator works.

Overview

CloudNativePG is a Kubernetes operator that manages the full lifecycle of PostgreSQL database clusters. It uses the operator pattern to watch for custom resources (Cluster, Backup, Pooler) and reconcile the desired state.

Components

Operator Controller

  • Deployment: Single pod in cnpg-system namespace

  • Purpose: Reconciles CNPG custom resources

  • Watches: Cluster, Backup, ScheduledBackup, Pooler CRDs

  • Manages: PostgreSQL pods, services, PVCs, secrets

Barman Cloud Plugin

  • Purpose: S3-compatible backup/restore tooling

  • Integration: Used by operator for backup operations

  • Tools: barman-cloud-backup, barman-cloud-wal-archive, barman-cloud-restore

Custom Resource Definitions (CRDs)

Cluster

Defines a PostgreSQL cluster with instances, storage, and configuration.

Backup

Triggers on-demand backups to S3.

ScheduledBackup

Defines automated backup schedules (cron-based).

Pooler

Deploys PgBouncer connection pooler for the cluster.

Deployment via ArgoCD

The operator itself is deployed using CDK8S + ArgoCD:

  1. Source: dp-infra/cnpg repository

  2. Build: TypeScript → Kubernetes manifests

  3. Deploy: ArgoCD syncs from git

  4. Update: Change config.yaml → rebuild → commit → ArgoCD sync