DEV Community: 12ww1160

CNPG - Configuration - TLS Encryption

12ww1160 — Mon, 06 Jul 2026 11:52:04 +0000

Using TLS Encryption with CloudNativePG (CNPG)

Encryption has become essential in modern infrastructure. When working with databases, two main types of encryption come into play:

At-rest encryption — where the database files stored on disk are encrypted.
In-transit encryption (transport encryption) — where the connection between the database server and clients is encrypted, protecting data from eavesdropping, spoofing, and man-in-the-middle attacks.

This post focuses exclusively on transport encryption in CloudNativePG.

Encryption Modes in CloudNativePG

The CloudNativePG operator supports two primary modes for managing TLS certificates:

Operator-managed mode — Certificates are fully handled and automatically renewed by the operator. They are signed by a dedicated Certificate Authority (CA) created by CloudNativePG.
User-provided mode — You supply your own certificates (generated externally) and import them as Kubernetes Secrets. This mode also integrates smoothly with tools like cert-manager.

Setting Up TLS Encryption

Operator-Managed Mode (Default)

If you use the default operator-managed mode, no extra configuration is required. CloudNativePG automatically enables TLS encryption on the server side.

Here’s what happens behind the scenes:

The operator creates a Kubernetes Secret named -ca containing the Certificate Authority certificate.
It also creates a TLS Secret named -server with the server certificate and private key.
These secrets are automatically mounted into the PostgreSQL pods.

To verify that TLS is active, connect to your database using psql (or any other client) and run:

\conninfo

You should see output similar to this:

my_db=> \conninfo
            Connection Information
      Parameter       |         Value          
----------------------+------------------------
 Database             | my_db
 Client User          | my_db
 Host                 | 127.0.0.1
 Server Port          | 5432
 Options              | 
 Protocol Version     | 3.0
 Password Used        | true
 GSSAPI Authenticated | false
 Backend PID          | 1016607281
 SSL Connection       | true
 SSL Library          | OpenSSL
 SSL Protocol         | TLSv1.3
 SSL Key Bits         | 256
 SSL Cipher           | TLS_AES_256_GCM_SHA384
 SSL Compression      | false
 ALPN                 | postgresql
 Superuser            | off
 Hot Standby          | off

This confirms the connection is encrypted with a strong TLSv1.3 cipher.
For additional security, you can download the CA certificate from Kubernetes and configure your client to verify the server certificate using sslmode=verify-ca or sslmode=verify-full.

Replica connections are encrypted in exactly the same way. Certificate renewals happen seamlessly without any downtime.
For most non-production and many production environments, this built-in approach is more than sufficient.

User-Provided Certificates Mode

When you need full control — for example, to use a company-wide internal CA — you can provide your own certificates.
The official documentation explains the process in detail: User-provided certificates mode.
In summary, you create the necessary Secrets and reference them in your Cluster resource. CloudNativePG integrates cleanly with cert-manager if you prefer automated certificate lifecycle management.

How TLS Flows in Kubernetes with CloudNativePG

Here’s a visual overview of the TLS certificate flow in operator-managed mode:

This diagram shows how the operator provisions the certificates as Kubernetes Secrets, mounts them into the database pods, and enables secure client connections.

Final Thoughts

Securing your CloudNativePG cluster with TLS is straightforward — often just a matter of using the defaults. Whether you stick with the operator-managed certificates or bring your own, CloudNativePG makes transport encryption simple, reliable, and production-ready.
Have you tried TLS with CloudNativePG yet? Feel free to share your experience in the comments!

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

CNPG - Installation - Monitoring

12ww1160 — Thu, 02 Jul 2026 11:23:40 +0000

Monitoring CloudNativePG Clusters with the PLG Stack

Monitoring your CloudNativePG (CNPG) clusters is essential. Without proper visibility, small issues can quickly escalate into major outages or performance bottlenecks that affect your entire application.
Fortunately, CNPG makes monitoring straightforward. While many monitoring solutions exist, this post focuses on the popular PLG stack—Prometheus, Loki, and Grafana—which integrates seamlessly with Kubernetes.

What Is the PLG Stack?

Prometheus: An open-source time-series database and monitoring system. It collects and stores metrics from your applications and infrastructure. Unlike traditional threshold-based tools, Prometheus gathers data points over time, enabling powerful querying and alerting.
Loki: A lightweight, horizontally scalable log aggregation system inspired by Prometheus. It indexes metadata labels rather than the full content of logs, making it cost-effective and easy to operate.
Grafana: A powerful open-source visualization platform. It connects to various data sources (including Prometheus and Loki) to create rich dashboards, charts, and alerts. Grafana itself does not store monitoring data—it simply displays it.

Together, these tools provide a complete observability solution: metrics, logs, and beautiful visualizations.

The Tech Stack in This Environment

In this setup, a dedicated Prometheus instance runs inside Kubernetes alongside Thanos for long-term storage and MinIO as a cost-effective object store. This approach also collects metrics from the underlying Linux nodes, not just Kubernetes resources.
Grafana runs as a single instance integrated with Keycloak for authentication. Loki operates quietly in the background, feeding logs into Grafana.

How CNPG Monitoring Works

The great news is that no changes are required inside CNPG itself. Every CNPG pod automatically exposes metrics on port 9187. If you are using poolers, they expose metrics on port 9127.
Prometheus discovers and scrapes these metrics using Kubernetes service discovery.
Here is the recommended scrape configuration for Prometheus:

