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とともに、CloudNativePGプロジェクトが貢献した機能。

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

CREATE EXTENSION コマンドを介してデータベースレベルのインストールが必要な拡張機能の場合、 アプリケーションデータベースの構成

すべてのPostgreSQLデータベースで一貫した自動セットアップを保証します。

公式拡張機能のイメージとカタログ

CloudNativePGコミュニティは、 pgvector を含む拡張コンテナイメージスイートを維持しています

および postgres-extensions-containers の一部としての PostGIS 。これらのイメージは、 official PostgreSQL `minimal images <https://github.com/cloudnative-pg/postgres-containers?tab=readme-ov-file#minimal-images>`_ の上にビルドされます。

注釈

このドキュメントは、サードパーティが独自のイメージとカタログをビルドするために必要な技術仕様を提供しますが、次の手順では、公式の拡張機能イメージとカタログの展開と使用に特に焦点を当てています。

メリット

この機能は、 PostgreSQLオペランドイメージから拡張機能のディストリビューションを分離することにより、コンテナでPostgreSQLを実行する際の重要な障壁を取り除きます。ビルド時に拡張機能を埋め込む必要がなくなり、公式の最小限のオペランドイメージを使用し、必要な拡張機能のみをCluster 定義に直接または Image Catalog を介して追加できます。

このアプローチでは、コアデータベースコンテナに操作に必要な重要なバイナリのみが含まれるようにすることにより、データベースクラスターの攻撃対象領域を大幅に削減します。不要な拡張機能、ライブラリ、およびビルド時の依存関係を除外することにより、エクスプロイトの潜在的なエントリーポイントを最小限に抑え、脆弱性管理を簡素化します。このアーキテクチャは、データワークロードの不変の最小限のベースイメージを維持することにより、サプライチェーンのセキュリティを強化し、運用オーバーヘッドを削減します。

重要

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

要件

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 リソースに追加できます。

重要

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

構成ソースと優先順位

extensions スタンザは、エントリのリストを受け入れます。各エントリは、クラスター内で一意である必要があるname を必要とします。

重要

name は、小文字の英数字、アンダースコア`_` またはハイフン`-` で構成され、英数字で開始および終了する必要があります。各エントリは、コンテナイメージの構成を定義し、PostgreSQLが拡張機能を見つけてロードするために必要なオプションを指定します。

  • **Via Image Catalog** クラスターが、現在のPostgreSQLメジャーバージョンの拡張機能を定義するImageCatalog を参照する場合、これらの定義はデフォルト構成として機能します。これにより、カタログはimage.reference を一元管理できますが、クラスターは単に名前で拡張機能を有効にするだけです。

  • クラスター内に直接 クラスターがイメージカタログを使用しない場合、image.reference フィールドは必須で、拡張機能イメージの有効なコンテナレジストリパスを明示的に指定する必要があります。 image スタンザは

Kubernetes `ImageVolume API <https://kubernetes.io/docs/concepts/storage/volumes/#image>`_ の後にあります。

「構成よりコンベンション」 パラダイムに従って、CloudNativePGは完全な柔軟性を提供します。image.reference を含むカタログから継承した値は、特定のローカル要件を満たすようにCluster 定義内で選択的にオーバーライドできます。

マウンティングとPostgreSQLの構成

各拡張機能は、ポッド内の/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

注釈

アンダースコアを含む拡張名たとえば`pg_ivm` は、RFC 1123 DNSラベル要件に準拠するようにKubernetesボリューム名にハイフンたとえば`pg-ivm` を使用するように変換されます。サニタイズ後に同じになる拡張名は使用しないでくださいたとえば、 pg_ivm と`pg-ivm` は両方とも`pg-ivm` にサニタイズします。 Webhook検証は、このような競合を防ぎます。これらの値は、拡張機能が`extensions` リストで定義された順序で追加され、PostgreSQL内の決定論的なパスの解決が保証されます。これにより、PostgreSQLは、ポッド内の手動構成を必要とせずに拡張機能を検出してロードできます。

カスタム画像レイアウトに一致するようにこれらのパスを手動で調整できますが、公式CloudNativePGカタログは、これらのオプションを各拡張機能の正しい値に事前構成し、すぐに機能することを保証します。

重要

拡張イメージに共有ライブラリが含まれる場合、オペランドイメージと同じPostgreSQLメジャーバージョン、オペレーティングシステムディストリビューション、およびCPUアーキテクチャ用にコンパイルする必要があります。公式のCloudNativePGカタログを使用すると、この互換性が自動的に保証されます。カタログは、クラスターの特定の環境と一致するように設計され、ライブラリまたはアーキテクチャの不一致によって発生するランタイムの問題を防ぎます。

データベースへのインストール

データベース内の拡張機能の管理 を活用できます

標準のPostgreSQL CREATE EXTENSION メカニズムをサポートする拡張機能の最終的なアクティブ化を自動化します。

拡張機能イメージがマウントされ、GUCが構成されると、拡張機能はPostgreSQLインスタンスで利用できるようになりますが、特定のデータベース内ではまだアクティブになっていません。インストールするには、 Database リソースを定義します。次の例では、 official `postgres-extensions-containers project <https://github.com/cloudnative-pg/postgres-extensions-containers/tree/main/pgvector>`_ の実装標準に従って、 pgvector を使用します。

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: "<VERSION>"

CloudNativePGは、ターゲットデータベース内でCREATE EXTENSION IF NOT EXISTS vector を実行することにより、このリソースを自動的にリコンサイルします。これにより、目的の状態が維持され、すべてのインスタンスに一貫して適用されます。

