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-sideflag, 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.
