CNPG-I

CloudNativePGインターフェイス CNPG-I は、コアコードベースを変更せずにCloudNativePGを拡張およびカスタマイズする標準の方法です。

なぜCNPG-Iなのか？

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

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

プロジェクトをフォークしてカスタム動作を追加する、または
上流のコードベースにカスタムコンポーネントを記述することにより、上流のコードベースを拡張します。

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

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

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

演算子、および/または
PostgreSQLポッド内で実行されているインスタンスマネージャー。

プラグインの登録

CNPG-Iは、Kubernetes

Container Storage Interface (CSI) からインスピレーションを得ています。オペレーターは、 CNPG-I protocol に従って、 gRPC を使用して登録されたプラグインと通信します。

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

サイドカーコンテナ – オペレーターの展開内でプラグインを実行します
スタンドアロン展開 – 同じ名前空間内の別のワークロードとしてプラグインを実行します

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

サイドカーコンテナ

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

例

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エンドポイントを公開します。

警告

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

展開例

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サーバーが公開されるポートを指定します

サービス例

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 として保存する必要があります

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

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:
    [...]

注釈

独自の証明書バンドルを提供できますが、 Cert-manager を使用することをお勧めします。

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

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

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 については、CloudNativePG APIリファレンスを参照してください。

仕様。

例

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 を参照してください。