agentleFS
Aidas-devAidas-dev/k8s-agent-skills/skills/cnpg/SKILL.md

cnpg

Skill4 starsChanged 5 months agoMITView on GitHub

Use when working with CloudNativePG (CNPG) for PostgreSQL on Kubernetes — creating or troubleshooting Cluster, Backup, ScheduledBackup, Pooler, or ImageCatalog resources; defining bootstrap, storage, backup, or affinity settings.

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Check helm list -n <ns> for deployed chart version.

    line 130

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

CloudNativePG (CNPG)

Overview

CloudNativePG operator manages HA PostgreSQL clusters on Kubernetes. API: postgresql.cnpg.io/v1. Deployed via Helm chart (latest: 0.28.2 \u2192 operator 1.29.1).

CRD Reference

CRDPurpose
ClusterHA PostgreSQL cluster (core resource)
BackupOn-demand backup
ScheduledBackupCron-based backup schedule
PoolerPgBouncer connection pooler
DatabaseDatabase-level management within cluster
Publication / SubscriptionLogical replication
ImageCatalog / ClusterImageCatalogExtension image management (v1.29+)
FailoverQuorumQuorum-based failover settings

Cluster Spec (Key Fields)

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
spec:
  instances: 1                    # Replicas (1 = standalone primary)
  imageName: ghcr.io/cloudnative-pg/postgresql:18

  storage:
    size: 10Gi
    storageClass: ceph-block      # Omit or null for cluster default
    resizePVC: true               # Allow storage resize via Helm upgrade

  walStorage:                     # Optional \u2014 separate WAL volume
    size: 5Gi
    storageClass: ceph-block

  bootstrap:
    initdb:
      database: app               # Default DB name
      owner: app                  # Default owner user
      postInitSQL:                # Run after init
        - CREATE EXTENSION vector;

  affinity:
    nodeSelector:
      kubernetes.io/hostname: worker-01
    podAntiAffinity:
      type: preferred             # required or preferred
      topologyKey: kubernetes.io/hostname

  postgresql:
    parameters:
      shared_preload_libraries: vector  # Extensions
    pg_hba:                             # Custom pg_hba (v1.29+ use podSelectorRefs)

  primaryUpdateStrategy: unsupervised   # unsupervised (default) or switchover
  primaryUpdateMethod: restart          # restart or switchover

  monitoring:
    enablePodMonitor: true              # Generates Prometheus PodMonitor

  backup:
    volumeSnapshot:
      snapshotClass: csi-ceph-block     # CSI snapshot class

Bootstrap Methods

MethodUse case
initdbFresh cluster from scratch
pg_basebackupClone from existing CNPG cluster
recoveryPITR from Barman/volumeSnapshot/plugin backup
pg_basebackup via recoveryBootstrap replica from another cluster

Backup Methods

MethodStatusDetails
barmanObjectStoreDeprecated (removed v1.30)S3/GCS/Azure via Barman Cloud
volumeSnapshotCurrentCSI snapshots (recommended for Ceph, EBS, etc.)
pluginCurrentCNPG-I gRPC plugin for backup/WAL/recovery

Affinity / Scheduling Patterns

  • nodeSelector — Pin to specific node (common for stateful workloads)
  • podAntiAffinity — Spread replicas across nodes (required for HA, preferred for soft)
  • topologySpreadConstraints — Distribute across zones
  • tolerations — For tainted nodes (GPU, infra-only)

Set per-instance overrides via instances + nodeSelector to pin specific roles.

ImageCatalog (v1.29+)

apiVersion: postgresql.cnpg.io/v1
kind: ClusterImageCatalog
metadata:
  name: postgres-extensions
spec:
  images:
    - image: ghcr.io/my-org/postgres:18-pgvector
      major: 18

Then reference in Cluster: spec.imageCatalogRef: postgres-extensions

Common Mistakes

  • BarmanObjectStore as default \u2014 deprecated, use volumeSnapshot or plugin
  • No WAL storage \u2014 important for HA. Add walStorage block for performance
  • resizePVC: false \u2014 prevents storage expansion on Helm upgrade
  • primaryUpdateStrategy: supervised \u2014 requires manual approval for switchover; use unsupervised for automatic
  • Same storageClass for all workloads \u2014 ceph-block fine for most, but immich needs local-fast for vector extension performance
  • Missing INHERITED_ANNOTATIONS / INHERITED_LABELS \u2014 empty is fine; only set if you want annotations propagated to PVCs

Version Mapping

Helm ChartOperatorRelease Notes
0.28.21.29.1Latest (CVE fixes)
0.28.01.29.0ImageCatalog, podSelectorRefs, CNPG-I plugins

Check helm list -n <ns> for deployed chart version; cross-reference with cloudnative-pg.io/release-notes.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.