CNPG-I
======


.. raw:: html

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

**CloudNativePGインターフェイス** `CNPG-I <https://github.com/cloudnative-pg/cnpg-i>`_ 
は、コアコードベースを変更せずにCloudNativePGを拡張およびカスタマイズする標準の方法です。

なぜCNPG-Iなのか？
------------------

CloudNativePGは幅広いユースケースをサポートしていますが、そのビルトイン機能では十分でない場合、または特定の機能をメインプロジェクトに直接追加するのは現実的ではありません。

CNPG-Iが登場するまで、ユーザーには2つの主なオプションがありました。

- プロジェクトをフォークしてカスタム動作を追加する、または

- 上流のコードベースにカスタムコンポーネントを記述することにより、上流のコードベースを拡張します。

どちらのアプローチも、メンテナンスのオーバーヘッドが発生し、アップグレードが遅く、重要な機能のデリバリーが遅延します。

CNPG-Iは、コアプロジェクトを中断せずに、クラスターのライフサイクルの重要なポイントバックアップ、リカバリー、サブリソースのリコンシリエーションなどでCloudNativePGを拡張するための安定したgRPCベースの統合ポイントを提供することにより、これらの問題を解決します。

CNPG-Iは以下を拡張できます。

- 演算子、および/または

- PostgreSQLポッド内で実行されているインスタンスマネージャー。

プラグインの登録
----------------

CNPG-Iは、Kubernetes
 
`Container Storage Interface (CSI) <https://kubernetes.io/blog/2019/01/15/container-storage-interface-ga/>`_ からインスピレーションを得ています。オペレーターは、
`CNPG-I protocol <https://github.com/cloudnative-pg/cnpg-i/blob/main/docs/protocol.md>`_ に従って、 **gRPC**
を使用して登録されたプラグインと通信します。

CloudNativePGは、 **起動時に**
プラグインを検出します。次の2つの方法のいずれかで登録できます。

- サイドカーコンテナ – オペレーターの展開内でプラグインを実行します

- スタンドアロン展開 –
  同じ名前空間内の別のワークロードとしてプラグインを実行します

どちらの場合も、プラグインはコンテナイメージとしてパッケージ化する必要があります。

サイドカーコンテナ
^^^^^^^^^^^^^^^^^^

サイドカーとして実行する場合、プラグインは **Unixドメインソケット**
を介してgRPCサーバーを公開する必要があります。このソケットは、オペレーターコンテナと共有するディレクトリに配置し、\ ``PLUGIN_SOCKET_DIR``
デフォルト\ ``/plugin`` で設定したパスにマウントする必要があります。

例

.. code:: yaml

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: controller-manager
   spec:
     template:
       spec:
         containers:
         - image: cloudnative-pg:latest
           [...]
           name: manager
           volumeMounts:
           - mountPath: /plugins
             name: cnpg-i-plugins
               
         - image: cnpg-i-plugin-example:latest
           name: cnpg-i-plugin-example
           volumeMounts:
           - mountPath: /plugins
             name: cnpg-i-plugins
         volumes:
         - name: cnpg-i-plugins
           emptyDir: {}

スタンドアロン展開推奨
^^^^^^^^^^^^^^^^^^^^^^

プラグインを独自の展開として実行すると、そのライフサイクルがオペレーターのライフサイクルから分離され、独立したスケーリングが可能になります。この設定では、プラグインは、安全な通信のための
**mTLS** を使用して、サービスの背後にあるTCP
gRPCエンドポイントを公開します。

..  Warning::
   CloudNativePGはプラグインを動的に検出しません**。新しいプラグインを展開する場合、それを検出するには**オペレーターを再起動**する必要があります。 　

展開例

.. code:: yaml

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: cnpg-i-plugin-example
   spec:
     template:
       [...]
       spec:
         containers:
         - name: cnpg-i-plugin-example
           image: cnpg-i-plugin-example:latest
           ports:
           - containerPort: 9090
             protocol: TCP

プラグインの関連サービスには以下を含める必要があります。

- ラベル ``cnpg.io/plugin: <plugin-name>`` —
  CloudNativePGがプラグインを検出するために必要

- アノテーション ``cnpg.io/pluginPort: <port>`` -
  プラグインのgRPCサーバーが公開されるポートを指定します

サービス例

