이미지 카탈로그

이미지 카탈로그 (Image Catalog)

ImageCatalog와 ClusterImageCatalog는 PostgreSQL 이미지 수명 주기를 Cluster 정의에서 분리할 수 있게 해주는 CRD(Custom Resource Definition)예요. 카탈로그를 사용하면 이미지 업데이트를 중앙에서 관리할 수 있어요. 카탈로그 항목이 업데이트되면, 관련된 모든 클러스터가 자동으로 새 이미지를 롤아웃해요.

커스텀 카탈로그를 만들 수도 있지만, CloudNativePG는 모든 공식 커뮤니티 PostgreSQL 컨테이너 이미지를 다루는 공식 카탈로그를 ClusterImageCatalog 리소스로 제공해요.

출처: 문서

본문

카탈로그 범위 (Catalog scoping)

두 리소스의 주요 차이는 범위예요:

리소스	범위	최적 사용 사례
ImageCatalog	네임스페이스 범위	애플리케이션별 버전 또는 팀 레벨 제한
ClusterImageCatalog	클러스터 전역	조직의 모든 네임스페이스에 걸친 전역 표준

카탈로그 구조 (Catalog structure)

두 리소스 모두 공통 스키마를 공유해요:

• 메이저 버전 관리: major PostgreSQL 버전으로 키가 지정된 이미지 목록
• 고유성: major 필드는 단일 카탈로그 내에서 고유해야 해요
• 확장(extensions): 인증된 확장 컨테이너 이미지 지원 (extension_control_path를 통한 PostgreSQL 18+에서 사용 가능)
• 컴포넌트 이미지: PgBouncer 같은 비-PostgreSQL 컴포넌트를 위한 명명된 이미지의 선택적 목록 (컴포넌트 이미지 참조)

:::warning 연산자는 이미지 감지 없이 사용자 정의 major 버전을 신뢰하지만, 공식 CloudNativePG 카탈로그는 커뮤니티가 사전 검증해서 모든 확장·operand 이미지 항목이 선언된 major 버전과 올바르게 일치하도록 보장해요. 커스텀 카탈로그를 만들고 있다면, 선언된 major 버전이 실제 PostgreSQL 이미지와 일치하도록 보장해 호환성을 유지해야 해요. :::

컴포넌트 이미지 (Component images)

PostgreSQL 이미지 외에도, 카탈로그는 componentImages 필드를 통해 다른 컴포넌트의 이미지를 저장할 수 있어요. 각 항목은 문자열 **키(key)**로 식별되는데, 이는 소문자 영숫자 식별자(하이픈 허용, 1~63자)이며 카탈로그 내에서 고유해야 해요.

현재 컴포넌트 이미지의 유일한 소비자는 Pooler 리소스예요. 이 리소스는 컴포넌트 이미지 항목을 참조해 PgBouncer 컨테이너 이미지를 중앙에서 관리할 수 있어요 (이미지 카탈로그 사용 참조).

다음 예시는 PgBouncer 컴포넌트 이미지가 있는 네임스페이스 범위 ImageCatalog를 정의해요:

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

클러스터 전역 카탈로그에는 kind: ClusterImageCatalog를 사용하고 metadata.namespace 필드를 빼면 돼요 (spec은 그 외 동일해요).

:::info 카탈로그는 최대 32개의 컴포넌트 이미지 항목을 포함할 수 있어요. 키는 소문자 영숫자 문자 또는 하이픈이며, 영숫자 문자로 시작·끝나고 길이는 최대 63자예요. :::

구성 예시 (Configuration examples)

카탈로그 정의

단일 카탈로그 안에 여러 메이저 버전을 정의할 수 있어요.

다음 예시는 네임스페이스 범위 ImageCatalog를 정의해요:

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

클러스터에서 카탈로그 참조

Cluster 리소스는 imageCatalogRef를 사용해 자신의 이미지를 선택해요:

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

