Image Volume Extensions ======================= .. raw:: html CloudNativePGは、 `Kubernetes `ImageVolume` feature `_ を使用して、ポッドの起動時に\ ``Cluster`` への **PostgreSQL拡張機能の動的ロード** をサポートします PostgreSQL 18で導入された\ ``extension_control_path`` GUCとともに、CloudNativePGプロジェクトが貢献した機能。 この機能を使用すると、OCI準拠のコンテナイメージとしてパッケージされた `PostgreSQL extension `_ を、実行中のポッド内の指定されたファイルシステムパスに読み取り専用で不変のボリュームとしてマウントできます。 ``CREATE EXTENSION`` コマンドを介してデータベースレベルのインストールが必要な拡張機能の場合、 :ref:`アプリケーションデータベースの構成 <アプリケーションデータベースの構成>` すべてのPostgreSQLデータベースで一貫した自動セットアップを保証します。 公式拡張機能のイメージとカタログ -------------------------------- CloudNativePGコミュニティは、 `pgvector `_ を含む拡張コンテナイメージスイートを維持しています および `postgres-extensions-containers `_ の一部としての `PostGIS `_ 。これらのイメージは、 `official PostgreSQL `minimal` images `_ の上にビルドされます。 .. Note:: このドキュメントは、サードパーティが独自のイメージとカタログをビルドするために必要な技術仕様を提供しますが、次の手順では、公式の拡張機能イメージとカタログの展開と使用に特に焦点を当てています。 メリット -------- この機能は、 PostgreSQLオペランドイメージから拡張機能のディストリビューションを分離することにより、コンテナでPostgreSQLを実行する際の重要な障壁を取り除きます。ビルド時に拡張機能を埋め込む必要がなくなり、公式の最小限のオペランドイメージを使用し、必要な拡張機能のみを\ ``Cluster`` 定義に直接または :ref:`Image Catalog ` を介して追加できます。 このアプローチでは、コアデータベースコンテナに操作に必要な重要なバイナリのみが含まれるようにすることにより、データベースクラスターの攻撃対象領域を大幅に削減します。不要な拡張機能、ライブラリ、およびビルド時の依存関係を除外することにより、エクスプロイトの潜在的なエントリーポイントを最小限に抑え、脆弱性管理を簡素化します。このアーキテクチャは、データワークロードの不変の最小限のベースイメージを維持することにより、サプライチェーンのセキュリティを強化し、運用オーバーヘッドを削減します。 .. Important:: 拡張イメージは、 :ref:`画像の仕様 <画像の仕様>` に従ってビルドする必要があります。 要件 ---- CloudNativePGでイメージボリューム拡張を使用するには、以下が必要です。 - **PostgreSQL 18以降** ``extension_control_path`` サポートに必要です。 - **Kubernetes 1.35以降** ``ImageVolume`` 機能はデフォルトで有効になっています。 Kubernetes 1.33および1.34のユーザーは、\ ``ImageVolume`` 機能ゲートを手動で有効にする必要があります。 - **``ImageVolume`` サポートを備えたコンテナランタイム** - ``containerd`` v2.1.0以降、or - ``CRI-O`` v1.31以降。 - **CloudNativePG互換の拡張コンテナイメージ** 、以下を保証します。 - ``Cluster`` リソースのPostgreSQLメジャーバージョンと一致します。 - ``Cluster`` リソースの互換性のあるオペレーティングシステムディストリビューション。 - ``Cluster`` リソースのCPUアーキテクチャと一致します。 その仕組み ---------- ``.spec.postgresql.extensions`` スタンザを使用して、拡張イメージを新しいまたは既存の\ ``Cluster`` リソースに追加できます。 .. Important:: 新しい拡張機能が実行中の`Cluster` に追加されると、CloudNativePGは自動的に :ref:`Rolling updates ` をトリガーして、新しいイメージボリュームを各ポッドにアタッチします。実稼働環境に新しい拡張機能を追加する前に、ステージング環境で完全にテストして、PostgreSQLクラスターを異常な状態にする可能性のある構成の問題を防止してください。 !!!注 フィールドレベルの詳細については、 :ref:`API reference for `ExtensionConfiguration` ` を参照してください。 構成ソースと優先順位 ^^^^^^^^^^^^^^^^^^^^ ``extensions`` スタンザは、エントリのリストを受け入れます。各エントリは、クラスター内で一意である必要がある\ ``name`` を必要とします。 .. Important:: `name` は、小文字の英数字、アンダースコア`_` またはハイフン`-` で構成され、英数字で開始および終了する必要があります。各エントリは、コンテナイメージの構成を定義し、PostgreSQLが拡張機能を見つけてロードするために必要なオプションを指定します。 - :ref:`**Via Image Catalog** <#via-an-image-catalog-recommended>` クラスターが、現在のPostgreSQLメジャーバージョンの拡張機能を定義する\ ``ImageCatalog`` を参照する場合、これらの定義はデフォルト構成として機能します。これにより、カタログは\ ``image.reference`` を一元管理できますが、クラスターは単に名前で拡張機能を有効にするだけです。 - :ref:`クラスター内に直接 <クラスター内に直接>` クラスターがイメージカタログを使用しない場合、\ ``image.reference`` フィールドは必須で、拡張機能イメージの有効なコンテナレジストリパスを明示的に指定する必要があります。 ``image`` スタンザは `Kubernetes `ImageVolume` API `_ の後にあります。 *「構成よりコンベンション」* パラダイムに従って、CloudNativePGは完全な柔軟性を提供します。\ ``image.reference`` を含むカタログから継承した値は、特定のローカル要件を満たすように\ ``Cluster`` 定義内で選択的にオーバーライドできます。 マウンティングとPostgreSQLの構成 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 各拡張機能は、ポッド内の\ ``/extensions/`` に読み取り専用ボリュームとしてマウントされます。 デフォルトでは、CloudNativePGは次の設定により、関連するGUCを自動的に管理します。 - ``extension_control_path`` 〜\ ``/extensions//share`` 、 PostgreSQLが\ ``/extensions//share/extension`` 内の拡張制御ファイルを見つけられるようにします - ``dynamic_library_path`` 〜\ ``/extensions//lib`` .. Note:: アンダースコアを含む拡張名たとえば`pg_ivm` は、RFC 1123 DNSラベル要件に準拠するようにKubernetesボリューム名にハイフンたとえば`pg-ivm` を使用するように変換されます。サニタイズ後に同じになる拡張名は使用しないでくださいたとえば、 `pg_ivm` と`pg-ivm` は両方とも`pg-ivm` にサニタイズします。 Webhook検証は、このような競合を防ぎます。これらの値は、拡張機能が`extensions` リストで定義された順序で追加され、PostgreSQL内の決定論的なパスの解決が保証されます。これにより、PostgreSQLは、ポッド内の手動構成を必要とせずに拡張機能を検出してロードできます。 カスタム画像レイアウトに一致するようにこれらのパスを手動で調整できますが、公式CloudNativePGカタログは、これらのオプションを各拡張機能の正しい値に事前構成し、すぐに機能することを保証します。 .. Important:: 拡張イメージに共有ライブラリが含まれる場合、オペランドイメージと同じPostgreSQLメジャーバージョン、オペレーティングシステムディストリビューション、およびCPUアーキテクチャ用にコンパイルする必要があります。公式のCloudNativePGカタログを使用すると、この互換性が自動的に保証されます。カタログは、クラスターの特定の環境と一致するように設計され、ライブラリまたはアーキテクチャの不一致によって発生するランタイムの問題を防ぎます。 データベースへのインストール ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :ref:`データベース内の拡張機能の管理 <データベース内の拡張機能の管理>` を活用できます 標準のPostgreSQL ``CREATE EXTENSION`` メカニズムをサポートする拡張機能の最終的なアクティブ化を自動化します。 拡張機能イメージがマウントされ、GUCが構成されると、拡張機能はPostgreSQLインスタンスで利用できるようになりますが、特定のデータベース内ではまだアクティブになっていません。インストールするには、 ``Database`` リソースを定義します。次の例では、 `official `postgres-extensions-containers` project `_ の実装標準に従って、 ``pgvector`` を使用します。 .. code:: yaml apiVersion: postgresql.cnpg.io/v1 kind: Database metadata: name: cluster-example-app spec: name: app owner: app cluster: name: cluster-example extensions: - name: vector version: "" CloudNativePGは、ターゲットデータベース内で\ ``CREATE EXTENSION IF NOT EXISTS vector`` を実行することにより、このリソースを自動的にリコンサイルします。これにより、目的の状態が維持され、すべてのインスタンスに一貫して適用されます。 .. Note:: モジュールと呼ばれることが多い一部のPostgreSQLコンポーネントは、 `CREATE EXTENSION` メカニズムを使用しません。これらは通常、サーバーの起動時に`shared_preload_libraries` を介してロードする必要がある共有ライブラリで構成されます。イメージカタログを使用してこれらのバイナリの配布を簡素化する場合でも、ライブラリ名を :ref:`shared_preload_libraries ` に手動で追加する必要があります ``Cluster`` 定義で変更して、メモリにロードされるようにします。 Postgresクラスターへの拡張機能の追加 ------------------------------------ 以前に予想されたように、CloudNativePGは、拡張機能イメージを定義する2つの方法を提供します。どちらもポッドレベルで同じ結果を達成しますが、一貫した運用準備が整ったサプライチェーンを維持するには、イメージカタログを使用することをお勧めします。 画像カタログ経由推奨 ^^^^^^^^^^^^^^^^^^^^ .. Note:: イメージカタログの拡張コンテナイメージのサポートは、CloudNativePG 1.29で導入されました。 :ref:`image catalog that covers extensions ` を使用する場合 :ref:`official ones ` のような コミュニティが提供するシステムでは、特定のコンテナイメージ\ ``reference`` や必要なファイルシステムパスなどの複雑な構成の詳細が一元管理されます。 ``Cluster`` 定義は、名前で拡張機能に「オプトイン」するだけでよいため、クリーンで宣言的なままです。オペレーターは、カタログの定義に基づいて、画像の解像度と必要なPostgreSQL設定を自動的に処理します。 カタログから\ ``pgvector`` のような拡張機能を有効にするには、次の抜粋のように、クラスターの\ ``extensions`` リストに追加します。 .. code:: yaml apiVersion: postgresql.cnpg.io/v1 kind: Cluster metadata: name: cluster-example spec: # ... imageCatalogRef: apiGroup: postgresql.cnpg.io kind: ClusterImageCatalog name: postgresql-minimal-trixie major: 18 postgresql: extensions: - name: pgvector # Resolves all details, including the image reference, from the catalog # ... この方法により、拡張イメージは、同じカタログエントリで定義されたPostgreSQLオペランドイメージと常に互換性があることが保証されます。 クラスター内に直接 ^^^^^^^^^^^^^^^^^^ .. Note:: `Cluster` リソースで拡張機能を直接定義するのがオリジナルの方法で、CloudNativePG 1.29より前のバージョンの唯一のオプションのままです。現在のカタログに存在しない拡張機能を使用する必要がある場合、またはカスタムイメージをテストする場合にも役立ちます。カタログを使用せずに`Cluster` リソース内で拡張機能を直接定義できます。この場合、イメージ`reference` を明示的に提供する必要があります。 次の例は、公式コンテナイメージを明示的に指定することにより\ ``pgvector`` を追加する方法を示しています。 .. code:: yaml apiVersion: postgresql.cnpg.io/v1 kind: Cluster metadata: name: cluster-example spec: # ... postgresql: extensions: - name: pgvector image: reference: ghcr.io/cloudnative-pg/pgvector: .. Tip:: `Cluster` で直接提供される構成が優先されることに注意してください。カタログを参照しているが、 `Cluster` スタンザでも同じ拡張名を定義している場合、 `Cluster` の設定がカタログの設定をオーバーライドします。 :ref:`ExtensionConfiguration ` のすべてのフィールド ``Cluster`` レベルでオーバーライドして、完全な柔軟性を提供できます。\ ``name`` フィールドは例外です。 !!!警告 ``name`` は一意の識別子として機能します。それを変更すると、カタログから既存の拡張機能エントリをオーバーライドするのではなく、新しい拡張機能エントリが定義されます。 拡張機能ステータスの確認 ^^^^^^^^^^^^^^^^^^^^^^^^ 拡張機能はイメージカタログと直接クラスター定義の両方からソースできるため、CloudNativePGは\ ``Cluster`` ステータスで構成の「解決済み」ビューを提供します。これは、オペレーターがポッドをプロビジョニングするために使用する最終的な有効な状態です。 ``status.pgDataImageInfo.extensions`` フィールドを検査して、継承またはオーバーライドの結果を確認できます。 .. code:: yaml # ... status: # ... pgDataImageInfo: image: # registry path for your PostgreSQL image majorVersion: 18 extensions: - name: foo image: reference: # registry path for your `foo` extension image - name: bar image: reference: # registry path for your `bar` extension image # ... このセクションは、次の場合に特に役立ちます。 - **解決策の検証** ``Cluster`` の名前で要求された拡張機能が、関連するカタログから\ ``image.reference`` を正しくプルしたことの確認。 - **オーバーライドの確認** クラスターレベルのオーバーライド特定のイメージバージョンなどによって、カタログのデフォルト値が正常に置き換えられたことを確認します。 - **トラブルシューティング** ポッドがローリング更新される前に、目的のすべての拡張機能がオペレーターによって認識されることを確認します。 PostgreSQLクラスターからの拡張機能の削除 ---------------------------------------- 拡張機能の削除には、インフラストラクチャとデータベースのメタデータの両方をクリーンアップする2段階のプロセスが含まれます。 「library not found」エラーを回避するために、最初にデータベースから拡張機能を削除する必要があります。宣言的管理を使用している場合は、拡張機能に\ ``ensure: absent`` を設定して\ ``Database`` リソースを更新します。 .. code:: yaml spec: # ... extensions: - name: pgvector ensure: absent # ... これにより、CloudNativePGがデータベース内で\ ``DROP EXTENSION`` を実行します。 拡張機能が\ ``shared_preload_libraries`` に追加された場合、\ ``Cluster`` 構成から削除する必要があります。 次に、 ``Cluster`` リソースの\ ``.spec.postgresql.extensions`` リストから拡張エントリを削除します。オペレーターは、ローリング更新を実行して\ ``ImageVolume`` を切断し、関連するGUCパスを更新します。 高度なトピック -------------- 場合によっては、特に次の場合、デフォルトの予想される構造では拡張機能イメージには不十分である可能性があります。 - 拡張機能には追加のシステムライブラリが必要です。 - 複数の拡張機能が同じイメージにバンドルされています。 - イメージはカスタムディレクトリ構造を使用します。 *「構成よりコンベンション」* パラダイムに従って、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が実行時にこれらのシステムライブラリを見つけてロードできるようにします。 .. Important:: PostgreSQLプロセスの開始時に`ld_library_path` を設定する必要があるため、この値を変更するには、**クラスターの再起動**して新しい値を有効にする必要があります。 CloudNativePGは現在、この再起動を自動的にトリガーしません。 `ld_library_path` を変更した後、クラスターを手動で再起動する必要がありますたとえば、`cnpg restart` を使用して 画像の仕様 ---------- CloudNativePGの標準の拡張コンテナイメージには、ルートに2つの必須ディレクトリが含まれます。 - ``/share/`` 拡張制御ファイルたとえば ``.control`` および対応するSQLファイルを含む\ ``extension`` サブディレクトリが含まれています。 - ``/lib/`` 拡張機能の共有ライブラリたとえば ``.so`` およびその他の必要なライブラリが含まれています。 この構造に従うと、手動構成を必要とせずに、CloudNativePG内のPostgreSQLで拡張機能が自動的に検出可能で使用できるようになります。 .. Important:: PostgreSQL拡張機能開発者とサードパーティプロバイダーは、このレイアウトに従ってOCI準拠の拡張機能イメージを公開することをお勧めします。実際の実装の詳細については、公式のCloudNativePG拡張イメージをビルドするためのリファレンスとして機能する `postgres-extensions-containers `_ を確認することをお勧めします。 理想的には、拡張機能画像には次のことを行う必要があります。 - 特定のオペレーティングシステムディストリビューションとCPUアーキテクチャのセットをターゲットとします。 - 特定のPostgreSQLメジャーバージョンに関連付けられること。 - ディストリビューションのネイティブパッケージシステムたとえば ``.deb`` または\ ``.rpm`` パッケージなどを使用してビルドして、クラスターで使用されるPostgreSQLオペランドイメージとの一貫性、セキュリティ、および互換性を保証します。 注意事項 -------- 現在、拡張機能イメージを追加、削除、または更新すると、PostgreSQLポッドの再起動がトリガーされます。この動作は、 `image volumes `_ の方法から継承されます Kubernetesでの作業。 拡張機能の更新を実行する前に、次のことを確認します。 - ステージング環境で更新プロセスを徹底的にテストしました。 - 拡張イメージには、現在インストールされているバージョンとターゲットバージョン間の必要なアップグレードパスが含まれていることを確認しました。 - 関連する\ ``Database`` リソース定義の拡張機能の\ ``version`` フィールドを更新して、イメージの新しいバージョンに合わせて調整します。 これらの手順は、拡張機能の更新中にPostgreSQLクラスターでのダウンタイムまたはデータの不一貫性を防ぐのに役立ちます。