- job_name: 'cnpg-pods'
  kubernetes_sd_configs:
    - role: pod

  relabel_configs:
    # Keep only CNPG PostgreSQL pods
    - source_labels: [__meta_kubernetes_pod_label_cnpg_io_cluster]
      action: keep
      regex: .+

    # Keep only the metrics port
    - source_labels: [__meta_kubernetes_pod_container_port_name]
      action: keep
      regex: ^metrics$

    # Add useful labels
    - source_labels: [__meta_kubernetes_namespace]
      target_label: namespace
    - source_labels: [__meta_kubernetes_pod_label_cnpg_io_cluster]
      target_label: cluster
    - source_labels: [__meta_kubernetes_pod_name]
      target_label: pod

    # Clean up instance label
    - source_labels: [__address__]
      target_label: instance
      regex: '(.+):\d+'
      replacement: '$1'
      - job_name: 'cnpg-pods'
  kubernetes_sd_configs:
    - role: pod

  relabel_configs:
    # Keep only CNPG PostgreSQL pods
    - source_labels: [__meta_kubernetes_pod_label_cnpg_io_cluster]
      action: keep
      regex: .+

    # Keep only the metrics port
    - source_labels: [__meta_kubernetes_pod_container_port_name]
      action: keep
      regex: ^metrics$

    # Add useful labels
    - source_labels: [__meta_kubernetes_namespace]
      target_label: namespace
    - source_labels: [__meta_kubernetes_pod_label_cnpg_io_cluster]
      target_label: cluster
    - source_labels: [__meta_kubernetes_pod_name]
      target_label: pod

    # Clean up instance label
    - source_labels: [__address__]
      target_label: instance
      regex: '(.+):\d+'
      replacement: '$1'

Required Permissions (RBAC)

For Prometheus to discover CNPG pods, it needs the right permissions. Create the following resources:

---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: prometheus-svc-acc
  namespace: prometheus

---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: prometheus-cnpg-discovery
rules:
  - apiGroups: [""]
    resources:
      - nodes
      - nodes/metrics
      - services
      - endpoints
      - pods
    verbs: ["get", "list", "watch"]

  - apiGroups: ["extensions", "networking.k8s.io"]
    resources:
      - ingresses
    verbs: ["get", "list", "watch"]

  - nonResourceURLs: ["/metrics"]
    verbs: ["get"]

---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: prometheus-cnpg-discovery
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: prometheus-cnpg-discovery
subjects:
  - kind: ServiceAccount
    name: prometheus-svc-acc
    namespace: prometheus

Once these are applied, Prometheus should show your CNPG pods as healthy targets.

Visualizing Data in Grafana

Connect Grafana to your Prometheus instance as a data source. You can then import the official CloudNativePG dashboard using ID 20417.

How the PLG Stack Works Together

Flow Summary:

CNPG pods expose metrics and logs.
Prometheus scrapes metrics.
Loki collects and stores logs.
Grafana queries both systems and presents everything in user-friendly dashboards.

This setup gives you comprehensive visibility into your database clusters with minimal ongoing maintenance.

In the next post, we will explore backups and archiving strategies for CloudNativePG. Stay tuned!

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

CNPG - Installation - Connection pooling

12ww1160 — Wed, 01 Jul 2026 11:58:51 +0000

Connection Pooling in CloudNativePG: Managing Postgres Connections Efficiently

Connection management is a critical aspect of running PostgreSQL databases. Whether you are operating a single instance or a high-availability failover cluster, applications can quickly run into connection limits. When too many connections are open, new ones get rejected, leading to application errors and downtime.

Effective connection management should happen on both the client and server sides. You can limit the number of connections your applications open, while the database server enforces its own maximums. This is important for two main reasons:

An idle connection still consumes RAM and system resources.
Each additional connection increases overall memory usage, which can strain your infrastructure as the number of connections grows.

This is where PgBouncer shines. PgBouncer acts as a lightweight connection pooler that sits between your applications and PostgreSQL. It reuses and recycles connections according to your configuration, ensuring you never exceed defined limits while dramatically improving efficiency.

PgBouncer Pooling Modes

PgBouncer supports three main pool modes, each suited to different application behaviors:

Session Mode: A connection is assigned to a client for the entire duration of its session (from login until logout). This mode is the most compatible with applications that rely on session-level state, temporary tables, or prepared statements. It provides the highest compatibility but uses connections less efficiently.
Transaction Mode: The connection is returned to the pool after each transaction completes. This mode offers a good balance between compatibility and resource efficiency. Most modern applications work well here.
Statement Mode: The connection is released back to the pool after every single SQL statement. This is the most efficient mode for resource usage but has the strictest compatibility requirements—applications cannot use transactions spanning multiple statements or rely on session state.

Choosing the right mode depends on your application's behavior. Some apps work best in session mode, while others perform well in transaction mode. See my post about pgbouncer and gitea as example.

Setting Up Pooling with CloudNativePG

CloudNativePG (CNPG) includes built-in support for PgBouncer through a dedicated Pooler resource. The operator does not create poolers automatically—you must define and apply them yourself.
Key points about CNPG poolers:

You can create multiple poolers for a single cluster.
A pooler cannot serve multiple clusters.
Poolers can target read-write (rw) or read-only (ro) traffic.
Poolers can serve different modes.

Here is an example of a basic read-write pooler in session mode:

apiVersion: postgresql.cnpg.io/v1
kind: Pooler
metadata:
  name: pooler-example-rw
  namespace: your-namespace
spec:
  cluster:
    name: cluster-example
  instances: 3
  type: rw
  pgbouncer:
    poolMode: session
    parameters:
      max_client_conn: "1000"
      default_pool_size: "10"

Notes on the configuration:

