Installation and upgrades

Kubernetesへのインストール

オペレーターマニフェストを直接使用する

オペレーターは、Kubernetesの他のリソースと同様に、kubectl を介して適用されるYAMLマニフェストを介してインストールできます。

このマイナーリリースでは次のようになります。

kubectl apply --server-side -f \
  https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.30/releases/cnpg-1.30.0.yaml

これは次の方法で確認できます。

kubectl rollout status deployment \
  -n cnpg-system cnpg-controller-manager

`kubectl` の`cnpg` プラグインを使用する

cnpg プラグインを使用して、静的マニフェストにあるデフォルトの構成オプションをオーバーライドできます。

たとえば、デフォルトの最新のマニフェストを生成しますが、ウォッチ名前空間を特定の名前空間のみに変更するには、次のコマンドを実行できます。

kubectl cnpg install generate \
  --watch-namespace "specific-namespace" \
  > cnpg_for_specific_namespace.yaml

より包括的な例については、 postgresql.cnpg.io/v1 ドキュメントを参照してください。

警告

GKEにCloudNativePGをデプロイしており、エラー`... failed to call webhook...` を取得した場合は、公式 docs で説明しているように、デフォルトでは、ワーカーノードとコントロールプレーン間のトラフィックは、いくつかの特定のポートを除きてファイアウォールによってブロックされていることに注意してください

そしてこれによって issue 。 WebhookサービスのtargetPort を許可されるもののいずれかに変更するか、ファイアウォールでWebhookのポート9443 を開く必要があります。

Helmチャートを使用する

オペレーターは、提供されている Helm chart を使用してインストールできます。

OLMを使用する

CloudNativePGは、 Operator Lifecycle Manager (OLM) からインストールすることもできます

OperatorHub.io から直接。

Red Hat OpenShiftでの展開の場合、EDBは、 Red Hat OpenShift Container Platform から入手可能なCloudNativePGの認定バージョンを提供および完全にサポートしています。

デプロイメントの詳細

Kubernetesでは、オペレーターはデフォルトでKubernetes Deployment としてcnpg-system 名前空間にインストールされます。この展開の名前は、インストール方法によって異なります。マニフェストまたはcnpg プラグインを介してインストールされる場合、デフォルトでcnpg-controller-manager と呼ばれます。 Helmを介してインストールされた場合、デフォルト名はcnpg-cloudnative-pg です。

注釈

Helmを使用すると、 _"values.yaml"_ file の`fullnameOverride` フィールドを介してデプロイメントの名前をカスタマイズできます。

kubectl のdescribe コマンドを使用して、詳細情報を取得できます。

$ kubectl get deployments -n cnpg-system
NAME                READY   UP-TO-DATE   AVAILABLE   AGE
<deployment-name>   1/1     1            1           18m

kubectl describe deploy \
  -n cnpg-system \
  <deployment-name>

他の展開と同様に、レプリカセットの上にあり、ローリングアップグレードをサポートします。 CloudNativePGオペレーターのデフォルト構成には、単一のレプリカの展開が付属しており、ほとんどのインストールに適しています。ポッドが実行されているノードに到達できなくなった場合、ポッドは別のノードで再スケジュールされます。

オペレーターレベルでの高可用性が必要な場合、オペレーターがリーダー選択をサポートしていることを考慮すると、展開構成で複数のレプリカを指定できます。また、テイントと寛容を利用して、実際のPostgreSQLクラスターが実行されているノードでオペレーターが実行されないことを確認できます。これには、自己管理のKubernetesインストールのコントロールプレーンが含まれる場合があります。

注釈

いくつかのデフォルトオプションをオーバーライドすることにより、オペレーターのデフォルト動作を変更できます。詳細については、 Operator configuration セクションを参照してください。

アップグレード

注釈

1.14.0以前のリリースノートをよくお読みください

一部のバージョンは追加の手順を必要とする場合があるため、アップグレードを実行する前に。

CloudNativePGオペレーターのアップグレードは、2段階のプロセスです。

コントローラと関連するKubernetesリソースをアップグレードする
すべてのPostgreSQLポッドで実行されているインスタンスマネージャーをアップグレードする

リリースノートに別の記載がない限り、最初のステップは、通常、プレーンなKubernetesインストールの新しいバージョンのマニフェストを適用するか、使用するディストリビューションのネイティブパッケージマネージャーを使用して実行されます上記のセクションの指示に従ってください。

