CNPG - installation

#postgres #database #cnpg #gitops

Installing CloudNativePG (CNPG): Step-by-Step Guide

In previous posts, we explored the reasons for adopting CloudNativePG and the key considerations for migrating databases to it. Now it is time to get practical and walk through the installation process.
This guide assumes you are working in a GitOps-driven environment. All configuration lives in Git repositories, and deployments are handled through CI/CD pipelines ( i.e- GitLab + Jenkins for development, or GitLab + Argo CD for production). This approach ensures everything is version-controlled, repeatable, and auditable.

1. Install the CNPG Operator

CNPG is a Kubernetes operator. Once installed, it watches for custom resources (mainly Cluster objects) and manages the full lifecycle of your PostgreSQL databases.
The official way to install the operator is straightforward:

kubectl apply --server-side -f \
  https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.29/releases/cnpg-1.29.1.yaml

Recommended GitOps practice:
Instead of applying the manifest directly from the internet, download it into your control repository. This gives you a stable, pinned version that you can reapply anytime.

Add the YAML file to your Git repo.
For environments using Jenkins, create a pipeline stage that runs:

kubectl apply --server-side -f /path/to/cnpg-1.29.1.yaml

Argo CD may need special handling for the --server-side flag, so Jenkins often handles the initial operator install.

You can monitor the rollout with:

kubectl rollout status deployment \
  -n cnpg-system cnpg-controller-manager

Or simply watch the deployment in a Kubernetes dashboard such as Headlamp.

2. Create a ClusterImageCatalog

It is highly recommended to define the PostgreSQL images you want to use. This gives you control over major versions and prevents unexpected upgrades.

Create and apply the following manifest in your repository:

---
apiVersion: postgresql.cnpg.io/v1
kind: ClusterImageCatalog
metadata:
  name: postgresql-global
spec:
  images:
    - major: 15
      image: ghcr.io/cloudnative-pg/postgresql:15.14-system-trixie
    - major: 16
      image: ghcr.io/cloudnative-pg/postgresql:16.10-system-trixie
    - major: 17
      image: ghcr.io/cloudnative-pg/postgresql:17.6-system-trixie
    - major: 18
      image: ghcr.io/cloudnative-pg/postgresql:18.3-system-trixie

With the operator and image catalog in place, you are ready to define your actual database clusters.

3. Design Decisions Before Bootstrapping

Before writing your first Cluster manifest, take time to plan the following aspects (many were covered in the migration considerations post):

Namespace — Use a dedicated namespace for each CNPG setup (e.g., postgres-prod). This improves isolation, especially when running multiple clusters.
One cluster or many? — CNPG works best with one database per cluster for strong isolation. If your databases are small and have light workloads, you can host several in one cluster (as I did successfully).
Storage backend — Choose the right Kubernetes StorageClass based on performance needs (SSD, NVMe, local volumes, etc.). Plan for both data and WAL storage.
Superuser access — Not strictly required for single-database clusters, but very useful for backups, restores, and maintenance. Use separate roles and secrets for better isolation when hosting multiple databases.
Connection pooling — Enable PgBouncer (integrated with CNPG) to handle connection management efficiently. It automatically follows failovers.
WAL storage — Strongly consider a dedicated volume for the Write-Ahead Log. WAL can grow quickly and should not compete with data storage.
Backup strategy — Plan for Barman (integrated object storage backups, often with MinIO on slower storage) plus optional traditional pg_dump exports.
Data import method — Decide whether to use live logical replication from the source or bootstrap with existing backups.

4. Example Cluster Manifest

Here is a minimal starting point for a new cluster:

---
# Create a dedicated namespace
apiVersion: v1
kind: Namespace
metadata:
  name: postgres

---
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-example-initdb
  namespace: postgres
spec:
  instances: 3

  bootstrap:
    initdb:
      database: app
      owner: app
      secret:
        name: app-secret

  storage:
    size: 1Gi
    # storageClass: your-preferred-class

This basic manifest creates a 3-instance highly available cluster. You will expand it with:

Additional roles and databases
Custom pg_hba rules
Service exposure settings
WAL storage configuration
Barman object store for backups

Apply the manifest with kubectl apply -f your-cluster.yaml. The operator will spin up the cluster within a few minutes.

Next Steps and Tips

Test everything first in a development environment using iterative kubectl apply.
Once the configuration is solid, let Argo CD manage it in production.
Plan your data import strategy carefully. The official bootstrap documentation is helpful but can feel dense on first read — hands-on testing is the best teacher.

I will follow up with more detailed posts covering:

Advanced cluster configuration
Backup and disaster recovery setup
Data migration techniques
PgBouncer integration
Monitoring and observability

A sample chart gallery with ready-to-use manifests is also on the roadmap.

Ready to deploy?
Start small, document your decisions, and iterate. CloudNativePG makes PostgreSQL on Kubernetes reliable and pleasant to operate once the foundation is set correctly.
Have you installed CNPG yet? What challenges did you face during setup? Feel free to share in the comments.
Stay tuned for the next post in the CNPG series.

Did you find this post helpful? You can support me.