The pooler name is your choice but cannot match the cluster name.
It must be deployed in the same namespace as the cluster.
Using suffixes like -rw or -ro helps when running separate read-write and read-only poolers, as well as describing the mode (-session).

The read-write pooler attaches to the primary instance and automatically follows failovers.

General Flow of PgBouncer:

Applications connect to the PgBouncer service instead of the PostgreSQL cluster directly.
PgBouncer accepts incoming client connections and manages a smaller pool of actual connections to PostgreSQL.
When a client requests data, PgBouncer assigns (or reuses) a backend connection.
After the operation (depending on the pool mode), the connection returns to the pool for reuse.
This dramatically reduces the load on PostgreSQL while keeping resource usage predictable.

Why Multiple Poolers Are Often Needed

Not every application behaves well with the same pooling mode. For example, some tools work flawlessly in session mode but fail in transaction mode, while others show the opposite behavior. Since the pool mode is set at the pooler level, it is common to run multiple poolers—one for each required mode—and point different applications to the appropriate one.

External Access to Poolers

For applications running outside the Kubernetes cluster, expose the poolers using NodePort or LoadBalancer services. Because external load balancers typically cannot route the same port to different backends, assign different ports to each pooler (e.g., 5432 for one and 6432 for another).

Additional Configuration Options

You can fine-tune PgBouncer with many parameters. For a complete list, refer to the official CNPG documentation on PgBouncer configuration options.

Monitoring and Observability

CNPG’s PgBouncer pooler includes a built-in Prometheus exporter with metrics prefixed by cnpg_pgbouncer_. Adding the proper scrape configuration to Prometheus allows you to collect these metrics and build insightful dashboards in Grafana.
The official CloudNativePG Grafana dashboard works great with these metrics.
Important reminder: Simply creating a pooler is not enough. You must update your applications to connect through the pooler service instead of the cluster service directly. Monitoring these connections and pool utilization is essential for performance tuning and ensuring everything runs smoothly.
Connection pooling with PgBouncer in CloudNativePG is one of the most effective ways to keep your PostgreSQL clusters stable and performant under load. Taking the time to configure the right modes and monitor usage pays off significantly in reliability and resource efficiency.

The next post in this series will look into monitoring CNPG, a very interesting topic.

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

CNPG - Installation - Database Import

12ww1160 — Sat, 27 Jun 2026 14:05:20 +0000

Importing Databases into CloudNativePG (CNPG) Clusters

In the previous post of our CNPG series, we explored the importance of secrets, roles, and database creation in a multi-database cluster setup. If you’ve been following along and applying the concepts, you should now have a working multi-node cluster with one or more empty databases ready to use.

In this post, we’ll look at practical ways to bring your databases to life by importing real data. There are several approaches, each with its own strengths.

Common Import Methods

You generally have two main categories of database import:

Native CNPG methods (require access to the source cluster)
- Microservice-style approach
- Monolithic-style approach
External access methods (using standard PostgreSQL tools)

All of these methods rely heavily on PostgreSQL’s native backup tools: pg_dump and pg_restore. The key differences lie in the workflow and requirements.

CNPG `initdb.import` Method

The official CloudNativePG documentation covers the initdb.import feature in detail here. The process is straightforward when conditions are ideal.

Key requirements include:

Full network connectivity between source and target clusters
Proper access credentials
Compatible TLS certificates (critical in production environments)
Matching or newer PostgreSQL version on the target
Reliable online backup strategy (including snapshots) on the source

When everything aligns, this method can feel seamless. However, real-world migrations often face challenges:

Source clusters frequently run older PostgreSQL versions (sometimes as old as 9.x) while targets use modern versions (16–18).
Older versions may lack advanced features like proper Multi-Version Concurrency Control (MVCC) snapshots.
TLS certificate mismatches (different domains, intermediate CAs, etc.) are common.
The source cluster might no longer be online or accessible.

Careful planning and testing of workarounds are essential for successful migrations.

Traditional PostgreSQL Export/Import (Most Common Approach)

In many cases, standard pg_dump backups already exist. These produce plain SQL files (e.g., mydb_backup.sql) that can be easily transferred, reviewed, and restored.

Advantages:

Works well for small to medium-sized databases
Creates complete, consistent backups
Easy to transfer over networks
No complex TLS configuration needed between clusters
Simple to automate with scripts

Disadvantages:

Potential security considerations during transfer
Compliance with local data protection regulations
Large databases may require physical media shipment
Usually requires a maintenance window

Typical Workflow

Here’s the standard process most teams follow:

Announce a maintenance window.
Put the source database in read-only mode to prevent data loss.
Create a full backup:

pg_dump -U postgres -h localhost mydb > mydb_backup.sql

Review and edit the backup file if needed (e.g., update database owners or references).
Transfer the file to the target environment.
Restore using one of these options:

Option A – Using pg_restore:

pg_restore -d mydb mydb_backup.sql

Option B – Using psql (often simplest for new empty databases):

psql -h newhost -U mydb -d mydb < mydb_backup.sql

You can also pipe the dump directly (if network conditions allow):

pg_dump -U source_user -h source_host source_db | psql -U target_user -d target_db

Recommended Flow Diagram

Real-World Tips

In one recent project, I successfully migrated 18 databases of varying sizes by handling them one at a time. This approach allowed careful validation after each import. For larger-scale migrations, a well-tested shell script with looping can work well — but always expect at least one database to need special handling (different extensions, custom settings, etc.). Thorough testing in a staging environment is highly recommended.

This method gives you a reliable, battle-tested way to move your databases into CloudNativePG. In future posts, we’ll dive deeper into post-import validation, performance tuning, and ongoing maintenance strategies.
Stay tuned!

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