注釈

モジュールと呼ばれることが多い一部のPostgreSQLコンポーネントは、 CREATE EXTENSION メカニズムを使用しません。これらは通常、サーバーの起動時に`shared_preload_libraries` を介してロードする必要がある共有ライブラリで構成されます。イメージカタログを使用してこれらのバイナリの配布を簡素化する場合でも、ライブラリ名を shared_preload_libraries に手動で追加する必要があります

Cluster 定義で変更して、メモリにロードされるようにします。

Postgresクラスターへの拡張機能の追加

以前に予想されたように、CloudNativePGは、拡張機能イメージを定義する2つの方法を提供します。どちらもポッドレベルで同じ結果を達成しますが、一貫した運用準備が整ったサプライチェーンを維持するには、イメージカタログを使用することをお勧めします。

画像カタログ経由推奨

注釈

イメージカタログの拡張コンテナイメージのサポートは、CloudNativePG 1.29で導入されました。 image catalog that covers extensions を使用する場合

official ones のような

コミュニティが提供するシステムでは、特定のコンテナイメージreference や必要なファイルシステムパスなどの複雑な構成の詳細が一元管理されます。

Cluster 定義は、名前で拡張機能に「オプトイン」するだけでよいため、クリーンで宣言的なままです。オペレーターは、カタログの定義に基づいて、画像の解像度と必要なPostgreSQL設定を自動的に処理します。

カタログからpgvector のような拡張機能を有効にするには、次の抜粋のように、クラスターのextensions リストに追加します。

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-example
spec:
  # ... <snip>
  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
      # ... <snip>

この方法により、拡張イメージは、同じカタログエントリで定義されたPostgreSQLオペランドイメージと常に互換性があることが保証されます。

クラスター内に直接

注釈

Cluster リソースで拡張機能を直接定義するのがオリジナルの方法で、CloudNativePG 1.29より前のバージョンの唯一のオプションのままです。現在のカタログに存在しない拡張機能を使用する必要がある場合、またはカスタムイメージをテストする場合にも役立ちます。カタログを使用せずに`Cluster` リソース内で拡張機能を直接定義できます。この場合、イメージ`reference` を明示的に提供する必要があります。

次の例は、公式コンテナイメージを明示的に指定することによりpgvector を追加する方法を示しています。

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-example
spec:
  # ... <snip>
  postgresql:
    extensions:
      - name: pgvector
        image:
          reference: ghcr.io/cloudnative-pg/pgvector:<TAG>

Tip

Cluster で直接提供される構成が優先されることに注意してください。カタログを参照しているが、 Cluster スタンザでも同じ拡張名を定義している場合、 Cluster の設定がカタログの設定をオーバーライドします。 ExtensionConfiguration のすべてのフィールド

Cluster レベルでオーバーライドして、完全な柔軟性を提供できます。name フィールドは例外です。 !!!警告 name は一意の識別子として機能します。それを変更すると、カタログから既存の拡張機能エントリをオーバーライドするのではなく、新しい拡張機能エントリが定義されます。

拡張機能ステータスの確認

拡張機能はイメージカタログと直接クラスター定義の両方からソースできるため、CloudNativePGはCluster ステータスで構成の「解決済み」ビューを提供します。これは、オペレーターがポッドをプロビジョニングするために使用する最終的な有効な状態です。

status.pgDataImageInfo.extensions フィールドを検査して、継承またはオーバーライドの結果を確認できます。

#  ... <snip>

status:
  # ... <snip>
  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
    # ... <snip>

このセクションは、次の場合に特に役立ちます。

  • 解決策の検証 Cluster の名前で要求された拡張機能が、関連するカタログからimage.reference を正しくプルしたことの確認。

  • オーバーライドの確認 クラスターレベルのオーバーライド特定のイメージバージョンなどによって、カタログのデフォルト値が正常に置き換えられたことを確認します。

  • トラブルシューティング ポッドがローリング更新される前に、目的のすべての拡張機能がオペレーターによって認識されることを確認します。

PostgreSQLクラスターからの拡張機能の削除

拡張機能の削除には、インフラストラクチャとデータベースのメタデータの両方をクリーンアップする2段階のプロセスが含まれます。

「library not found」エラーを回避するために、最初にデータベースから拡張機能を削除する必要があります。宣言的管理を使用している場合は、拡張機能にensure: absent を設定してDatabase リソースを更新します。

spec:
  # ... <snip>
  extensions:
    - name: pgvector
      ensure: absent
    # ... <snip>

これにより、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 を明示的に設定することによりデフォルトをオーバーライドできます。

例

spec:
  # ... <snip>
  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
      # ... <snip>
    # ... <snip>
  # ... <snip>

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

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

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

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

マルチ拡張子画像

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

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

#  ...

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

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

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

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

#  ...

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

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準拠の拡張機能イメージを公開することをお勧めします。実際の実装の詳細については、公式のCloudNativePG拡張イメージをビルドするためのリファレンスとして機能する postgres-extensions-containers を確認することをお勧めします。

理想的には、拡張機能画像には次のことを行う必要があります。

  • 特定のオペレーティングシステムディストリビューションとCPUアーキテクチャのセットをターゲットとします。

  • 特定のPostgreSQLメジャーバージョンに関連付けられること。

  • ディストリビューションのネイティブパッケージシステムたとえば .deb または.rpm パッケージなどを使用してビルドして、クラスターで使用されるPostgreSQLオペランドイメージとの一貫性、セキュリティ、および互換性を保証します。

注意事項

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

Kubernetesでの作業。

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

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

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

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

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