2番目のステップは、コントローラの更新後に自動的にトリガーされます。デフォルトでは、これにより、展開されたすべてのPostgreSQLクラスターのローリング更新が開始され、新しいインスタンスマネージャーを使用するように一度に1つのインスタンスをアップグレードします。ローリング更新は、 primaryUpdateStrategy オプションによって制御されるスイッチオーバーで終了します。デフォルト値unsupervised は、スイッチオーバーを自動的に完了します。 supervised に設定している場合、ユーザーはkubectl のcnpg プラグインを使用して、新しいプライマリインスタンスを手動でプロモートする必要があります。

注釈

このプロセスは、 Rolling updates ページで詳細に説明されています。

注釈

primaryUpdateStrategy が`unsupervised` のデフォルト値に設定されている場合、オペレーターのアップグレードはPostgreSQLクラスターでスイッチオーバーをトリガーし、通常は無視できるダウンタイムを発生します。 PostgreSQLクラスターにインスタンスが1つだけある場合、 supervised 値は`primaryUpdateStrategy` でサポートされていないため、インスタンスは自動的に再起動されます。いずれの場合も、アプリケーションはPostgreSQLに再接続する必要があります。

デフォルトのローリング更新動作は、インスタンスマネージャーのインプレース更新に置き換えることができます。このアプローチでは、 PostgreSQLインスタンスの再起動が必要ないため、クラスター内のスイッチオーバーを回避します。この機能はデフォルトで無効になっていますが、以下で詳細に説明します。

スプレッドアップグレード

デフォルトでは、すべてのPostgreSQLクラスターは同時にロールアウトされるため、特に複数のクラスターを管理する場合、リソース使用量の急増につながる可能性があります。 CloudNativePGは、 operator level で2つの構成オプションを提供します

これにより、クラスターのロールアウト間、または同じクラスター内のインスタンス間で遅延を導入でき、時間の経過とともにリソース使用量を分散するのに役立ちます。

CLUSTERS_ROLLOUT_DELAY さまざまなPostgreSQLクラスターデフォルト0 のロールアウトの間で待機する秒数を定義します。
INSTANCES_ROLLOUT_DELAY 同じPostgreSQLクラスター内の個々のインスタンスのロールアウトの間で待機する秒数を定義しますデフォルト0 。

インスタンスマネージャーのインプレース更新

デフォルトでは、CloudNativePGは、オペレーターが更新されるたびに、クラスターのローリング更新を発行します。オペレーターに同梱される新しいインスタンスマネージャーは、initコンテナを介して各PostgreSQLポッドに追加されます。

ただし、この動作は構成を介して変更でき、インスタンスマネージャーのインプレース更新を有効にできます。これは、コンテナを生きたままにするPID 1プロセスです。

内部的には、CloudNativePGの各インスタンスマネージャーは、完全性検証フェーズが正常に完了し、すべての内部プロセスを正常に終了した後、既存の実行可能ファイルを置き換える新しい実行可能ファイルのインジェクションをサポートします。新しいバイナリで再起動すると、インスタンスマネージャーは既に実行されている_postmaster_をシームレスに採用します。

その結果、PostgreSQLプロセスは更新の影響を受けず、スイッチオーバーを実行する必要はありません。コインの反対側は、Podがスタート後に変更され、不変性の純粋な概念を壊すということです。

Operator configuration でENABLE_INSTANCE_MANAGER_INPLACE_UPDATES 環境変数を'true' に設定することにより、この機能を有効にできます。

インプレースアップグレードプロセスでは、ポッド内のinitコンテナイメージは変更されません。したがって、ポッド定義はオペレーターの現在のバージョンを反映しません。

バージョン間の互換性

CloudNativePGはセマンティックバージョニングに従います。同じAPIバージョン内のオペレーターのすべてのリリースは、以前のAPIバージョンと互換性があります。現在のAPIバージョンはv1で、オペレーターのバージョン1.x.yに対応します。

新機能に加えて、オペレーターの新しいバージョンにはバグ修正と安定性の強化が含まれています。このため、各バージョンは、最も安全で安定したPostgres環境を維持するためにリリースされるため、**オペレーターの最新バージョンにアップグレードすることを強くお勧めします。

CloudNativePGは現在、少なくとも毎月オペレーターの新しいバージョンをリリースしています。各バージョンが利用可能になったときに更新を適用できない場合は、バージョンをスキップせずに、各バージョンを順番にアップグレードして、定期的に最新の状態になることをお勧めします。