CNPG - Installation - Roles and Databases

12ww1160 — Sat, 27 Jun 2026 10:42:57 +0000

Installing Your CNPG Cluster: Roles, Databases, and Access Control

In the previous post, we walked through installing the CloudNativePG operator and bootstrapping a basic cluster. Now it is time to go deeper and configure roles, databases, and proper access controls—especially when running multiple databases within the same cluster.

If you are only hosting a single database, the basic bootstrap configuration from the last post is often all you need. It automatically creates the database, its owner, and a Kubernetes Secret for credentials:

bootstrap:
  initdb:
    database: app          # Name of your database
    owner: app             # Database owner role
    secret:
      name: app-secret     # Kubernetes Secret for credentials

Choose clear, descriptive names that match your application. For many environments, however, you will need multiple databases with isolated owners and stricter security rules.

Enabling Superuser Access

Especially with multiple databases, it is highly recommended to enable superuser access on the cluster. This account is extremely useful for cross-database maintenance tasks, running custom backup scripts, performing cleanups, or executing administrative procedures.

Add this to your Cluster spec:

spec:
  instances: 3
  imagePullPolicy: IfNotPresent
  enableSuperuserAccess: true   # Recommended,  this enables the superuser account

The operator automatically creates a superuser and stores its credentials in a Secret named -superuser in the same namespace. You can retrieve the username and password from there whenever needed.

Adding Multiple Databases: Secrets, Roles, and pg_hba Rules

For each additional database, you typically need three components:

A Kubernetes Secret containing the username and password.
A managed Role defined in the Cluster.
A Database custom resource to create the actual database.
Optional but recommended: pg_hba rules for fine-grained connection control.

Here is a complete example for a database called my-cool-app-db:

# 1. Kubernetes Secret (create this first)
apiVersion: v1
kind: Secret
metadata:
  name: my-cool-app-db-cluster-secret
  namespace: postgres
  labels:
    cnpg.io/reload: "true"
type: kubernetes.io/basic-auth
data:
  username: YWRtaW4=                      # base64 encoded "admin"
  password: c3VwZXJzdHJvbmdwYXNzd29yZA==  # base64 encoded "password"

# 2. Cluster definition with role and pg_hba
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-example-initdb
  namespace: postgres
spec:
  instances: 3
  imagePullPolicy: IfNotPresent
  enableSuperuserAccess: true

  managed:
    roles:
      - name: my-cool-app-role
        ensure: present
        comment: "Role for Cool-App database"
        passwordSecret:
          name: my-cool-app-db-cluster-secret
        login: true                    # Important: allows login

  postgresql:
    pg_hba:
      - hostssl my-cool-app-db my-cool-app-role 10.244.0.0/16 md5

  # ... existing bootstrap and storage sections ...

# 3. Create the actual database
apiVersion: postgresql.cnpg.io/v1
kind: Database
metadata:
  name: my-cool-app-db
  namespace: postgres
spec:
  name: my-cool-app-db
  owner: my-cool-app-role
  cluster:
    name: cluster-example-initdb

Apply everything with:

kubectl apply -f your-cluster.yaml

or your preferred CI/CD tol, i.e. argo-cd.

Tip: For demonstration reasons, the 3 sections above were all listed in the cluster-config.yaml For better long-term maintainability, split Secrets, the main Cluster definition, and individual Database resources into separate YAML files. This makes it easier to manage and review changes over time.

How it all acts together

Kubernetes Secrets store credentials securely.
The CNPG Operator reads these Secrets and creates or updates PostgreSQL Roles (users) inside the database.
You define pg_hba rules in the Cluster manifest to control who can connect, from where, and how (SSL, authentication method).
Applications connect using the credentials from the Secrets, and only connections matching the pg_hba rules are allowed.

This setup gives you strong isolation and security while keeping everything declarative and GitOps-friendly.

Best Practices

Use strong, unique passwords for each database role.
Leverage pg_hba rules to restrict connections by database, user, and network source.
Keep Secrets in Git (encrypted if necessary) or manage them through your secret management solution.
Test access thoroughly after applying changes.

With roles and databases properly configured, your CNPG cluster is now ready for real data.

In the next post, we will cover importing existing database content into your new CNPG cluster—using logical replication, pg_dump/restore, and other proven strategies.
Have you started building your CNPG clusters? What challenges have you run into with roles and multi-database setups? Share your experiences in the comments.
Stay tuned for the next installment in the CNPG series.

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

CNPG - installation

12ww1160 — Thu, 25 Jun 2026 14:37:43 +0000

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.

CNPG - considerations for migrating databases

12ww1160 — Wed, 24 Jun 2026 12:27:34 +0000

Key Considerations for Migrating Databases to CloudNativePG (CNPG)

Migrating databases is rarely simple. Achieving zero or minimal downtime while avoiding data loss demands careful planning. Moving to CloudNativePG (CNPG)—the Kubernetes-native PostgreSQL operator—introduces additional factors tied to containerized environments, Kubernetes storage, and operator-specific features.
While no guide can cover every scenario, the following considerations provide a strong starting point for a smooth transition.

1. Database Size

PostgreSQL databases consist of interconnected objects—schemas, tables, indexes, roles, and more—stored in a specific file structure managed by the server. Data movement typically relies on SQL operations, with backups (via pg_dump) being a common method. CNPG provides other methods, including direct access to the migration source, but that is not always feasible.

Small databases (a few MB or GB) are straightforward to transfer. Large ones—think tens or hundreds of terabytes—require much more planning around storage, time, and bandwidth.

