Image Volume Extensions

CloudNativePGは、 Kubernetes `ImageVolume feature <https://kubernetes.io/docs/tasks/configure-pod-container/image-volumes/>`_ を使用して、ポッドの起動時にCluster への PostgreSQL拡張機能の動的ロード をサポートします

そして、このプロジェクトが貢献したPostgreSQL 18で導入されたextension_control_path GUC。

この機能を使用すると、OCI準拠のコンテナイメージとしてパッケージされた PostgreSQL extension を、既知のファイルシステムパスの実行中のポッド内の読み取り専用で不変ボリュームとしてマウントできます。

拡張機能で、サーバー起動時に1つ以上の共有ライブラリをプリロードする必要がある場合、 shared_preload_libraries を介して追加できます。また、拡張機能をCREATE EXTENSION コマンドを介してデータベースレベルで作成する必要がある場合、 アプリケーションデータベースの構成

PostgreSQLデータベース内での一貫した自動拡張機能セットアップを保証します。

メリット

イメージボリューム拡張機能は、拡張機能のディストリビューションからPostgreSQLオペランドコンテナイメージのディストリビューションを分離します。これにより、PostgreSQLイメージ内のビルド時に拡張機能を定義して埋め込む必要がなくなります。これは、セキュリティとサプライチェーンの観点からなど、コンテナ化されたワークロードとしてのPostgreSQLの主な採用のブロッカーです。

その結果、次のことができます。

• official PostgreSQL `minimal operand images <https://github.com/cloudnative-pg/postgres-containers?tab=readme-ov-file#minimal-images>`_ を使用します

CloudNativePGによって提供されます。

• カスタムPostgreSQLイメージをリビルドまたはメンテナンスせずに、必要な拡張機能をCluster 定義に動的に追加します。

• 不変の最小限のセキュアベースイメージを使用し、各ワークロードに必要な拡張機能のみを追加することにより、操作面を削減します。

拡張イメージは、 画像の仕様 に従ってビルドする必要があります。

要件

CloudNativePGでイメージボリューム拡張を使用するには、以下が必要です。

• PostgreSQL 18以降 、extension_control_path のサポート。

• Kubernetes 1.33 、ImageVolume 機能ゲートが有効になっています。

• ``ImageVolume`` サポートを備えたコンテナランタイム

  • containerd v2.1.0以降、or

  • CRI-O v1.31以降。

• CloudNativePG互換の拡張コンテナイメージ 、以下を保証します。

  • Cluster リソースのPostgreSQLメジャーバージョンと一致します。

  • Cluster リソースの互換性のあるオペレーティングシステムディストリビューション。

  • Cluster リソースのCPUアーキテクチャと一致します。

その仕組み

拡張機能イメージは、Cluster リソースの.spec.postgresql.extensions スタンザで定義され、PostgreSQLクラスターに追加する拡張機能の順序付けリストを受け入れます。

注釈

フィールドレベルの詳細については、 API reference for `ExtensionConfiguration <API Reference>` を参照してください。

各イメージボリュームは/extensions/<EXTENSION_NAME> にマウントされます。

デフォルトでは、CloudNativePGは関連するGUCを自動的に管理し、次の設定を行います。

• extension_control_path 〜/extensions/<EXTENSION_NAME>/share 、 PostgreSQLが/extensions/<EXTENSION_NAME>/share/extension 内の拡張制御ファイルを見つけられるようにします

• dynamic_library_path 〜/extensions/<EXTENSION_NAME>/lib

これらの値は、拡張機能がextensions リストで定義された順序で追加され、PostgreSQL内の決定論的なパスの解決が保証されます。これにより、PostgreSQLは、ポッド内の手動構成を必要とせずに拡張機能を検出してロードできます。

注釈

拡張機能コンテナイメージの構築方法とそのレイアウトによっては、イメージ構造と一致するようにデフォルトの`extension_control_path` および`dynamic_library_path` 値を調整する必要がある場合があります。

注釈

拡張機能イメージに共有ライブラリが含まれる場合、クラスターで使用されるPostgreSQLコンテナイメージと同じPostgreSQLメジャーバージョン、オペレーティングシステムディストリビューション、およびCPUアーキテクチャでコンパイルして、互換性を保証し、ランタイムの問題を防ぐ必要があります。

新しい拡張機能を追加する方法

CloudNativePGのデータベースに拡張機能を追加するには、いくつかの手順を含みます。

1. PostgreSQLが検出してロードできるように、Cluster リソースに拡張イメージを定義します。

2. ライブラリを shared_preload_libraries に追加する

拡張機能で必要な場合。