1.14.0以前のリリースノートページには、CloudNativePGのすべてのリリースバージョンで導入された変更の詳細なリストが含まれており、ソフトウェアの新しいバージョンにアップグレードする前に読む必要があります。

ほとんどのバージョンは直接アップグレード可能であり、その場合、プレーンなKubernetesインストールに新しいマニフェストを適用するか、選択したディストリビューションのネイティブパッケージマネージャーを使用するだけで十分です。

バージョンを直接アップグレードできない場合、新しいバージョンをインストールする前に古いバージョンを削除する必要があります。これはユーザーデータに影響を与えるのではなく、オペレーター自分自身にのみ影響を与えます。

1.30.0、1.29.2、または1.28.4へのアップグレード

注釈

すべてのCloudNativePGユーザーがバージョン1.30.0、または少なくとも現在のマイナーリリース1.29.2または1.28.4などの最新の安定バージョンにアップグレードすることを強くお勧めします。

これらのリリースには、アップグレードする前に確認する価値のある変更が導入されています。 2つは 1.30.0、1.29.2、および1.28.4 に適用されるセキュリティ変更です。オペレーターサイドのパスワードエンコード CVE-2026-55765 とsearch_path の強化 CVE-2026-55769 。他の3つは 1.30.0 のみの新機能です。宣言的ロール管理用のDatabaseRole リソース、クラスターごとのリースを介した安全なプライマリ選択、およびインスタンスマネージャーのステータスポートGHSA-7qwx-x8ff-3px9 でのオペレーター対インスタンス認証。さらに、 1.29.1または1.28.3 より古いリリースからアップグレードする場合、 CVE-2026-44477 からのメトリックエクスポータ権限の分離も適用されます。それぞれについて、以下の独自のサブセクションで説明します。

オペレーター側のパスワードエンコーディング `CVE-2026-55765`

バージョン1.30.0、1.29.2、および1.28.4から、セキュリティ上の理由から CVE-2026-55765 / GHSA-w3gf-xc94-wvmj 、CloudNativePG SCRAM-SHA-256はロールパスワードをエンコードします オペレータサイド PostgreSQLの観点からクライアントサイド)CREATE /ALTER ROLE ステートメントを発行する前に。その結果、 PostgreSQLパーサーに到達するリテラルおよびpg_stat_statements やpgaudit などの拡張機能が観察するリテラルは、pg_authid.rolpassword に到達するハッシュと同じであり、平文シークレットではありません。エンコードは、オペレーターが使用するすべての基本認証Secret 、postgres スーパーユーザーシークレット、アプリケーションユーザーシークレット、および管理対象ロールパスワードシークレットに適用されます。 MD5またはSCRAM-SHA-256シャドウフォームで既に指定されたパスワードは、変更せずにパススルーされます。

PostgreSQL 14 以降、 password_encryption はデフォルトでscram-sha-256 になるため、既存のインストールがこの変更の影響を受けることはないと思われます。

クラスターがpassword_encryption をscram-sha-256 以外の値に明示的にオーバーライドしていて、PostgreSQL演算子ではなくにパスワードをハッシュする方法を決定したい場合は、各basic-auth Secret にアノテーションcnpg.io/passwordPassthrough: "enabled" を設定してオプトアウトしますオペレーターが消費します。オペレーターはパスワード値をそのまま転送し、PostgreSQLは独自のpassword_encryption GUCに従ってそれをエンコードします。

警告

cnpg.io/passwordPassthrough アノテーションは、Cluster リソースではなく、**basic-auth Secret**自分自身に設定する必要があります。 Cluster に配置しても効果はなく、オペレーターはPostgreSQLに送信する前にパスワードにSCRAM-SHA-256エンコードを適用し続けます。

警告

cnpg.io/passwordPassthrough: "enabled" を使用すると、オペレーターはシークレットの`password` 値を逐語転送します。その値がクリアテキストの場合、password_encryption = md5 クラスターで一般的なように、pg_stat_statements や`pgaudit` などの拡張機能はそれを監視します。

オペレーターサイドのエンコーディングのオプトアウトを参照

詳細については。

`search_path` 強化 `CVE-2026-55769`

