Image Volume Extensions ======================= .. raw:: html CloudNativePGは、 `Kubernetes `ImageVolume` feature `_ を使用して、ポッドの起動時に\ ``Cluster`` への **PostgreSQL拡張機能の動的ロード** をサポートします そして、このプロジェクトが貢献したPostgreSQL 18で導入された\ ``extension_control_path`` GUC。 この機能を使用すると、OCI準拠のコンテナイメージとしてパッケージされた `PostgreSQL extension `_ を、既知のファイルシステムパスの実行中のポッド内の読み取り専用で不変ボリュームとしてマウントできます。 拡張機能で、サーバー起動時に1つ以上の共有ライブラリをプリロードする必要がある場合、 :ref:`shared_preload_libraries ` を介して追加できます。また、拡張機能を\ ``CREATE EXTENSION`` コマンドを介してデータベースレベルで作成する必要がある場合、 :ref:`アプリケーションデータベースの構成 <アプリケーションデータベースの構成>` PostgreSQLデータベース内での一貫した自動拡張機能セットアップを保証します。 メリット -------- イメージボリューム拡張機能は、拡張機能のディストリビューションからPostgreSQLオペランドコンテナイメージのディストリビューションを分離します。これにより、PostgreSQLイメージ内のビルド時に拡張機能を定義して埋め込む必要がなくなります。これは、セキュリティとサプライチェーンの観点からなど、コンテナ化されたワークロードとしてのPostgreSQLの主な採用のブロッカーです。 その結果、次のことができます。 - `official PostgreSQL `minimal` operand images `_ を使用します CloudNativePGによって提供されます。 - カスタムPostgreSQLイメージをリビルドまたはメンテナンスせずに、必要な拡張機能を\ ``Cluster`` 定義に動的に追加します。 - 不変の最小限のセキュアベースイメージを使用し、各ワークロードに必要な拡張機能のみを追加することにより、操作面を削減します。 拡張イメージは、 :ref:`画像の仕様 <画像の仕様>` に従ってビルドする必要があります。 要件 ---- 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クラスターに追加する拡張機能の順序付けリストを受け入れます。 .. Note:: フィールドレベルの詳細については、 :ref:`API reference for `ExtensionConfiguration` ` を参照してください。 　 各イメージボリュームは\ ``/extensions/`` にマウントされます。 デフォルトでは、CloudNativePGは関連するGUCを自動的に管理し、次の設定を行います。 - ``extension_control_path`` 〜\ ``/extensions//share`` 、 PostgreSQLが\ ``/extensions//share/extension`` 内の拡張制御ファイルを見つけられるようにします - ``dynamic_library_path`` 〜\ ``/extensions//lib`` これらの値は、拡張機能が\ ``extensions`` リストで定義された順序で追加され、PostgreSQL内の決定論的なパスの解決が保証されます。これにより、PostgreSQLは、ポッド内の手動構成を必要とせずに拡張機能を検出してロードできます。 .. Note:: 拡張機能コンテナイメージの構築方法とそのレイアウトによっては、イメージ構造と一致するようにデフォルトの`extension_control_path` および`dynamic_library_path` 値を調整する必要がある場合があります。 　 .. Note:: 拡張機能イメージに共有ライブラリが含まれる場合、クラスターで使用されるPostgreSQLコンテナイメージと同じPostgreSQLメジャーバージョン、オペレーティングシステムディストリビューション、およびCPUアーキテクチャでコンパイルして、互換性を保証し、ランタイムの問題を防ぐ必要があります。 新しい拡張機能を追加する方法 ---------------------------- CloudNativePGのデータベースに拡張機能を追加するには、いくつかの手順を含みます。 1. PostgreSQLが検出してロードできるように、\ ``Cluster`` リソースに拡張イメージを定義します。 2. ライブラリを :ref:`shared_preload_libraries ` に追加する 拡張機能で必要な場合。 3. 拡張機能が\ ``CREATE EXTENSION`` をサポートしている場合、インストールする\ ``Database`` リソースで拡張機能を宣言します。 .. Warning:: 拡張機能イメージとPostgreSQL構成設定 `shared_preload_libraries` などを同時に変更することは避けてください。最初に、新しい拡張機能イメージでポッドをロールアウトし、PostgreSQL構成を更新します。この制限は、CloudNativePGの将来のリリースで解決される予定です。 　 説明のために、このガイドでは、 ``CREATE EXTENSION`` をサポートする\ ``foo`` という名前の単純な架空の拡張機能を使用します。 新しい拡張機能の\ ``Cluster`` リソースへの追加 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``.spec.postgresql.extensions`` スタンザを使用して、\ ``ImageVolume`` ベースの拡張機能を\ ``Cluster`` に追加できます。例 .. code:: yaml 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 `_ の後にあります。 ``reference`` は、拡張機能イメージの有効なコンテナレジストリパスを指している必要があります。 .. Note:: 新しい拡張機能が実行中の`Cluster` に追加されると、CloudNativePGは自動的に :ref:`Rolling updates ` をトリガーして、新しいイメージボリュームを各ポッドにアタッチします。実稼働環境に新しい拡張機能を追加する前に、ステージング環境で完全にテストして、PostgreSQLクラスターを異常な状態にする可能性のある構成の問題を防止してください。 　 マウントされると、CloudNativePGは以下を追加することによりPostgreSQLを自動的に構成します。 - ``/extensions/foo/share`` 〜\ ``extension_control_path`` - ``/extensions/foo/lib`` 〜\ ``dynamic_library_path`` これにより、次のセクションで説明するように、PostgreSQLコンテナがデータベースから要求されたときに\ ``foo`` 拡張機能を提供できる準備が保証されます。 ``CREATE EXTENSION foo`` コマンドは、 :ref:`reconciliation of the `Database` resource ` 中に自動的にトリガーされ、PostgreSQLが次の場所を見つけるため、追加の構成なしで機能します。 - ``/extensions/foo/share/extension/foo.control`` の拡張制御ファイル - ``/extensions/foo/lib/foo.so`` の共有ライブラリ 新しい拡張機能の\ ``Database`` リソースへの追加 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PostgreSQLインスタンスで拡張機能が利用できるようになると、宣言的データベースを活用して :ref:`manage the lifecycle of your extensions ` ことができます ターゲットデータベース内で。 ``foo`` の例で続けると、次のリソース定義を使用して、\ ``foo-18`` クラスターの\ ``app`` データベースへの\ ``foo`` 拡張機能のインストールを要求できます。 .. code:: yaml 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`` を明示的に設定することによりデフォルトをオーバーライドできます。 例 .. code:: yaml 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を単一のイメージに、それぞれが独自のサブディレクトリにパッケージ化するには。 .. code:: yaml ## ... 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`` ディレクトリが含まれる場合 .. code:: yaml ## ... 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が実行時にこれらのシステムライブラリを見つけてロードできるようにします。 .. Note:: PostgreSQLプロセスの開始時に`ld_library_path` を設定する必要があるため、この値を変更するには、**クラスターの再起動**して新しい値を有効にする必要があります。 CloudNativePGは現在、この再起動を自動的にトリガーしません。 `ld_library_path` を変更した後、クラスターを手動で再起動する必要がありますたとえば、`cnpg restart` を使用して 　 画像の仕様 ---------- CloudNativePGの標準の拡張コンテナイメージには、ルートに2つの必須ディレクトリが含まれます。 - ``/share/`` 拡張制御ファイルたとえば ``.control`` および対応するSQLファイルを含む\ ``extension`` サブディレクトリが含まれています。 - ``/lib/`` 拡張機能の共有ライブラリたとえば ``.so`` およびその他の必要なライブラリが含まれています。 この構造に従うと、手動構成を必要とせずに、CloudNativePG内のPostgreSQLで拡張機能が自動的に検出可能で使用できるようになります。 .. Note:: PostgreSQL拡張機能開発者は、アーティファクト配布の一部としてこのレイアウトに従ってOCI準拠の拡張機能イメージを公開し、Kubernetes環境内で拡張機能を簡単に使用できるようにすることをお勧めします。理想的には、拡張機能イメージは特定のオペレーティングシステムディストリビューションとアーキテクチャをターゲットとし、特定のPostgreSQLバージョンに関連付けられ、ディストリビューションのネイティブパッケージシステムたとえばDebianまたはRPMパッケージを使用してビルドする必要があります。このアプローチでは、クラスターで使用されるPostgreSQLイメージとの一貫性、セキュリティ、および互換性が保証されます。 注意事項 -------- 現在、拡張機能イメージを追加、削除、または更新すると、PostgreSQLポッドの再起動がトリガーされます。この動作は、 `image volumes `_ 方法から継承されます Kubernetesでの作業。 拡張機能の更新を実行する前に、次のことを確認します。 - ステージング環境で更新プロセスを徹底的にテストしました。 - 拡張イメージには、現在インストールされているバージョンとターゲットバージョン間の必要なアップグレードパスが含まれていることを確認しました。 - 関連する\ ``Database`` リソース定義の拡張機能の\ ``version`` フィールドを更新して、イメージの新しいバージョンに合わせて調整します。 これらの手順は、拡張機能の更新中にPostgreSQLクラスターでのダウンタイムまたはデータの不一貫性を防ぐのに役立ちます。