Actionable first step:
Query your current PostgreSQL server to understand the footprint:

SELECT datname, pg_size_pretty(pg_database_size(datname)) AS size
FROM pg_database
ORDER BY pg_database_size(datname) DESC;

This returns a clear, human-readable table of database sizes. Note that pg_dump files are usually compressed, so they may be smaller than the live database. Always provision extra headroom on the target side to accommodate growth.

Pro tip: Before migrating, run cleanup jobs on the source. Remove old, unused data, temporary tables, or orphaned records. Every DBA knows how clutter accumulates—there is no reason to carry it forward.

2. Database Type (Source Compatibility)

Your source may not be PostgreSQL. Many applications support multiple backends, such as MySQL, MariaDB, or others. In these cases, you will need schema conversion, data type mapping, and possibly query adjustments.

Popular tools include:

pgloader — Excellent for migrating from MySQL or other systems to PostgreSQL.
mysqldump with compatibility flags, followed by manual tweaks.

Plan for differences in features, stored procedures, and data types early in the process.

3. Query and I/O Patterns

Size alone does not tell the full story. A modest database under heavy load can stress CPU, memory, storage IOPS, and network resources more than a large but quiet one.

Key steps:

Profile current workloads using tools like pg_stat_statements, pg_stat_io (available in PostgreSQL 16+), or external monitoring.
Benchmark the expected load on the target Kubernetes environment.
Leverage CNPG’s built-in replication: add multiple read-only replicas (typically three or more instances per cluster) to offload read traffic from the primary.

Understanding IOPS and file system behavior versus actual PostgreSQL activity is complex and often warrants dedicated testing. A well-provisioned CNPG cluster with proper storage classes can handle demanding workloads effectively.

4. High Availability (HA) Requirements

Traditional PostgreSQL HA solutions (e.g., Patroni) work well but require manual management. CNPG provides native, automated HA with replicas and failover capabilities, plus integrated PgBouncer support for connection pooling.

This setup suits most applications using a primary for writes and replicas for reads. However, it is not an active-active configuration with multiple writable nodes. If your application demands true multi-master writes, conduct deeper research or consider additional patterns.

5. Backup and Restore Strategies

Backups are only as good as your last successful restore. Many organizations discover gaps only during a crisis.

Best practices:

Validate existing backup procedures and adapt them for CNPG.
CNPG offers built-in support for continuous archiving and recovery, often using object storage like S3.
For smaller databases or extra safety, combine this with traditional pg_dump / pg_restore.
Test restores regularly—ideally onto new clusters—to confirm end-to-end recoverability.

6. Data Transport

Moving data from on-premises to cloud (or between data centers) introduces logistical challenges.

Network constraints: Private networks, firewalls, and bandwidth limits can complicate large transfers.
Physical media: For very large databases, shipping drives is sometimes necessary, but many data centers restrict external USB/storage devices due to security policies.
Alternatives: Logical replication (via CNPG’s native PostgreSQL support) enables near-zero-downtime migrations by streaming changes in real time.

Plan the transport method early and account for security, compliance, and downtime windows.

7. Application Connectivity

Migration affects more than just the database. Consider:

Whether the application moves with the database or connects remotely.
Updated connection strings, service discovery in Kubernetes, and network policies.
New RBAC roles, secrets management, and security configurations.

Test connectivity thoroughly in a staging environment, paying special attention to Kubernetes networking and service exposure.

8. One Cluster or Many? (CNPG Architecture Decisions)

CNPG strongly recommends one PostgreSQL cluster per database (or per microservice) for isolation, security, and operational simplicity.
Important storage consideration: Decide whether to place Write-Ahead Log (WAL) files on the same volume as data or on a dedicated volume. WAL can grow rapidly, especially under heavy load or during replication lag. Using a separate walStorage volume prevents one from starving the other.

Evaluate your disk space, I/O patterns, and resource availability. Some teams run many databases in a single large CNPG cluster successfully; others prefer multiple smaller clusters on dedicated nodes. Choose based on validated requirements rather than convenience alone.

Final Thoughts

Migrating to CloudNativePG offers powerful Kubernetes-native PostgreSQL capabilities—automated HA, declarative management, and excellent operator integration—but success depends on thoughtful preparation.
Start with assessment (size, load, compatibility), design for isolation and performance, validate backups and connectivity, and test thoroughly. Tools like logical replication can minimize disruption, while proper storage configuration prevents nasty surprises with WAL growth.
With careful planning, you can achieve a reliable, scalable PostgreSQL environment that leverages the full power of Kubernetes. Good luck with your migration!

Have you migrated to CNPG? Share your experiences or specific challenges in the comments.

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

CNPG - Cloud Native Postgresql - Pilot

12ww1160 — Sun, 14 Jun 2026 13:26:22 +0000

Moving from Traditional Postgres to CNPG (Cloud Native Postgres)

Rising hosting costs and the desire to stay current with modern technologies prompted a significant shift in my lab cloud setup. The main goal was to reduce expenses while exploring newer tools. A key part of this plan involved moving as much workload as possible from traditional virtual machines to my existing, well-running Kubernetes cluster, which already hosts around 18 applications with plenty of capacity to spare.

Immediate Priorities

Two quick wins stood out:

Retire the dedicated database server
Move the Puppet-managed Nagios server onto an existing web server

Looking further ahead, I plan to migrate web services to Kubernetes, replace Nagios with Zabbix (which also runs nicely in Kubernetes), switch from Jenkins to GitLab CI, and give Prometheus another try in the cluster.