.. code:: yaml

   apiVersion: v1
   kind: Service
   metadata:
     annotations:
       cnpg.io/pluginPort: "9090"
     labels:
       cnpg.io/pluginName: cnpg-i-plugin-example.my-org.io
     name: cnpg-i-plugin-example
   spec:
     ports:
     - port: 9090
       protocol: TCP
       targetPort: 9090
     selector:
       app: cnpg-i-plugin-example

TLS証明書の構成
^^^^^^^^^^^^^^^

プラグインが\ ``Deployment``
として実行される場合、CloudNativePGとの通信はネットワーク経由で発生します。それを保護するために、
**mTLSが適用され** 、両方の側にTLS証明書が必要です。

証明書は `Kubernetes TLS Secrets <https://kubernetes.io/docs/concepts/configuration/secret/#tls-secrets>`_ として保存する必要があります

およびプラグインのサービスアノテーション\ ``cnpg.io/pluginClientSecret``
および\ ``cnpg.io/pluginServerSecret`` で参照されます。

.. code:: yaml

   apiVersion: v1
   kind: Service
   metadata:
     annotations:
       cnpg.io/pluginClientSecret: cnpg-i-plugin-example-client-tls
       cnpg.io/pluginServerSecret: cnpg-i-plugin-example-server-tls
       cnpg.io/pluginPort: "9090"
     name: barman-cloud
     namespace: postgresql-operator-system
   spec:
       [...]

..  Note::
   独自の証明書バンドルを提供できますが、 `Cert-manager <https://cert-manager.io>`_ を使用することをお勧めします。 　

証明書のDNS名のカスタマイズ
^^^^^^^^^^^^^^^^^^^^^^^^^^^

デフォルトでは、CloudNativePGは、プラグインへの接続時にTLS検証のサーバー名としてサービス名を使用します。ご使用の環境により、証明書に別のDNS名\ ``barman-cloud.svc``
などが必要な場合、 ``cnpg.io/pluginServerName``
アノテーションを使用してカスタマイズできます。

.. code:: yaml

   apiVersion: v1
   kind: Service
   metadata:
     annotations:
       cnpg.io/pluginClientSecret: cnpg-i-plugin-example-client-tls
       cnpg.io/pluginServerSecret: cnpg-i-plugin-example-server-tls
       cnpg.io/pluginPort: "9090"
       cnpg.io/pluginServerName: barman-cloud.svc
     name: barman-cloud
     namespace: postgresql-operator-system
   spec:
       [...]

これにより、オペレーターは、デフォルトのサービス名ではなく指定されたDNS名と比較してプラグインの証明書を検証できます。サーバー証明書には、このDNS名がサブジェクト代替名SANに含まれている必要があります。

プラグインを使用する
--------------------

プラグインを有効にするには、 ``Cluster`` リソースの\ ``.spec.plugins``
セクションを構成します。完全な `PluginConfiguration <https://cloudnative-pg.io/documentation/current/cloudnative-pg.v1/#postgresql-cnpg-io-v1-PluginConfiguration>`_ については、CloudNativePG
APIリファレンスを参照してください。

仕様。

例

.. code:: yaml

   apiVersion: postgresql.cnpg.io/v1
   kind: Cluster
   metadata:
     name: cluster-with-plugins
   spec:
     instances: 1
     storage:
       size: 1Gi
     plugins:
     - name: cnpg-i-plugin-example.my-org.io
       enabled: true
       parameters:
         key1: value1
         key2: value2

各プラグインは独自のパラメーターを持つ場合があります。詳細については、プラグインのドキュメントを確認してください。
``spec.plugins`` の\ ``name``
フィールドは、プラグインが展開される方法によって異なります。

- サイドカーコンテナ Unixソケットファイル名を使用します

- Deployment サービスの\ ``cnpg.io/pluginName`` labelの値を使用します

コミュニティプラグイン
----------------------

CNPG-Iプロトコルは、コアプロジェクトを保守可能に保ちながらCloudNativePGを拡張するための証明された信頼性の高いパターンになりました。時間の経過とともに、コミュニティは実世界のニーズに対応し、開発者の例として機能するプラグインを構築および共有してきました。

CNPG-Iでビルドされたプラグインの完全な最新のリストについては、
`CNPG-I GitHub page <https://github.com/cloudnative-pg/cnpg-i?tab=readme-ov-file#projects-built-with-cnpg-i>`_ を参照してください。