また、バージョン1.30.0、1.29.2、および1.28.4から、セキュリティ上の理由からCVE-2026-55769 / GHSA-x8c2-3p4r-v9r6 、CloudNativePGはPostgreSQLへ開くすべての接続でsearch_path を固定pg_catalog, public, pg_temp に固定するため、テナント制御のALTER DATABASE / ALTER ROLE 設定は、オペレーター発行のクエリーが非修飾のオブジェクト名を解決する方法に影響を与えることができなくなりました。 PgBouncer統合で使用されるSECURITY DEFINER ルックアップファンクションは、アップグレード後の最初のリコンシリエーション中に、独自の固定されたsearch_path を使用して自動的に再作成されます。スキーマの解決と`search_path の強化 <スキーマの解決と`search_path` の強化>` を参照

理論的根拠のため。

この変更は、 search_path がpg_catalog, public, pg_temp に固定されているトランザクション内で実行されるカスタムモニタリングクエリーにも影響します。カスタムメトリックが、非修飾名を介して他のユーザー定義スキーマにあるオブジェクトを参照している場合、アップグレード後も解決し続けるようにスキーマ修飾たとえば myschema.mytable 。ユーザー作成のブートストラップpostInit* および論理インポートインポート後SQLは影響を受けません。これらは標準の"$user", public 解像度で実行され続けます。

`DatabaseRole` リソースを使用した宣言的ロール管理

バージョン1.30.0以降、クラスターの.spec.managed.roles スタンザでインライン宣言するのではなく、スタンドアロンの DatabaseRole リソースとしてPostgreSQLロールを管理することもできます。これはオプトイン機能の強化であり、アップグレード時のアクションは必要ありません。既存のインラインロールは変更せずに動作し続け、インラインmanaged.roles メソッドは完全にサポートされたままです。

中断せずに既存のインラインロールをDatabaseRole の下に移動するには、最初にDatabaseRole を作成してから、 .spec.managed.roles から一致するエントリーを削除します。両方が存在しますが、クラスター仕様が常に優先されるため、インラインエントリがなくなった場合にのみ管理が引き渡されます。インライン管理ロールから`DatabaseRole への移行 <インライン管理ロールから`DatabaseRole` への移行>` を参照

完全な手順については。

DatabaseRole はensure: absent をサポートしていません。インラインmanaged.roles スタンザがensure: absent を設定することによりロールをドロップする場合、 DatabaseRole は代わりにdatabaseRoleReclaimPolicy フィールドに依存します。 databaseRoleReclaimPolicy: delete でリソースを削除してPostgreSQLからロールを削除するか、デフォルトのretain をそのままにしてロールをそのままにします。

安全な予備選挙

バージョン1.30.0から、CloudNativePGは、クラスターごとのKubernetes Lease を介してプライマリプロモーションを調整し、任意の時点で、最大1つのインスタンスが自分自身をプロモーションするようにします。この動作は自動的に有効になり、構成は必要ありません。リースタイミングは、 .spec.primaryLease を介してオプションで調整できます安全な予備選挙を参照してください。

警告

この機能を使用するには、オペレーターが`coordination.k8s.io` APIグループの`Lease` オブジェクトを管理する必要があります。バンドルされたオペレーターマニフェストとHelmチャートは、必要な権限を自動的に付与します。オペレーターのRBACを自分で管理する場合、アップグレードする前に、coordination.k8s.io APIグループの`leases` に`create` 、get 、list 、update 、および`watch` 動詞を追加する必要があります。そうしないと、プライマリはプロモーションできません。

オペレーターからインスタンスへの認証 `GHSA-7qwx-x8ff-3px9`

バージョン1.30.0から、オペレーターは、メモリ内クライアント証明書をピン留めすることにより、インスタンスマネージャーのステータスポートbackup、pg_controldata 、部分的なWALアーカイブ、およびインスタンスマネージャーのアップグレードの機密エンドポイントへの呼び出しを認証します。これは自動的に有効になり、構成は必要ありません。ステータス、状態、およびプローブエンドポイントは認証されないままです。この強化はバックポートされません。 1.30.0より前のリリースでは、NetworkPolicy でステータスポートTCP 8000を制限し続けますが、これはセキュリティ境界のままです。オペレーターからインスタンスへの認証 `GHSA-7qwx-x8ff-3px9 <オペレーターからインスタンスへの認証 GHSA-7qwx-x8ff-3px9>` を参照

詳細については。

警告