Thanks to the growing ecosystem of Kubernetes operators, managing complex services has become much smoother. The end result should be roughly half the number of servers—and significantly lower costs.

First Step: Moving to CNPG

Last year, I experimented with a standard Postgres container, but the results were disappointing. Performance lagged behind my VM-based setup, and I was limited to a single instance. In contrast, the VM environment delivered solid performance and allowed near-complete management through Puppet.

The new objectives for the CNPG migration were clear:

Run Postgres natively in Kubernetes
Manage everything through CI/CD and GitOps
Deploy a 3-node cluster
Enable straightforward database migrations
Implement reliable backups
Improve internal transport security via the Kubernetes network (even though everything was already TLS-secured in a private network)
Optionally expose database services to external applications

This migration took several days and required careful attention to several key areas:

Installation procedures
Networking requirements
Storage configuration
Backup strategies
Application connectivity
Data migration approaches

This blog series will explore each of these topics in dedicated posts. I know many others are tackling similar projects at work or in their own environments, so I hope these guides prove helpful.
Stay tuned for the first deep dive into the CNPG installation and setup process!

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

ConfDroid Puppet Modules - java

12ww1160 — Sat, 18 Apr 2026 16:24:20 +0000

Introducing confdroid_java: A Lightweight Helper for Reliable Java Installations

We’re continuing the ConfDroid Puppet modules series with a small but essential addition: confdroid_java.

This module does exactly one thing—and does it well. It installs and configures a specified Java version so that other Puppet modules can simply rely on it being there. No more guessing, no more manual setup, and no more version conflicts when you spin up Java-based services.

Think of it as the Java counterpart to our popular confdroid_php module. Just as confdroid_php prepares a clean PHP environment for applications like WordPress or Nagios, confdroid_java sets up the exact Java runtime that tools like confdroid_jenkins (and any future Java-dependent modules) expect. It keeps everything consistent, reproducible, and ready for automation.

What confdroid_java actually does

Installs the Java binaries you specify through parameters
Places all necessary configuration files in the correct locations
Automatically applies the right SELinux contexts (and gracefully ignores them on systems where SELinux is disabled)
Stays deliberately lightweight—no unnecessary features, no external module dependencies

It is designed to be a silent foundation. You include it once, and every Java-needing module that follows can simply assume a working Java environment is already in place. Confdroid modules which rely on it like confdroid_jenkins automatically add it, as long as it is in the Puppet catalogue.

Supported platforms

Fully tested and validated on Rocky Linux 9
Expected to work on all RHEL 9-based distributions
Requires Puppet 8

How to use it

The simplest way is just to include the class:

node 'example.example.net' {
  include confdroid_java
}

Or, if you manage your nodes with Foreman, simply set the desired parameters (Java version, installation source, etc.) directly in the host or host-group configuration. No extra code required.

Important note: This module is meant for fresh systems. If Java has already been installed or configured manually on a server, applying confdroid_java could overwrite those changes. Always test in a lab environment first.

Where to get it

The full module, complete documentation, and parameter reference are available right now in the Confdroid Forge:

You’ll also find the generated documentation in the doc/ folder inside the repository.

Why this module matters

In larger Puppet environments, helper modules like confdroid_java (and its PHP sibling) are the glue that makes everything else click. They remove duplication, enforce consistency, and let the bigger application modules focus on what they do best—managing Jenkins, application servers, or any other Java workload—without reinventing the Java installation wheel every time.
If you’re already running other ConfDroid modules on Rocky 9, adding confdroid_java is a quick win that will make your Java-based services even more reliable and easier to maintain.
Happy automating!
As always, feedback and pull requests are welcome in the repository.

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

ConfDroid Puppet Modules - SSH

12ww1160 — Sat, 18 Apr 2026 15:33:33 +0000

Introducing confdroid_ssh: Reliable and Hardened SSH Access for Your Rocky 9 Servers

SSH is the primary way we access and manage Linux servers. When SSH stops working, everything else grinds to a halt — troubleshooting becomes painful, and automation pipelines can fail.

To solve this, I created confdroid_ssh, a new Puppet 8 module that ensures the SSH daemon (sshd) is always installed, properly configured, running, and reachable.

The module provides a hardened, consistent SSH setup across your entire infrastructure while making it easy to apply custom security policies.

Why This Module Matters

Guarantees SSH access is always available.
Applies secure defaults for ciphers, MAC algorithms, and other important settings
Manages the main sshd_config safely through drop-in files in /etc/ssh/sshd_config.d/
Handles SELinux contexts automatically (works great together with confdroid_selinux)
Optionally manages firewall rules to keep the SSH port open
Prevents configuration drift and manual overrides that often cause problems

It fits perfectly into the Confdroid collection alongside confdroid_selinux (for global SELinux enforcement) and confdroid_fail2ban (for brute-force protection on SSH).

Key Features

Installs the SSH server packages and required binaries
Manages the sshd service (ensures it is enabled and running)
Supports custom configuration snippets via the confdroid_ssh::custom::custom_config define
Automatically applies correct SELinux contexts
Optionally opens the SSH port in the firewall (iptables/nftables)
Designed for Rocky 9 (and other RHEL 9-based systems)

Example: Adding Custom Configuration

You can easily add your own secure settings without touching the main config file:

confdroid_ssh::custom::custom_config { '30-my-hardening':
  config_name    => '30-my-hardening',
  config_content => [
    'PasswordAuthentication no',
    'PermitRootLogin no',
    'MaxAuthTries 3',
  ],
}

This creates a cleanly managed file /etc/ssh/sshd_config.d/30-my-hardening.conf, overriding default settings from the main configuration file.

