Image Catalog
=============

.. raw:: html

   <!-- SPDX-License-Identifier: CC-BY-4.0 -->

``ImageCatalog`` および\ ``ClusterImageCatalog`` は、
PostgreSQLイメージのライフサイクルを\ ``Cluster``
定義から分離できるカスタムリソース定義CRDです。カタログを使用することにより、イメージの更新を一元管理できます。カタログエントリが更新されると、関連するすべてのクラスターが自動的に
:ref:`roll out the new image <Rolling updates>`  。

カスタムカタログをビルドすることはできますが、CloudNativePGは\ ``ClusterImageCatalog``
リソースとして :ref:`CloudNativePGカタログ <CloudNativePGカタログ>` を提供し、すべての公式コミュニティPostgreSQLコンテナイメージをカバーします。

カタログのスコーピング
----------------------

2つのリソースの主な違いは、そのスコープです。

.. csv-table::
  :header: Resource,Scope,Best use case
  :widths: 12,15,20
  :align: left
  :class: longtable

  `ImageCatalog`,Namespaced,Application-specific versions or team-level restrictions.
  `ClusterImageCatalog`,Cluster-wide,Global standards across all namespaces for an organization.

カタログ構造
------------

両方のリソースは、共通のスキーマを共有します。

- **メジャーバージョン** ``major``
  PostgreSQLバージョンによってキー付けられたイメージのリスト。

- **一意性** ``major``
  フィールドは、単一のカタログ内で一意である必要があります。

- **拡張機能**
  認定された拡張機能コンテナイメージのサポート\ ``extension_control_path``
  経由でPostgreSQL 18+で利用可能。

..  Warning::
   オペレーターは画像検出を実行せずにユーザー定義の`major` バージョンを信頼しますが、公式CloudNativePGカタログはコミュニティによって事前検証され、すべての拡張機能とオペランドのイメージエントリが宣言されたメジャーバージョンと正しく一致することを確認します。カスタムカタログを作成する場合は、宣言されたメジャーバージョンが実際のPostgreSQLイメージと一致することを確認して、互換性を維持する必要があります。

構成例
------

カタログの定義
^^^^^^^^^^^^^^

単一のカタログ内で複数のメジャーバージョンを定義できます。

次の例では、名前空間\ ``ImageCatalog`` を定義します。

.. code:: yaml

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

次の例は、クラスター全体の\ ``ClusterImageCatalog`` を定義します。

.. code:: yaml

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

クラスター内のカタログの参照
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``Cluster`` リソースは、 ``imageCatalogRef``
を使用して画像を選択します。

.. code:: yaml

   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

イメージボリューム拡張を使用したイメージカタログ
------------------------------------------------

:ref:`イメージボリューム拡張を使用したイメージカタログ <イメージボリューム拡張を使用したイメージカタログ>` では、カタログエントリー内で直接拡張機能のコンテナをバンドルできます。

.. code:: yaml

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

``extensions`` セクションは :ref:`ExtensionConfiguration <ExtensionConfiguration>` の後です

APIスキーマと構造。イメージカタログを参照するクラスターは、関連する拡張機能を名前でロードできます。

..  Note::
   :ref:`documentation of image volume extensions <Image Volume Extensions>` を参照してください。

内部イメージ構造、構成オプション、およびクラスター内のカタログ拡張機能を選択またはオーバーライドする方法の詳細については、

CloudNativePGカタログ
---------------------

CloudNativePGプロジェクトは、サポートされているすべてのイメージの\ ``ClusterImageCatalog``
マニフェストを維持します。

これらのカタログは定期的に更新され、 `artifacts repository <https://github.com/cloudnative-pg/artifacts/tree/main/image-catalogs>`_  で公開されます。

各カタログは、イメージタイプ\ ``minimal``
などとDebianリリース\ ``trixie``
などの特定の組み合わせに対応しています。サポートされているすべてのPostgreSQLメジャーバージョンの最新のコンテナイメージをリストしています。

..  Important::
   最大限のセキュリティと不変性を保証するために、公式CloudNativePGカタログ内のすべての画像は、単なるタグではなく**SHA256ダイジェスト**によって識別されます。

バージョンの互換性
^^^^^^^^^^^^^^^^^^

標準カタログはオペレーターの古いバージョンで動作しますが、
**``extensions`` セクションを含むカタログはCloudNativePG 1.29以降**
とのみ互換性があります。古いオペレーターの拡張定義を含むカタログを使用すると、これらの定義が拒否されます。

インストールと使用
^^^^^^^^^^^^^^^^^^

これらのカタログをインストールすることにより、クラスター管理者は、PostgreSQLクラスターが、選択したDebianディストリビューションとイメージタイプの特定のPostgreSQLメジャーバージョン内の最新のパッチリリースに自動的に更新されることを確認できます。

たとえば、\ ``minimal``
PostgreSQLコンテナイメージの最新のカタログをDebian ``trixie``
にインストールするには、次のコマンドを実行します。

.. code:: shell

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

``image-catalogs`` ディレクトリにある\ ``kustomization``
ファイルを使用して、使用可能なすべてのカタログをインストールできます。

.. code:: shell

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

次に、次の方法で展開されたすべてのカタログを表示できます。

.. code:: shell

   kubectl get clusterimagecatalogs.postgresql.cnpg.io

例 クラスターでのカタログの使用
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``trixie`` 上のPostgreSQL 18の最新の\ ``minimal``
イメージを常に追跡するクラスターを作成するには、次のように\ ``Cluster``
を定義します。

.. code:: yaml

   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