3. 拡張機能がCREATE EXTENSION をサポートしている場合、インストールするDatabase リソースで拡張機能を宣言します。

警告

拡張機能イメージとPostgreSQL構成設定 shared_preload_libraries などを同時に変更することは避けてください。最初に、新しい拡張機能イメージでポッドをロールアウトし、PostgreSQL構成を更新します。この制限は、CloudNativePGの将来のリリースで解決される予定です。

説明のために、このガイドでは、 CREATE EXTENSION をサポートするfoo という名前の単純な架空の拡張機能を使用します。

新しい拡張機能のCluster リソースへの追加

.spec.postgresql.extensions スタンザを使用して、ImageVolume ベースの拡張機能をCluster に追加できます。例

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: foo-18
spec:
  # ...
  postgresql:
    extensions:
      - name: foo
        image:
          reference: # registry path for your extension image
  # ...

name フィールドは 必須 で、マウントパスこの例では/extensions/foo を決定するため、 クラスター内で一意である必要があります 。 小文字の英数字またはハイフン``-`` で構成され、英数字で開始および終了する必要があります。

image スタンザは Kubernetes `ImageVolume API <https://kubernetes.io/docs/tasks/configure-pod-container/image-volumes/>`_ の後にあります。 reference は、拡張機能イメージの有効なコンテナレジストリパスを指している必要があります。

注釈

新しい拡張機能が実行中の`Cluster` に追加されると、CloudNativePGは自動的に Rolling updates をトリガーして、新しいイメージボリュームを各ポッドにアタッチします。実稼働環境に新しい拡張機能を追加する前に、ステージング環境で完全にテストして、PostgreSQLクラスターを異常な状態にする可能性のある構成の問題を防止してください。

マウントされると、CloudNativePGは以下を追加することによりPostgreSQLを自動的に構成します。

• /extensions/foo/share 〜extension_control_path

• /extensions/foo/lib 〜dynamic_library_path

これにより、次のセクションで説明するように、PostgreSQLコンテナがデータベースから要求されたときにfoo 拡張機能を提供できる準備が保証されます。 CREATE EXTENSION foo コマンドは、 reconciliation of the `Database resource <PostgreSQL Database management>` 中に自動的にトリガーされ、PostgreSQLが次の場所を見つけるため、追加の構成なしで機能します。

• /extensions/foo/share/extension/foo.control の拡張制御ファイル

• /extensions/foo/lib/foo.so の共有ライブラリ

新しい拡張機能のDatabase リソースへの追加

PostgreSQLインスタンスで拡張機能が利用できるようになると、宣言的データベースを活用して manage the lifecycle of your extensions ことができます

ターゲットデータベース内で。

foo の例で続けると、次のリソース定義を使用して、foo-18 クラスターのapp データベースへのfoo 拡張機能のインストールを要求できます。

apiVersion: postgresql.cnpg.io/v1
kind: Database
metadata:
  name: foo-app
spec:
  name: app
  owner: app
  cluster:
    name: foo-18
  extensions:
    - name: foo
      version: 1.0

CloudNativePGは、このリソースを自動的にリコンサイルし、app データベース内でCREATE EXTENSION foo コマンドがまだインストールされていない場合は実行し、手動介入なしで目的の状態が維持されるようにします。

高度なトピック

場合によっては、特に次の場合、デフォルトの予想される構造では拡張機能イメージには不十分である可能性があります。

• 拡張機能には追加のシステムライブラリが必要です。

• 複数の拡張機能が同じイメージにバンドルされています。

• イメージはカスタムディレクトリ構造を使用します。

「構成よりコンベンション」 パラダイムに従って、CloudNativePGでは、次のフィールドを介して各拡張機能イメージの構成を細かく制御できます。

• extension_control_path PostgreSQLのextension_control_path に追加されるコンテナイメージ内の相対パスのリスト、拡張子制御ファイルを見つけられるようにします。

• dynamic_library_path PostgreSQLのdynamic_library_path に追加されるコンテナイメージ内の相対パスのリスト、拡張機能の共有ライブラリファイルを見つけられるようにします。

• ld_library_path インスタンスマネージャープロセスのLD_LIBRARY_PATH 環境変数に追加されるコンテナイメージ内の相対パスのリスト。これにより、PostgreSQLは実行時に必要なシステムライブラリを見つけられます。

この柔軟性により、明瞭性と予測可能性を維持しながら、複雑なまたは非標準の拡張画像をサポートできます。

カスタムパスの設定