How It Fits in the Confdroid Ecosystem

confdroid_ssh works hand-in-hand with the rest of the collection:

confdroid_selinux ensures the global SELinux mode is set correctly
confdroid_fail2ban protects SSH against brute-force attacks All other modules benefit from reliable SSH access for management and deployment.

Important Notes

Warning: This module overwrites SSH configuration. Do not use it right on systems that have heavy manual SSH customizations. Always test first in a non-production environment, and move your manual configuration into the module via the provided define see example. It is likely best practice to use small snippets depending on various conditions only when they apply. Not every Linux system follows the same pattern depending on the applications it hosts.
The module follows the Confdroid “ENC-first” philosophy — configure everything comfortably through Foreman smart class parameters.

You can find the full module, source code, parameter reference, and documentation here: https://sourcecode.confdroid.com/confdroid/confdroid_ssh

Final Thoughts

With confdroid_ssh, you no longer have to worry about SSH breaking after updates or configuration changes. It provides a solid, hardened, and fully automated foundation for secure remote access across your Rocky 9 fleet.

Combined with confdroid_selinux and confdroid_fail2ban, it forms a strong security layer that keeps your servers accessible to you — but not to attackers.
Have you ever lost SSH access due to a misconfiguration or update? How do you currently manage SSH hardening across your servers? Share your experiences or questions in the comments — I’d love to hear them!

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

ConfDroid Puppet Modules - Selinux

12ww1160 — Sat, 11 Apr 2026 10:04:51 +0000

Introducing confdroid_selinux: Declarative SELinux Management for Your Rocky 9 Servers

Security-Enhanced Linux (SELinux) is one of the most powerful built-in defenses on modern Linux systems. Unlike traditional permission-based security (user/group/other), SELinux adds mandatory access control (MAC) at the kernel level. It labels every process, file, directory, and network port with a security context and enforces strict policies that say exactly what each subject is allowed to do with each object — no matter what the file permissions say.

This means even if an attacker gains root or tricks a service into writing a malicious file, SELinux can still block the attack because the file simply doesn’t have the right context.
Many enterprise Linux distributions enable SELinux by default in enforcing mode on fresh installs:

Rocky Linux 9
AlmaLinux 9
Red Hat Enterprise Linux (RHEL) 9
Fedora

On these systems, SELinux is not an afterthought — it’s a core part of the security model.

How SELinux Stops Real-World Attacks

Imagine an attacker sends a phishing email with a malicious script disguised as a legitimate configuration file. The user (or a compromised service) downloads and places the file in /tmp or a web directory.

Without SELinux:

If the file has execute permissions, the attacker might be able to run it.

With SELinux (enforcing mode):

The file gets created with the wrong security context (for example, user_tmp_t instead of httpd_exec_t).
Even if the attacker somehow makes the file executable, SELinux denies execution or access because the policy doesn’t allow it.
The attack is stopped cold, and an audit log entry is generated.

SELinux turns potential disasters into harmless denied operations.

The Problem with Manual SELinux Management

While SELinux is powerful, managing it consistently across many servers is painful:

Forgetting to run restorecon after placing files
Accidentally setting the wrong mode (setenforce)
Configuration drift between hosts

That’s exactly why I built confdroid_selinux.

What confdroid_selinux Does

This new Puppet 8 module (tested on Rocky 9) gives you full declarative control over SELinux:

Installs all required SELinux tools and binaries
Manages the main configuration file /etc/sysconfig/selinux with correct permissions and SELinux contexts
Controls the global SELinux mode (enforcing or permissive) — the Puppet equivalent of setenforce
Ensures every file and directory managed by other Confdroid modules receives the proper SELinux context
Works cleanly on enforcing-mode systems

All other Confdroid modules (see the full collection overview) already include proper SELinux context handling:

and many more.

They work even better when **confdroid_selinux** is present, because the global policy and mode are managed in one place.

SELinux Management Flow with the Module

Here’s how the module turns your Puppet run into reliable SELinux enforcement:

Easy Deployment

Simple inclusion: in your site.pp or nodes.pp:

include confdroid_selinux

with Foreman (recommended):

Add the confdroid_selinux::params class to the host or host group and override parameters (mode, etc.) as smart class parameters.

Important notes:
Test in a non-production environment first.
If you are switching from disabled to enforcing mode, a reboot is required (the module does not reboot automatically to avoid surprises).

You can find the full module, source code, and parameter reference here:
→

Final Thoughts

SELinux is no longer optional on modern enterprise Linux. With confdroid_selinux, you get consistent, version-controlled, and fully automated SELinux management that works hand-in-hand with the rest of the Confdroid collection.
Your servers stay secure by default — even when things go wrong elsewhere.
Have you been running SELinux in enforcing mode across your fleet, or are you still in permissive because of management headaches? Would you like to see more advanced features (custom Booleans, custom modules, etc.) in a future version? Let me know in the comments!

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

ConfDroid Puppet Modules - Automatic

12ww1160 — Tue, 07 Apr 2026 10:59:02 +0000

Introducing confdroid_automatic: Hands-Off OS Updates for Your Rocky 9 Servers

Keeping operating systems patched is one of the most important — yet often neglected — parts of server maintenance. Security updates arrive regularly, and manually applying them across dozens or hundreds of machines quickly becomes a burden and a source of risk.

That’s why I’m happy to release confdroid_automatic, the latest addition to the Confdroid Puppet collection.

This module brings reliable, automated OS updates to Rocky 9 (and other RHEL 9-based) systems by managing dnf-automatic declaratively with Puppet 8. It installs the necessary packages, configures update behavior, applies correct SELinux contexts, and ensures the systemd timer runs as expected.

