postgres-operator-cloudnative-pg-migration skill
✓ VerifiedMigrates PostgreSQL clusters from Zalando postgres-operator to CloudNativePG on Kubernetes, handling glibc collation issues and backup incompatibility.
- GitHub stars
- 6
- Files
- 12
- Last commit
- Nov 10, 2026
- License
- MIT
- Allowed tools
- —
What does the postgres-operator-cloudnative-pg-migration skill do?
postgres-operator-cloudnative-pg-migration migrates PostgreSQL clusters from Zalando postgres-operator to CloudNativePG on Kubernetes, handling glibc collation issues and backup incompatibility.
Summary generated from the skill's SKILL.md.
About the postgres-operator-cloudnative-pg-migration skill
Database engineers moving from the Zalando postgres-operator to CloudNativePG on Kubernetes use this skill to navigate complex data migration challenges. It provides specialized guidance for handling the two primary technical barriers: glibc collation mismatches that cause index corruption during physical copies and the incompatibility between WAL-G and Barman backup formats. The skill helps users select the appropriate migration strategy based on their specific PostgreSQL version, database size, and downtime tolerance.
Users can implement logical replication for near-zero downtime, use initdb.import for smaller databases, or follow specific protocols for pg_basebackup when same-major migrations are required. It also assists in translating acid.zalan.do manifests into CNPG Cluster manifests, managing the transition of secrets, services, and monitoring metrics. For highly secure environments, it covers the requirements for air-gapped mirroring of all necessary images and Helm charts.
What an agent can do with it
- 1Select a migration pathDetermine whether to use logical replication, initdb.import, or pg_basebackup based on your database size and version.
- 2Reconfigure backup systemsPlan the transition from WAL-G archives to the barman-cloud CNPG-I plugin to ensure backups remain restorable.
- 3Translate Kubernetes manifestsMap existing Zalando operator configuration fields to their corresponding CloudNativePG equivalents.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the postgres-operator-cloudnative-pg-migration skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the postgres-operator-cloudnative-pg-migration skill in Plugin
/plugin marketplace add air-gapped/skills /plugin install k8s@air-gapped-marketplace
Install the postgres-operator-cloudnative-pg-migration skill in Claude Code
~/.claude/skills/postgres-operator-cloudnative-pg-migration/SKILL.md
$ npx degit air-gapped/skills/.claude/skills/postgres-operator-cloudnative-pg-migration ~/.claude/skills/postgres-operator-cloudnative-pg-migrationInstall the postgres-operator-cloudnative-pg-migration skill in Claude Code (project)
.claude/skills/postgres-operator-cloudnative-pg-migration/SKILL.md
$ npx degit air-gapped/skills/.claude/skills/postgres-operator-cloudnative-pg-migration .claude/skills/postgres-operator-cloudnative-pg-migrationInstall the postgres-operator-cloudnative-pg-migration skill in Codex
~/.agents/skills/postgres-operator-cloudnative-pg-migration/SKILL.md
$ npx degit air-gapped/skills/.claude/skills/postgres-operator-cloudnative-pg-migration ~/.agents/skills/postgres-operator-cloudnative-pg-migrationInstall the postgres-operator-cloudnative-pg-migration skill in Gemini CLI
~/.gemini/skills/postgres-operator-cloudnative-pg-migration/SKILL.md
$ npx degit air-gapped/skills/.claude/skills/postgres-operator-cloudnative-pg-migration ~/.gemini/skills/postgres-operator-cloudnative-pg-migrationInstall the postgres-operator-cloudnative-pg-migration skill in Claude.ai
npx degit air-gapped/skills/.claude/skills/postgres-operator-cloudnative-pg-migration postgres-operator-cloudnative-pg-migration && zip -r postgres-operator-cloudnative-pg-migration.zip postgres-operator-cloudnative-pg-migration # claude.ai → Customize → Skills → + → Create skill → Upload a skill → postgres-operator-cloudnative-pg-migration.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work · What to fix for more points
- Source repository linked and reachableair-gapped/skills/.claude/skills/postgres-operator-cloudnative-pg-migration is public and reachablegithub.com/air-gapped/skills/tree/HEAD/.claude/skills/postgr ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-10github.com/air-gapped/skills/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/air-gapped/skills/blob/HEAD/.claude/skills/postgr ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/air-gapped/skills/blob/HEAD/.claude/skills/postgr ↗Pass
- SKILL.md follows the Agent Skills formatthe description does not say when to use the skillgithub.com/air-gapped/skills/blob/HEAD/.claude/skills/postgr ↗Finding
SKILL.md
View on GitHubpostgres-operator-cloudnative-pg-migration
Migrate PostgreSQL clusters from the Zalando postgres-operator (Spilo + Patroni) to CloudNativePG with data intact, indexes trustworthy, backups restorable at every phase, and no dependency left on maintenance-mode artifacts. Facts below were verified 2026-07-24 against primary sources (both operator repos at HEAD, release manifests, maintainer statements); re-verify anything version-gated before relying on it in a later year. Version anchor (2026-10-27): Zalando v2.0.3 (Spilo-18 4.1-p2, PG 14–18; v2.0.0 and v2.0.1 are both defective), CNPG 1.30.1 (2026-09-23; PG 14–18; 1.29 EOL 2026-09-29, 1.31 due ~Dec 2026 — target 1.30.x), plugin-barman-cloud v0.15.1.
Why this migration exists
Zalando's operator runs on one sustained maintainer in confirmed low gear
(#2921) but is not dead — the v2 line shipped PG18, dropped PG13, and
flipped both kubernetes_use_configmaps and scram-sha-256 on by default.
CNPG runs ~7× the human commit volume across three maintained lines and
has a documented migration wave. This is strategic, not an emergency:
v2 extends the safe-to-stay horizon well past the old ~2027 estimate, and
CNPG brings its own churn costs. Migrate deliberately, cluster by cluster.
Full evidence, the skeptic's case, and alternatives: references/decision.md.
For staying and operating Zalando instead — the v1.x→v2.x upgrade, the
Patroni DCS/Endpoints switch, rolling-update triggers, day-2 operations —
use the sibling skill postgres-operator-best-practices.
The two walls that shape every plan
Wall 1 — glibc/collation (physical data paths). Spilo images are
Ubuntu (glibc 2.35; or a bundled Ubuntu 18.04 archive at glibc 2.27
when USE_OLD_LOCALES=true — common on long-lived fleets). CNPG operand
images are Debian bookworm/trixie (glibc 2.36/2.41). Zalando's initdb
default is en_US.UTF-8 (libc), so collation-sensitive btree indexes are
the norm. Any physical copy (pg_basebackup, replica promotion) crosses
at least one glibc boundary — for USE_OLD_LOCALES clusters it crosses
the catastrophic glibc-2.28 ISO-14651 break — and text indexes, unique
constraints, and partition bounds become silently corrupt. REFRESH COLLATION VERSION only silences the warning. Logical paths (replication,
import) rebuild indexes on the destination and dodge this entirely.
Triage per cluster before choosing a path:
SELECT datname, datcollate, datcollversion FROM pg_database; plus
checking USE_OLD_LOCALES in the pod env.
Wall 2 — WAL-G ↔ Barman (backup archives). Current Spilo backs up
with WAL-G; CNPG restores only Barman-Cloud-layout object stores. The
formats are disjoint (basebackups_005/wal_005 vs base/wals) with no
interop or conversion tool in either project. Consequences: a CNPG
cluster cannot bootstrap or PITR from the Zalando S3 archive, and after
cutover the old bucket is restorable only by a Spilo/WAL-G stack —
freeze it read-only and keep the retired cluster (or a documented
resurrection path) until the retention window expires. Take a fresh
CNPG base backup immediately at cutover.
Choosing a migration path
Three paths; pick by PG major, size, downtime budget, and Wall 1 status.
Full recipes with YAML and cutover sequences: references/migration-paths.md.
| Path | When | Downtime | Wall 1 |
|---|---|---|---|
| A. Logical replication (Publication/Subscription CRDs, CNPG ≥1.25) | default for production; source PG ≥10; no large objects | near-zero (write pause at cutover) | immune |
B. initdb.import (pg_dump/pg_restore) |
small DBs; PG ≤13 sources (CNPG images are 14–18 — jump majors in one hop); large objects | full copy window | immune |
C. pg_basebackup / replica promote |
same major only; TB-scale where logical copy is impractical | short (promote) | exposed — amcheck + full REINDEX of text indexes mandatory |
The CNPG maintainer explicitly discourages C from Zalando sources ("You should not use physical replication to migrate from Zalando", #5736) — yet IBM Instana's supported runbook is exactly C, with Spilo conf-path fixes. Both are real; default to A, and treat C as the constrained exception it is.
Path A skeleton: set wal_level: logical on the Spilo manifest (rolling
restart) → CNPG Cluster with bootstrap.initdb.import + schemaOnly: true + externalClusters pointing at the Spilo primary (reuse the
Zalando credentials secret) → kubectl cnpg publication create --external-cluster (runs SQL on the source) → subscription create →
watch lag → pause writes → kubectl cnpg subscription sync-sequences →
repoint apps → drop pub/sub. Not carried: DDL, sequence values (the
sync-sequences step), large objects, matviews (REFRESH after).
Translating the manifest
No conversion tool exists anywhere — translation is manual against the
field map in references/manifest-map.md (every acid.zalan.do field →
CNPG equivalent or explicit gap, with minimum CNPG versions). The gaps
that most often force design decisions: preparedDatabases role trios
(reconstruct via managed.roles + inRoles + postInitApplicationSQLRefs),
password auto-generation for extra users (through 1.30 CNPG requires
pre-created basic-auth Secrets; 1.31 adds it for DatabaseRole only),
arbitrary sidecars/initContainers (CNPG-I plugins only),
enableLogicalBackup pg_dump cron (hand-build), and
maintenanceWindows (nodeMaintenanceWindow is a false friend — it
controls PVC reuse, not upgrade timing). Strip CNPG's ~60 operator-owned
parameters from any copied postgresql.parameters map.
Extensions: Spilo bundles timescaledb/postgis/pg_cron/pg_stat_kcache/
set_user/…; CNPG standard images add only PGAudit, pgvector,
pg_failover_slots, locales, JIT. pg_restore fails on missing
extensions. Drop unused Spilo extensions pre-dump, use the official
postgis image, or build a custom operand image (TimescaleDB has no
official CNPG image; timescale/timescaledb-ha is incompatible).
HA parity
CNPG closed most of the Patroni gap: default-on primary isolation
self-fencing (1.27), quorum-gated failover (1.28), primary lease (1.30).
The honest residual: a primary that loses the API server but still
reaches every peer is never fenced, even after a replica is promoted
— Patroni replicas pinged by the leader's failsafe refuse the leader
race, CNPG peers do not. With async replication that is a real
acknowledged-write split-brain window. For Patroni-equivalent
durability, migrated production clusters get 3 instances +
postgresql.synchronous: {method: any, number: 1, dataDurability: required, failoverQuorum: true}. Details, defaults, and open HA bugs to
watch: references/pitfalls.md §HA.
Backups, cutover, air-gap
- Backups: go plugin-first (1.31 is the last CNPG minor with in-tree
barmanObjectStore; removal is scheduled for 1.32.0 after slipping five times — never hard-code that). ObjectStore CRD wiring, the sidecar image hidden in the release manifest, cert-manager avoidance, dashboards for renamedbarman_cloud_*metrics, and the frozen-WAL-G-bucket plan:references/backup-chain.md. - Consumer cutover: services
<cluster>/<cluster>-repl→<cluster>-rw/-ro/-r; secrets<user>.<cluster>.credentials…→<cluster>-app/-superuser(richer keys); md5 password hashes surviving physical/monolith moves fail against scram-only pg_hba;pg_*exporter metrics →cnpg_*with no shim. Checklists:references/app-cutover.md. - Air-gap: the mirror list is operator + operand (
-standard-flavor keeps en_US.UTF-8 available) + pgbouncer + plugin + sidecar images, two Helm charts; no telemetry to disable; cosign-verify at the mirror boundary. Registry knobs (PULL_SECRET_NAME,POSTGRES_IMAGE_NAME):references/airgap.md.
Side-by-side operation of both operators in one cluster is safe
(different API groups; Zalando registers no webhooks) — but never reuse
a Zalando cluster name in the same namespace: Zalando pods <name>-0,1…
and CNPG pods <name>-1,2… collide at <name>-1.
Pitfalls quick index
Before executing any plan, scan references/pitfalls.md (severity-
ordered). Headliners beyond the walls: CNPG initdb defaults to C
locale (silent ORDER BY change vs Spilo's en_US.UTF-8 — set locale
explicitly, or move to ICU/builtin to escape glibc); enableSuperuserAccess
defaults false; CNPG pg_hba APPENDS where Zalando REPLACES; monolith
import strips SUPERUSER; first plugin backup on an idle cluster is
unrestorable until a WAL switch; SSL cannot be fully disabled in CNPG.
Reference files
| File | Read when |
|---|---|
references/decision.md |
deciding stay-vs-migrate; trend evidence, skeptic's case, alternatives |
references/migration-paths.md |
executing a migration: full recipes for paths A/B/C, per-cluster pre-flight triage |
references/manifest-map.md |
translating an acid.zalan.do manifest; field map + gaps + operator-config knobs |
references/backup-chain.md |
re-plumbing backups onto the barman-cloud plugin; WAL-G retention plan; snapshot-only option |
references/app-cutover.md |
repointing applications; secret/service/auth/monitoring checklists |
references/airgap.md |
air-gapped mirroring: exact images, charts, registry configuration |
references/pitfalls.md |
always, before executing a migration plan |
references/sources.md |
verifying or freshening any dated claim |
Files in this skill
12postgres-operator-cloudnative-pg-migration skill questions
How do I install the postgres-operator-cloudnative-pg-migration skill in Claude Code?
Run npx degit air-gapped/skills/.claude/skills/postgres-operator-cloudnative-pg-migration ~/.claude/skills/postgres-operator-cloudnative-pg-migration. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the postgres-operator-cloudnative-pg-migration skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
Can I use physical replication to migrate from Zalando to CNPG?
While possible via pg_basebackup for same-major versions, it is discouraged because glibc/collation divergence between Spilo (Ubuntu) and CNPG (Debian) can silently corrupt text indexes and unique constraints.
How do backups work during the migration?
Spilo uses WAL-G and CNPG uses Barman-Cloud; these formats are incompatible. You cannot bootstrap a CNPG cluster from a Zalando S3 archive and should take a fresh CNPG backup immediately after cutover.
Is it safe to run both operators in the same cluster?
Yes, they use different API groups and Zalando does not register webhooks, but you must never reuse a Zalando cluster name in the same namespace to avoid pod name collisions.