3.2 Image Catalog

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

    flowchart TD
  IC["ImageCatalog<br/>major→image 매핑"]
  C1["Cluster A"]
  C2["Cluster B"]
  REF["imageCatalogRef<br/>major: 18"]
  IMG["18.4 이미지 확정"]
  RO["이미지 변경 시<br/>자동 rollout"]

  C1 --> REF
  C2 --> REF
  REF --> IC
  IC --> IMG
  IC --> RO

  classDef step fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
  class IC,C1,C2,REF,IMG,RO step
  

두 가지 CRD

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

카탈로그 구조

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

카탈로그 정의 예제

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

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 이미지를 중앙에서 관리하는 데 사용한다.

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

공식 카탈로그 사용

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

정리

• Image Catalog는 “major → image” 매핑을 Cluster에서 분리해 이미지 수명주기를 중앙 관리
• ImageCatalog는 namespace 한정, ClusterImageCatalog는 클러스터 전역
• Cluster는 imageCatalogRef 로 major만 가리키고, 카탈로그 이미지 변경은 자동 rollout으로 전파
• major 값 변경이 major 업그레이드를 대신하지는 않는다 — 이미지 선택과 업그레이드 절차는 별개

다음 절(3.3)에서는 Operator 자체의 동작을 바꾸는 Operator 설정을 본다.