feat(postgres): add ClusterImageCatalog for system components by IvanHunters · Pull Request #2342 · cozystack/cozystack

IvanHunters · 2026-04-06T11:24:47Z

Summary

Protects system PostgreSQL databases from automatic major version upgrades by introducing centralized ClusterImageCatalog resources based on official CNPG artifacts.

Background

CloudNativePG operator v1.26+ automatically triggers major version upgrades when imageName changes in the Cluster spec. Legacy tag 17.7 is deprecated and pointed to system images which are also deprecated.

Solution

Deploy two shared ClusterImageCatalog resources (bookworm and trixie) with postgres-operator using standard image type from CNPG official artifacts. Standard images provide more extensions than minimal (includes pgaudit, etc.) while system images are deprecated.

Image Types Comparison

Based on CNPG postgres-containers:

minimal: Barebones PostgreSQL on Debian + PGDG packages
standard: minimal + pgaudit + additional extensions ✅ We use this
system: standard + Barman Cloud binaries (deprecated) ❌

Changes

ClusterImageCatalog resources:

postgresql-bookworm - Standard images on Debian bookworm (PostgreSQL 13-17)
postgresql-trixie - Standard images on Debian trixie (PostgreSQL 13-17)
PostgreSQL 18 excluded to prevent auto-upgrades
SHA256-pinned images for reproducibility

System databases updated:

keycloak/templates/db.yaml → postgresql-bookworm major 17
harbor/templates/database.yaml → postgresql-bookworm major 17
monitoring/templates/grafana/db.yaml → postgresql-bookworm major 17
monitoring/templates/alerta/alerta-db.yaml → postgresql-bookworm major 17
seaweedfs/templates/database.yaml → postgresql-bookworm major 17

Makefile automation:

Added make update-image-catalogs target
Downloads latest catalogs from https://github.com/cloudnative-pg/artifacts
Automatically excludes PostgreSQL 18
Renames to cozystack naming convention

Benefits

No manual migrations - catalogs deploy with operator, templates update via OCIRepo
Standard images - more extensions than minimal, system images deprecated
Dual OS support - bookworm (stable) and trixie (testing) available
Automated updates - make update-image-catalogs syncs with upstream
Version control - PostgreSQL 18 excluded, prevents accidental upgrades
Upstream alignment - based on official CNPG image catalog format

Usage

Update catalogs when CNPG releases new PostgreSQL versions:

cd packages/system/postgres-operator
make update-image-catalogs

Test Plan

Verify both ClusterImageCatalog resources deploy with postgres-operator
Confirm existing databases continue running on PostgreSQL 17
Check CNPG operator respects imageCatalogRef and does not trigger upgrades
Validate make update-image-catalogs correctly downloads and filters catalogs
Test trixie catalog works for clusters that need newer Debian base

Summary by CodeRabbit

Chores
- Migrated multiple PostgreSQL database deployments to use centralized image catalog selection instead of fixed versions, improving deployment flexibility and maintainability across system components.
- Introduced new image catalog infrastructure for PostgreSQL, enabling standardized version and distribution management throughout the platform.

coderabbitai · 2026-04-06T11:24:54Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 62a118dd-273a-4061-9a4e-22f4469292c9

📥 Commits

Reviewing files that changed from the base of the PR and between b7486ae and a0ddacd.

📒 Files selected for processing (8)

packages/system/harbor/templates/database.yaml
packages/system/keycloak/templates/db.yaml
packages/system/monitoring/templates/alerta/alerta-db.yaml
packages/system/monitoring/templates/grafana/db.yaml
packages/system/postgres-operator/Makefile
packages/system/postgres-operator/templates/image-catalog-bookworm.yaml
packages/system/postgres-operator/templates/image-catalog-trixie.yaml
packages/system/seaweedfs/templates/database.yaml

✅ Files skipped from review due to trivial changes (4)

packages/system/monitoring/templates/alerta/alerta-db.yaml
packages/system/postgres-operator/Makefile
packages/system/postgres-operator/templates/image-catalog-bookworm.yaml
packages/system/postgres-operator/templates/image-catalog-trixie.yaml

🚧 Files skipped from review as they are similar to previous changes (4)

packages/system/harbor/templates/database.yaml
packages/system/monitoring/templates/grafana/db.yaml
packages/system/keycloak/templates/db.yaml
packages/system/seaweedfs/templates/database.yaml

📝 Walkthrough

Walkthrough

