3.2 Image Catalog

Cluster 정의 안에 PostgreSQL 이미지 태그를 직접 적으면, 이미지를 올릴 때마다 모든 Cluster 매니페스트를 찾아 고쳐야 합니다. Image Catalog는 "major 버전 → 이미지" 매핑을 별도 리소스로 빼내, Cluster는 major 버전만 가리키게 만듭니다. 이렇게 이미지 수명주기를 Cluster 정의에서 떼어 두면, 카탈로그의 이미지를 바꾸는 것만으로 이를 참조하는 모든 Cluster에 rollout이 전파됩니다.

공식 operand 이미지 변종과 tag 규칙

카탈로그에 어떤 이미지를 넣을지 정하려면 먼저 CloudNativePG 커뮤니티가 ghcr.io/cloudnative-pg/postgresql로 배포하는 공식 operand 이미지의 변종을 알아야 합니다. 변종은 세 가지고, 차이는 이미지에 함께 담긴 것입니다.

변종	내용	비고
`minimal`	Debian slim + PGDG(PostgreSQL 공식 apt 저장소) 패키지	PostgreSQL 18부터 LLVM JIT 미포함
`standard`	`minimal` + PGAudit, pg_failover_slots, pgvector, 전체 locale, LLVM JIT	contrib 외 extension이 조금 필요할 때
`system`	`standard` + Barman Cloud 바이너리	deprecated. in-core Barman Cloud 제거와 함께 사라질 예정

기반 OS는 Debian 13 trixie(stable)와 Debian 12 bookworm(oldstable) 두 가지입니다. 신규 클러스터라면 minimal 또는 standard에 trixie를 고르고, 그 밖의 extension은 image volume(9.5)으로 추가하는 구성이 1.30의 방향입니다.

tag는 MM.mm-TS-TYPE-OS 형식입니다. 예를 들어 16.10-202509090953-minimal-trixie는 PostgreSQL 16.10을 2025-09-09 09:53에 빌드한 minimal trixie 이미지입니다. 편의용 rolling tag도 있습니다.

MM.mm-TYPE-OS (예: 18.4-minimal-trixie) — 해당 minor의 최신 빌드
MM-TYPE-OS (예: 18-minimal-trixie) — 해당 major의 최신 minor

18.4나 18처럼 변종과 OS가 없는 단독 tag는 deprecated여서 새로 만들어지지 않습니다. 운영에서는 timestamp까지 포함한 tag나 카탈로그의 digest 고정을 쓰고, rolling tag는 실험 환경에 한정하는 편이 재현성에 유리합니다.

노트

아래 예제들은 공식 문서의 예를 따라 system 변종을 씁니다. 신규 구성이라면 minimal이나 standard로 바꾸고 Barman Cloud는 플러그인(7.1)으로 붙입니다.

두 가지 CRD

카탈로그는 스코프에 따라 두 CRD로 나뉩니다. 스키마는 동일하고, 적용 범위만 다릅니다.

리소스	스코프	용도
`ImageCatalog`	namespace 한정	팀·애플리케이션별 이미지 버전
`ClusterImageCatalog`	클러스터 전역	조직 전체 표준 이미지

카탈로그 구조

major 버전 번호로 이미지를 색인합니다. 하나의 카탈로그 안에서 각 major 버전은 한 번만 등장할 수 있습니다.
componentImages로 PgBouncer 같은 비(非) PostgreSQL 컴포넌트 이미지도 함께 관리합니다.
PostgreSQL 18 이상에서는 인증된 extension 컨테이너 이미지도 항목에 묶을 수 있습니다.

노트

Operator는 사용자가 선언한 major 버전을 검증하지 않고 그대로 신뢰합니다. 즉 major: 17로 적어 두고 실제로는 16 이미지를 가리켜도 막지 않습니다. 공식 CloudNativePG 카탈로그는 커뮤니티 검증을 거치므로, 직접 카탈로그를 만들 때는 major 번호와 실제 이미지 버전이 맞는지 스스로 확인해야 합니다.

카탈로그 정의 예제

ImageCatalog (namespace)

apiVersion: postgresql.cnpg.io/v1
kind: ImageCatalog
metadata:
  name: postgresql
  namespace: default
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.4-system-trixie

ClusterImageCatalog (전역)

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.4-system-trixie

componentImages 예제

componentImages 항목의 key는 소문자 영숫자(하이픈 허용, 1~63자)로 지정합니다. 현재는 Pooler 리소스가 PgBouncer 이미지를 중앙에서 관리하는 데 사용합니다. 1.30부터 Pooler는 spec.pgbouncer.imageCatalogRef로 이 항목을 참조할 수 있고, 카탈로그의 PgBouncer 이미지가 바뀌면 참조하는 Pooler가 자동으로 rollout됩니다.

apiVersion: postgresql.cnpg.io/v1
kind: ImageCatalog
metadata:
  name: my-catalog
  namespace: default
spec:
  images:
    - major: 18
      image: ghcr.io/cloudnative-pg/postgresql:18.4-system-trixie
  componentImages:
    - key: pgbouncer
      image: ghcr.io/cloudnative-pg/pgbouncer:1.25.1

Cluster에서 참조

Cluster는 imageCatalogRef로 카탈로그의 종류(kind), 이름(name), 원하는 PostgreSQL major 버전(major)을 지정합니다. Operator가 카탈로그에서 해당 major에 매핑된 이미지를 찾아 인스턴스에 적용합니다.

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-example
spec:
  instances: 3
  imageCatalogRef:
    apiGroup: postgresql.cnpg.io
    kind: ClusterImageCatalog
    name: postgresql-global
    major: 18
  storage:
    size: 1Gi

경고

imageCatalogRef의 major 값을 15에서 16처럼 올려도 CloudNativePG가 major 버전 업그레이드(pg_upgrade 등)를 자동으로 대신 해 주지 않습니다. 카탈로그는 어디까지나 "어떤 이미지를 쓸지"를 결정할 뿐이며, major 업그레이드 절차는 별도로 계획해야 합니다.

공식 카탈로그 사용

CloudNativePG는 검증된 ClusterImageCatalog 매니페스트를 artifacts 저장소로 제공합니다. 공식 카탈로그 이미지는 모두 SHA256 digest로 고정되어 불변성과 무결성을 보장합니다.

# 특정 카탈로그 하나 적용
kubectl apply -f \
  https://raw.githubusercontent.com/cloudnative-pg/artifacts/refs/heads/main/image-catalogs/catalog-minimal-trixie.yaml

# 배포된 전역 카탈로그 확인
kubectl get clusterimagecatalogs.postgresql.cnpg.io

공식 카탈로그를 쓰면 Cluster는 아래처럼 최신 minimal PostgreSQL 18(Debian Trixie) 이미지를 자동 추적합니다.

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: angus
spec:
  instances: 3
  imageCatalogRef:
    apiGroup: postgresql.cnpg.io
    kind: ClusterImageCatalog
    name: postgresql-minimal-trixie
    major: 18
  storage:
    size: 1Gi

노트

extension이 포함된 카탈로그는 CloudNativePG 1.29 이상에서만 동작합니다. 이전 버전 Operator는 extension 정의를 거부합니다.

공식 operand 이미지 변종과 tag 규칙​

두 가지 CRD​

카탈로그 구조​

카탈로그 정의 예제​

ImageCatalog (namespace)​

ClusterImageCatalog (전역)​

componentImages 예제​

Cluster에서 참조​

공식 카탈로그 사용​