이미지 볼륨 확장이 있는 이미지 카탈로그 (Image Catalog with Image Volume Extensions)

이미지 볼륨 확장(Image Volume Extensions)을 사용하면 확장용 컨테이너를 카탈로그 항목 안에 직접 번들할 수 있어요:

apiVersion: postgresql.cnpg.io/v1
kind: ImageCatalog
metadata:
  name: postgresql
spec:
  images:
    - major: 18
      image: ghcr.io/cloudnative-pg/postgresql:18.6-minimal-trixie
      extensions:
        - name: foo
          image:
            reference: # registry path for your `foo` extension image

extensions 섹션은 ExtensionConfiguration API 스키마와 구조를 따라요. 이미지 카탈로그를 참조하는 클러스터는 관련 확장 중 어느 것이든 이름으로 로드할 수 있어요.

:::info 내부 이미지 구조, 구성 옵션, 클러스터 내에서 카탈로그 확장을 선택·오버라이드하는 방법에 대한 자세한 내용은 이미지 볼륨 확장 문서를 참조하세요. :::

CloudNativePG 카탈로그 (CloudNativePG Catalogs)

CloudNativePG 프로젝트는 모든 지원 이미지에 대한 ClusterImageCatalog 매니페스트를 유지 관리해요.

이 카탈로그들은 artifacts 저장소 안의 두 개의 별도 위치에 주기적으로 갱신·발행돼요:

• image-catalogs: 기본 이미지 유형에 대한 핵심 카탈로그 정의
• image-catalogs-extensions: 위 카탈로그와 동일하지만, minimal 이미지 유형에 확장 정의가 포함된다는 점이 핵심 차이

각 카탈로그는 이미지 유형과 Debian 릴리스(예: trixie)의 특정 조합에 해당해요. 카탈로그는 지원되는 모든 PostgreSQL 메이저 버전에 대한 가장 최신 컨테이너 이미지를 나열해요.

:::important 최대 보안과 불변성을 보장하기 위해, 공식 CloudNativePG 카탈로그의 모든 이미지는 태그가 아니라 SHA256 다이제스트로 식별돼요. :::

버전 호환성 (Version Compatibility)

핵심 카탈로그는 이전 버전의 연산자에서도 동작하지만, extensions 섹션을 포함하는 카탈로그는 CloudNativePG 1.29 이상에서만 호환돼요. 확장 정의가 있는 카탈로그를 이전 연산자에서 사용하면 그 정의가 거부돼요.

설치와 사용 (Installation and Usage)

이 카탈로그들을 설치하면, 클러스터 관리자는 PostgreSQL 클러스터가 선택한 Debian 배포판과 이미지 유형의 특정 PostgreSQL 메이저 버전 내에서 최신 패치 릴리스로 자동 업데이트되도록 보장할 수 있어요.

예를 들어, Debian trixie의 minimal PostgreSQL 컨테이너 이미지용 최신 카탈로그를 설치하려면 다음을 실행하세요:

kubectl apply -f \
  https://raw.githubusercontent.com/cloudnative-pg/artifacts/refs/heads/main/image-catalogs/catalog-minimal-trixie.yaml

image-catalogs 디렉터리에 있는 kustomization 파일을 사용해 모든 사용 가능한 카탈로그를 설치할 수 있어요:

kubectl apply -k 'https://github.com/cloudnative-pg/artifacts//image-catalogs?ref=main'

그런 다음 배포된 모든 카탈로그를 다음으로 볼 수 있어요:

kubectl get clusterimagecatalogs.postgresql.cnpg.io

예시: 클러스터에서 카탈로그 사용

trixie에서 PostgreSQL 18의 최신 minimal 이미지를 항상 추적하는 클러스터를 만들려면 Cluster를 다음과 같이 정의하세요:

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

더 알아보기 (Learn more)

• 롤링 업데이트 (rolling_update)
• 이미지 볼륨 확장 (imagevolume_extensions)
• 연결 풀링 (connection_pooling)