この保護には、ハード要件があります。ステータスポートはTLSで提供される必要がありますv1.24以降のデフォルトです。 v1.24より古いオペレーターによって作成されたインスタンスは、プレーンなHTTPでステータスポートを提供します。インスタンスマネージャーが1.30.0にアップグレードされると、オペレーターはそれらに対して認証できなくなり、保護されたエンドポイントへのすべての呼び出しは`401 Unauthorized` で**永久に**拒否されます。このようなインスタンスをまだ実行している場合は、ローリング更新を実行して、ポッドがTLS対応ステータスポートで再作成されます。 v1.24以降で作成されたインスタンスは影響を受けません。

メトリックエクスポーターの特権分離 `CVE-2026-44477`

これは、1.29.1または1.28.3より古いリリース**たとえば、1.29.0、1.28.2、または以前のバージョンからアップグレードする場合にのみ適用されます。 1.29.1、1.28.3以降に既にインストールされている場合には、この変更が既に含まれています。

CVE-2026-44477 / GHSA-423p-g724-fr39 の修正により、メトリックエクスポーターは、postgres スーパーユーザーではなく、pg_monitor 特権のみを持つ専用のcnpg_metrics_exporter ロールとして認証します。

ユーザー所有テーブルを読み取るカスタムモニタリングクエリー、またはPUBLIC CONNECT が取り消されたデータベースに対してtarget_databases: '*' を使用するカスタムモニタリングクエリーは、 cnpg_metrics_exporter に対する明示的なGRANT ステートメントが必要です。カスタムクエリーの特権と安全性を参照

とメトリックエクスポーターロールの手動作成

モニタリング文書で。

リリースアセットの検証

CloudNativePGは、すべての公式リリースアセットに暗号的に署名します。これらの署名を検証することにより、アセットが公式リポジトリから生成され、自動リリースワークフローを通じて公開されたことが保証されます。

注釈

リリースの完全性とサプライチェーンを参照してください

詳細については、

前提条件

署名検証 cosign CLI
SBOMと来歴 Docker Buildx

Docker Desktopおよび最新のDockerバージョンに含まれています

オペレーターYAML展開の検証

直接YAMLマニフェストを介してインストールする場合、 GitHub Release page で提供される対応するバンドル .sigstore.json ファイルを使用してマニフェストファイルを確認する必要があります。

次のコマンドを実行します。

cosign verify-blob \
  cnpg-{version}.yaml \
  --bundle cnpg-{version}.sigstore.json \
  --certificate-identity-regexp "^https://github.com/cloudnative-pg/cloudnative-pg/.github/workflows/release-publish.yml@refs/tags/v" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

SLSAの出所の検証

リリースバイナリを検証するには、アーティファクトと来歴ファイル multiple.intoto.jsonl の両方を GitHub release からダウンロードし、実行します。

slsa-verifier verify-artifact <ARTIFACT> \
  --provenance-path multiple.intoto.jsonl \
  --source-uri github.com/cloudnative-pg/cloudnative-pg

オペレーターコンテナイメージの検証

次のコマンドを実行して、CloudNativePGオペレーターイメージの署名を確認します。

cosign verify ghcr.io/cloudnative-pg/cloudnative-pg:{tag} \
  --certificate-identity-regexp="^https://github.com/cloudnative-pg/cloudnative-pg/.github/workflows/release-publish.yml@refs/tags/v" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com"

完全な透明性を実現するためにOCI証明書を提供します。ソフトウェア部品表SBOMを検査するか、来歴をビルドするには、 docker buildx imagetools コマンドを使用します。

SPDX形式のソフトウェア部品表SBOMを表示するには

docker buildx imagetools inspect ghcr.io/cloudnative-pg/cloudnative-pg:{tag} \
  --format {{ json (index .SBOM "linux/amd64").SPDX }}

SLSA来歴ビルドの詳細を検査するには

docker buildx imagetools inspect ghcr.io/cloudnative-pg/cloudnative-pg:{tag} \
  --format {{ json (index .Provenance "linux/amd64").SLSA }}

注釈

SLSAの出所の検証参照

SLSAビルドレベル3コンプライアンス検証用。

PostgreSQLオペランドイメージの検証

CloudNativePGは、サポートされているすべてのPostgreSQLバージョンのコンテナイメージを postgres-containers の一部として維持します

オペランドイメージとも呼ばれます。

特定のオペランドイメージの署名を検証するには

cosign verify ghcr.io/cloudnative-pg/postgresql:{tag} \
  --certificate-identity-regexp="^https://github.com/cloudnative-pg/postgres-containers/" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com"