Why Automated Updates Matter

Security patches close vulnerabilities before attackers can exploit them. dnf-automatic already does most of the heavy lifting out of the box — it can download and apply updates on a schedule, send notifications, and even reboot when needed. The challenge is managing it consistently across your entire fleet without configuration drift.

Additionally, production systems may need a different set of policies for updates than development or staging system, i.e. only security updates, while other stages use fully updated systems.

confdroid_automatic solves that by turning dnf-automatic into a fully Puppet-controlled service.

Key Features

Installs and configures the dnf-automatic package
Manages the main configuration file (/etc/dnf/automatic.conf) with proper permissions and SELinux contexts
Controls the dnf-automatic.timer systemd service
Supports flexible parameters you can override via Foreman ENC or Hiera
Includes sensible defaults for production use while allowing fine-tuning

Main tunable parameters include:

ac_upgrade_type- 'default', 'security', 'minimal' or 'all'
ac_apply_updates — whether to actually install updates (or just download them)
ac_download_updates — enable downloading of available packages
ac_random_sleep — add a random delay (in seconds) to prevent all servers from updating at the exact same moment
ac_reboot - when to reboot after applied updates
ac_email_to - which email address to notify

Automatic Update Flow

Here’s how the module turns Puppet configuration into real-world automated patching:

The flow ensures updates are applied safely and predictably. The optional random sleep helps avoid “thundering herd” problems in larger environments.

How to Use It

Import the module via r10k (Puppetfile).

The simplest way to enable automatic updates on a node is in site.pp:

include confdroid_automatic

To apply via Foreman:

Assign confdroid_automatic::params to the host or hostgroup in Question and override parameters as required.

Important Notes

Test thoroughly in a non-production environment first. Automatic updates can cause reboots or service restarts.
If you already have a manual dnf-automatic configuration, the module will overwrite it — start clean or review the generated config carefully.
The module handles SELinux contexts automatically, so it works smoothly on enforcing-mode Rocky 9 systems.

You can find the full module, source code, and parameter reference here: https://sourcecode.confdroid.com/confdroid/confdroid_automatic

Final Thoughts

With confdroid_automatic, keeping your Rocky 9 fleet patched becomes a truly hands-off process. Combined with the rest of the Confdroid collection (including monitoring via confdroid_nagios), you get a consistent, secure, and maintainable update strategy.

Automated patching is no longer a nice-to-have — it’s a baseline security requirement. This module makes it simple, repeatable, and fully integrated into your Puppet workflow.

Have you been managing OS updates manually or with scripts? Would you like automatic reboots enabled or prefer a download-only approach? Drop your thoughts or questions in the comments — I’d love to hear how you handle patching in your environment.

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

DEV Community: 12ww1160

CNPG - Configuration - TLS Encryption

Using TLS Encryption with CloudNativePG (CNPG)

Encryption Modes in CloudNativePG

Setting Up TLS Encryption

Operator-Managed Mode (Default)

User-Provided Certificates Mode

How TLS Flows in Kubernetes with CloudNativePG

Final Thoughts

Related posts

CNPG - Installation - Monitoring

Monitoring CloudNativePG Clusters with the PLG Stack

What Is the PLG Stack?

The Tech Stack in This Environment

How CNPG Monitoring Works

Required Permissions (RBAC)

Visualizing Data in Grafana

How the PLG Stack Works Together

Related posts

CNPG - Installation - Connection pooling

Connection Pooling in CloudNativePG: Managing Postgres Connections Efficiently

PgBouncer Pooling Modes

Setting Up Pooling with CloudNativePG

Why Multiple Poolers Are Often Needed

External Access to Poolers

Additional Configuration Options

Monitoring and Observability

Related posts

CNPG - Installation - Database Import

Importing Databases into CloudNativePG (CNPG) Clusters

Common Import Methods

CNPG initdb.import Method

Traditional PostgreSQL Export/Import (Most Common Approach)

Recommended Flow Diagram

Real-World Tips

Related posts

CNPG - Installation - Roles and Databases

Installing Your CNPG Cluster: Roles, Databases, and Access Control

Enabling Superuser Access

Adding Multiple Databases: Secrets, Roles, and pg_hba Rules

How it all acts together

Best Practices

Related posts

CNPG - installation

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

1. Install the CNPG Operator

2. Create a ClusterImageCatalog

3. Design Decisions Before Bootstrapping

4. Example Cluster Manifest

Next Steps and Tips

Related posts

CNPG - considerations for migrating databases

Key Considerations for Migrating Databases to CloudNativePG (CNPG)

1. Database Size

2. Database Type (Source Compatibility)

3. Query and I/O Patterns

4. High Availability (HA) Requirements

5. Backup and Restore Strategies

6. Data Transport

7. Application Connectivity

8. One Cluster or Many? (CNPG Architecture Decisions)

Final Thoughts

Related posts

CNPG - Cloud Native Postgresql - Pilot

Moving from Traditional Postgres to CNPG (Cloud Native Postgres)

Immediate Priorities

First Step: Moving to CNPG

Related posts

ConfDroid Puppet Modules - java

Introducing confdroid_java: A Lightweight Helper for Reliable Java Installations

What confdroid_java actually does

Supported platforms

How to use it

Where to get it

Why this module matters

Related posts

ConfDroid Puppet Modules - SSH

Introducing confdroid_ssh: Reliable and Hardened SSH Access for Your Rocky 9 Servers

Why This Module Matters

Key Features

CNPG `initdb.import` Method