The changes migrate PostgreSQL CNPG database configurations across five services from hardcoded image references to catalog-based resolution. Two new ClusterImageCatalog resources (bookworm and trixie variants) are added to the postgres-operator, a Makefile target is created to manage these catalogs, and corresponding database templates are updated to reference the catalogs instead of fixed image names.

Changes

Cohort / File(s)	Summary
Database Template Updates `packages/system/harbor/templates/database.yaml`, `packages/system/keycloak/templates/db.yaml`, `packages/system/monitoring/templates/alerta/alerta-db.yaml`, `packages/system/monitoring/templates/grafana/db.yaml`, `packages/system/seaweedfs/templates/database.yaml`	Changed CNPG `Cluster` spec from fixed `imageName` to `imageCatalogRef` pointing to `postgresql-bookworm` ClusterImageCatalog with major version 17.
Postgres Operator Catalog Infrastructure `packages/system/postgres-operator/Makefile`	Added `update-image-catalogs` target to fetch and process CNPG image catalog YAMLs via curl, sed, and awk, filtering for PostgreSQL versions ≤17 and generating bookworm and trixie catalog outputs.
Image Catalog Manifests `packages/system/postgres-operator/templates/image-catalog-bookworm.yaml`, `packages/system/postgres-operator/templates/image-catalog-trixie.yaml`	Added `ClusterImageCatalog` resources defining PostgreSQL container images for major versions 13–17 with pinned digests for bookworm and trixie distributions, enabling catalog-based image resolution.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 From hardcoded images to catalogs we leap,
PostgreSQL now chosen from a cataloged heap,
Five databases migrate with consistent grace,
Bookworm and Trixie find their rightful place,
Image resolution blooms where lookups trace! 📚✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: introducing ClusterImageCatalog resources for system components' PostgreSQL databases. It is concise, specific, and directly reflects the primary objective of the PR.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/postgres-image-catalog-system-components

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

gemini-code-assist

Code Review

This pull request migrates the PostgreSQL database configurations for Harbor, Keycloak, Monitoring (Alerta and Grafana), and SeaweedFS to use the ClusterImageCatalog resource instead of direct image names. New ClusterImageCatalog templates have been added for each service to manage PostgreSQL 17.7 images. I have no feedback to provide.

Protect system PostgreSQL databases from automatic major version upgrades by introducing centralized ClusterImageCatalog resources based on official CNPG artifacts repository. Changes: - Add two ClusterImageCatalog resources (bookworm and trixie OS variants) - Based on CNPG official standard images with PostgreSQL 13-17 support - PostgreSQL 18 excluded to prevent auto-upgrades - Replace hardcoded imageName with imageCatalogRef in all system databases - Add Makefile target 'update-image-catalogs' for automated catalog updates System components using catalogs: - keycloak-db → postgresql-bookworm major 17 - harbor-db → postgresql-bookworm major 17 - grafana-db → postgresql-bookworm major 17 - alerta-db → postgresql-bookworm major 17 - seaweedfs-db → postgresql-bookworm major 17 Benefits: - Catalogs deploy with operator, always available before cluster changes - Standard images include additional extensions (pgaudit, etc.) - Support for both Debian bookworm and trixie - Automated updates via 'make update-image-catalogs' - Changes propagate through OCIRepo without manual migrations Signed-off-by: IvanHunters <[email protected]>

IvanHunters marked this pull request as ready for review April 6, 2026 11:25

IvanHunters requested review from androndo, kvaps, lexfrei, lllamnyp and sircthulhu as code owners April 6, 2026 11:25

dosubot Bot added size:M This PR changes 30-99 lines, ignoring generated files. enhancement New feature or request labels Apr 6, 2026

gemini-code-assist Bot reviewed Apr 6, 2026

View reviewed changes

IvanHunters force-pushed the feat/postgres-image-catalog-system-components branch from 2a6249c to b7486ae Compare April 6, 2026 11:44

IvanHunters mentioned this pull request Apr 6, 2026

fix(migrations): remove migration 37 #2326

Closed

IvanHunters force-pushed the feat/postgres-image-catalog-system-components branch from b7486ae to a0ddacd Compare April 6, 2026 12:22

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(postgres): add ClusterImageCatalog for system components#2342

feat(postgres): add ClusterImageCatalog for system components#2342
IvanHunters wants to merge 1 commit intomainfrom
feat/postgres-image-catalog-system-components

IvanHunters commented Apr 6, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Apr 6, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

IvanHunters commented Apr 6, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Background

Solution

Image Types Comparison

Changes

Benefits

Usage

Test Plan

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

IvanHunters commented Apr 6, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Apr 6, 2026 •

edited

Loading