拡張イメージがライブラリと制御ファイルにデフォルトのlib およびshare ディレクトリを使用しない場合、 extension_control_path およびdynamic_library_path を明示的に設定することによりデフォルトをオーバーライドできます。

例

spec:
  postgresql:
    extensions:
      - name: my-extension
        extension_control_path:
          - my/share/path
        dynamic_library_path:
          - my/lib/path
        image:
          reference: # registry path for your extension image

CloudNativePGは以下を使用してPostgreSQLを構成します。

• extension_control_path に/extensions/my-extension/my/share/path を追加

• dynamic_library_path に/extensions/my-extension/my/lib/path を追加

これにより、PostgreSQLは、標準以外のレイアウトでも、拡張機能の制御ファイルと共有ライブラリを正しく検出できます。

マルチ拡張子画像

同じコンテナイメージ内に複数の拡張機能を含め、各拡張機能のファイルが独自のサブディレクトリに存在する構造を採用する必要がある場合があります。

たとえば、 PostGISとpgRoutingを単一のイメージに、それぞれが独自のサブディレクトリにパッケージ化するには。

##  ...

spec:
  # ...
  postgresql:
    extensions:
      - name: geospatial
        extension_control_path:
          - postgis/share
          - pgrouting/share
        dynamic_library_path:
          - postgis/lib
          - pgrouting/lib
        # ...
        image:
          reference: # registry path for your geospatial image
      # ...
    # ...
  # ...

システムライブラリを含める

PostGISなどの一部の拡張機能は、ベースのPostgreSQLイメージに存在しない場合があるシステムライブラリを必要とします。これらの要件をサポートするには、拡張機能コンテナイメージ内に必要なライブラリをパッケージし、 ld_library_path フィールドを使用してPostgreSQLで利用できるようにします。

たとえば、拡張機能イメージに、必要なライブラリを含むsystem ディレクトリが含まれる場合

##  ...

spec:
  # ...
  postgresql:
    extensions:
      - name: postgis
        # ...
        ld_library_path:
          - system
        image:
          reference: # registry path for your PostGIS image
      # ...
    # ...
  # ...

CloudNativePGは、 /extensions/postgis/system を含むようにLD_LIBRARY_PATH 環境変数を設定し、PostgreSQLが実行時にこれらのシステムライブラリを見つけてロードできるようにします。

注釈

PostgreSQLプロセスの開始時に`ld_library_path` を設定する必要があるため、この値を変更するには、**クラスターの再起動**して新しい値を有効にする必要があります。 CloudNativePGは現在、この再起動を自動的にトリガーしません。 ld_library_path を変更した後、クラスターを手動で再起動する必要がありますたとえば、cnpg restart を使用して

画像の仕様

CloudNativePGの標準の拡張コンテナイメージには、ルートに2つの必須ディレクトリが含まれます。

• /share/ 拡張制御ファイルたとえば <EXTENSION>.control および対応するSQLファイルを含むextension サブディレクトリが含まれています。

• /lib/ 拡張機能の共有ライブラリたとえば <EXTENSION>.so およびその他の必要なライブラリが含まれています。

この構造に従うと、手動構成を必要とせずに、CloudNativePG内のPostgreSQLで拡張機能が自動的に検出可能で使用できるようになります。

注釈

PostgreSQL拡張機能開発者は、アーティファクト配布の一部としてこのレイアウトに従ってOCI準拠の拡張機能イメージを公開し、Kubernetes環境内で拡張機能を簡単に使用できるようにすることをお勧めします。理想的には、拡張機能イメージは特定のオペレーティングシステムディストリビューションとアーキテクチャをターゲットとし、特定のPostgreSQLバージョンに関連付けられ、ディストリビューションのネイティブパッケージシステムたとえばDebianまたはRPMパッケージを使用してビルドする必要があります。このアプローチでは、クラスターで使用されるPostgreSQLイメージとの一貫性、セキュリティ、および互換性が保証されます。

注意事項

現在、拡張機能イメージを追加、削除、または更新すると、PostgreSQLポッドの再起動がトリガーされます。この動作は、 image volumes 方法から継承されます

Kubernetesでの作業。

拡張機能の更新を実行する前に、次のことを確認します。

• ステージング環境で更新プロセスを徹底的にテストしました。

• 拡張イメージには、現在インストールされているバージョンとターゲットバージョン間の必要なアップグレードパスが含まれていることを確認しました。

• 関連するDatabase リソース定義の拡張機能のversion フィールドを更新して、イメージの新しいバージョンに合わせて調整します。

これらの手順は、拡張機能の更新中にPostgreSQLクラスターでのダウンタイムまたはデータの不一貫性を防ぐのに役立ちます。