Bootstrap

このセクションでは、新しいPostgreSQLクラスターを作成するために必要なオプションと、その背後にある設計理論的根拠について説明します。新しいクラスターをブートストラップするには、主に2つの方法があります。

スクラッチから initdb
既存のPostgreSQLクラスターから直接pg_basebackup または物理ベースバックアップrecovery を介して間接的に

initdb ブートストラップは、Kubernetesの外部で、Postgresの異なるメジャーバージョンを使用している場合でも、既存のPostgresクラスターから1つ以上のデータベースをインポートする可能性も提供します。この機能の詳細については、

Postgresデータベースのインポートセクションを参照してください。

重要

既存のクラスターからのブートストラップは、**レプリカクラスター**を作成する可能性を開きます。これは、継続的リカバリーでソースと同期し、読み取り専用接続を受け入れる独立したPostgreSQLクラスターです。

警告

CloudNativePGでは、 postgres ユーザーとデータベースの両方が常に存在する必要があります。クラスターで管理タスクを実行するには、ローカルのUnixドメインソケットを使用して、 postgres ユーザーとして`peer` 認証を介して`postgres` データベースに接続する必要があります。 postgres ユーザーまたは`postgres` データベースは**削除しないでください**。

注釈

CloudNativePGは Kubernetes' native `VolumeSnapshot API <https://github.com/cloudnative-pg/cloudnative-pg/issues/2081>`_ のサポートを段階的に導入しています

バックアップおよびリカバリ操作におけるインクリメンタルおよび差分コピーの場合 - 基になるストレージクラスでサポートされている場合。

Recovery from Volume Snapshot objects を参照してください。

詳細については。

`bootstrap` セクション

bootstrap メソッドは、クラスター仕様のbootstrap セクションで定義できます。 CloudNativePGは現在、次のブートストラップ方法をサポートしています。

initdb 新しいPostgreSQLクラスターを初期化しますデフォルト
recovery 既存のクラスターのベースバックアップから復元し、必要に応じて、使用可能なすべてのWALファイルまたは特定の ポイント・インタイム までを再生することにより、PostgreSQLクラスターを作成します
pg_basebackup ストリーミングレプリケーションプロトコルを介してpg_basebackup を使用して、同じメジャーバージョンの既存のクローンを作成することにより、PostgreSQLクラスターを作成します。Kubernetesの外部からでもデータベースをCloudNativePGに移行する場合に役立ちます。

initdb 方法とは異なり、 recovery とpg_basebackup は両方とも別のクラスターオフラインまたはオンラインに基づいて新しいクラスターを作成し、レプリカクラスターをスピンアップするために使用できます。どちらも外部クラスターの定義に依存します。

CloudNativePGオペレーターが提供するバックアップストレージの組み合わせがいくつかあることを考慮して、各方法のガイダンスについてはバックアップリカバリーを参照してください。

参考

"API reference for the `bootstrap section <リソースタイプ>` を参照してください。

詳細については、

`externalClusters` セクション

externalClusters セクションは、現在の構成に関連付けられている1つ以上のPostgreSQLクラスターを指定するメカニズムを提供します。その主な使用例には次のものが含まれます。

データベースのインポート initdb ブートストラップ方法の一部として、論理バックアップとリストアを介して importation of databases 中に利用する外部ソースを指定します。
クロスリージョンレプリケーション 物理レプリケーションを採用するクロスリージョンPostgreSQLクラスターを定義し、個別のKubernetesクラスターまたは従来のVM/ベアメタル環境に拡張できます。
物理ベースバックアップからの復旧 物理ベースバックアップを参照することにより、PostgreSQLクラスターを完全にまたは特定のポイントインタイムに復旧します。

注釈

進行中の開発は`externalClusters` の機能を拡張して、将来のリリースでの論理レプリケーションやフォーリンサーバーなどの追加のユースケースに対応します。

ブートストラップに関する限り、 externalClusters は、 pg_basebackup メソッドまたはrecovery メソッドのソースPostgreSQLクラスターを定義するために使用できます。外部クラスターには以下が必要です。

オリジンクラスターを識別する名前。 source オプションを介して参照として使用されます
次の少なくとも1つ
- ストリーミング接続に関する情報b_tran_3 リカバリオブジェクトストア に関する情報。これは、以下を含むBarman Cloud互換オブジェクトストアです。
  - WALアーカイブポイントインタイムリカバリーに必要
  - カタログPostgresクラスターの物理ベースバックアップの

注釈

リカバリオブジェクトストアは、通常、 Barman Cloudによって管理されるAWS S3、Azure Blob Storage、またはGoogle Cloud Storageソースです。

ストリーミング接続のみが定義されている場合、ソースはpg_basebackup メソッドに使用できます。リカバリオブジェクトストアのみが定義されている場合、ソースはrecovery メソッドに使用できます。両方が定義されている場合、2つのブートストラップ方法のいずれかを選択できます。

さらに、 pg_basebackup または完全なrecovery ポイントインタイムの場合、クラスターはレプリカクラスターモードの資格があります。これは、クラスターがストリーミングを介して、PostgreSQLのrestore_command を介したWALシッピングを介して、または2つのいずれかを介してソースから継続的にフィードされることを意味します。

参考

"API reference for the `externalClusters section <リソースタイプ>` を参照してください。

詳細については、

パスワードファイル

externalClusters エントリー内でパスワードが指定されるたびに、CloudNativePGは自律的に PostgreSQL password file

その場合、各インスタンスの/controller/external/NAME/pgpass にあります。

このアプローチにより、CloudNativePGは、接続文字列でパスワードを公開せずに、外部サーバーとの接続を安全に確立できます。代わりに、接続はpassfile 接続パラメーターを介して前述のファイルを安全に参照します。

空のクラスターをブートストラップする `initdb`

initdb ブートストラップ方法は、新しいPostgreSQLクラスターをスクラッチから作成するために使用されます。特に指定しない限り、デフォルトのものです。

次の例には、initdb 構成の完全な構造が含まれています。

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-example-initdb
spec:
  instances: 3

  bootstrap:
    initdb:
      database: app
      owner: app
      secret:
        name: app-secret

  storage:
    size: 1Gi

上記のブートストラップの例では、次のことを行います。

PostgreSQLのネイティブinitdb コマンドを使用して、新しいPGDATA フォルダーを作成します
app という名前の 非特権 ユーザーを作成します
app-secret シークレットのパスワードを使用して、後者 app のパスワードを設定します username がowner の同じ名前と一致することを確認します
app ユーザーが所有するapp という名前のデータベースを作成します。

構成パラダイムに関する条約 のおかげで、オペレーターにデフォルトのデータベース名app とデフォルトのアプリケーションユーザー名データベース名と同じを選択させたり、スーパーユーザーとスーパーユーザーの両方の安全なパスワードをランダムに生成したりできます。 PostgreSQLのアプリケーションユーザー。

または、上記の例で説明したように、パスワードを生成し、シークレットとして保存し、PostgreSQLクラスターで使用できます。

提供されたシークレットは、: kubernetes.io/basic-auth の仕様に準拠する必要があります。その結果、シークレットのusername

は、 owner アプリケーションシークレットの場合およびスーパーユーザーのpostgres のいずれかと一致する必要があります。

以下は、basic-auth シークレットの例です。

apiVersion: v1
data:
  username: YXBw
  password: cGFzc3dvcmQ=
kind: Secret
metadata:
  name: app-secret
type: kubernetes.io/basic-auth

アプリケーションデータベースは、アプリケーションデータを保存するために使用するデータベースです。アプリケーションは、アプリケーションデータベースを所有するユーザーでクラスターに接続する必要があります。

重要

追加のユーザーを作成する必要がある場合は、 Declarative database role management を参照してください。

データベース名を指定しない場合、オペレーターは慣例に従ってapp データベースを作成し、 デフォルトのWebhook を使用してクラスター定義に追加します。データベースを所有するユーザーは、代わりにデータベース名をデフォルトにします。

アプリケーションユーザーは、オペレーターによって内部的に使用されず、代わりにスーパーユーザーに依存して、クラスターを目的のステータスに調整します。

`initdb` にオプションを渡す

実際のPostgreSQLデータディレクトリは、 initdb PostgreSQLコマンドの呼び出しを介して作成されます。そのコマンドにカスタムオプションを追加する必要がある場合つまり、テンプレートデータベースに使用されるlocale を変更するか、データチェックサムを追加する場合、次のパラメーターを使用できます。

dataChecksums dataChecksums がtrue に設定されている場合、 CNPGはinitdb の-k オプションを呼び出して、データページのチェックサムを有効にし、I/Oシステムによる破損の検出に役立ちます。それ以外の場合はサイレントデフォルトfalse 。

enabled encoding が値に設定されている場合、CNPGはそれをinitdb の--encoding オプションに渡します。これは、テンプレートデータベースデフォルトUTF8 のエンコードを選択します。

localeCollate localeCollate が値に設定されている場合、CNPGはそれをinitdb の--lc-collate オプションに渡します。このオプションは、

Locale Support で定義されているように、照合順序LC_COLLATE

サブカテゴリを制御します

PostgreSQLドキュメントデフォルトC より。

localeCType localeCType が値に設定されている場合、CNPGはそれをinitdb の--lc-ctype オプションに渡します。このオプションは、

Locale Support で定義されているように、照合順序LC_CTYPE

サブカテゴリを制御します

PostgreSQLドキュメントデフォルトC より。

walSegmentSize walSegmentSize が値に設定されている場合、CNPGはそれをinitdb の--wal-segsize オプションに渡しますデフォルト未設定-16メガバイトとしてPostgreSQLによって定義されています。

注釈

initdb ブートストラップ中にCloudNativePGが実装する2つの唯一のロケールオプションは、 LC_COLLATE および`LC_TYPE` サブカテゴリーを参照します。残りのロケールサブカテゴリは、 lc_messages 、lc_monetary 、lc_numeric 、および`lc_time` パラメーターを使用して、PostgreSQL構成で直接構成できます。

次の例は、データのチェックサムを有効にし、デフォルトのエンコードをLATIN1 に設定します。

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-example-initdb
spec:
  instances: 3

  bootstrap:
    initdb:
      database: app
      owner: app
      dataChecksums: true
      encoding: LATIN1
  storage:
    size: 1Gi

警告

CloudNativePGは、 options サブセクションを使用して、initdb 呼び出しの動作をカスタマイズする別の方法をサポートしています。ただし、オペレーターの動作を壊す可能性のあるオプション`--auth` や`-d` などがあることを考えると、このテクニックは非推奨であり、APIの将来のバージョンから削除されます。

データベースが作成および構成された直後に、1回実行されるクエリのカスタムリストを指定することもできます。これらのクエリーは、 postgres データベースに接続する スーパーユーザー postgres として実行されます。

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-example-initdb
spec:
  instances: 3

  bootstrap:
    initdb:
      database: app
      owner: app
      dataChecksums: true
      localeCollate: en_US
      localeCType: en_US
      postInitSQL:
        - CREATE DATABASE angus
  storage:
    size: 1Gi

警告

クエリーはスーパーユーザーとして実行され、クラスター全体を中断する可能性があるため、 postInitSQL 、postInitApplicationSQL 、および`postInitTemplateSQL` オプションを細心の注意して使用してください。これらのクエリのエラーはブートストラップフェーズを中断し、クラスターは不完全なままになります。

初期化後のクエリの実行

さらに、シークレットおよび/またはデータベースが作成および構成された後に実行されるSQLスクリプトを含むConfigMapsのリストを指定できます。これらのSQLスクリプトは、 superuser ロール postgres を使用して実行され、 initdb セクションで指定されたデータベースに接続されます。

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-example-initdb
spec:
  instances: 3

  bootstrap:
    initdb:
      database: app
      owner: app
      postInitApplicationSQLRefs:
        secretRefs:
        - name: my-secret
          key: secret.sql
        configMapRefs:
        - name: my-configmap
          key: configmap.sql
  storage:
    size: 1Gi

注釈

secretRefs で参照されるSQLスクリプトは、 configMapRefs で参照されるSQLスクリプトよりも前に実行されます。両方のセクションで、 SQLスクリプトはリスト内の順序を尊重して実行されます。 SQLスクリプト内では、各SQLステートメントは PostgreSQL semantics に従ってサーバー上の単一のexecで実行されます。コメントを含めることができますが、 psql のような内部コマンドはできません。

警告

postInitApplicationSQLRefs で指定されたConfigMapsまたはSecrets内のエントリの存在を確認してください。それ以外の場合、ブートストラップは失敗します。これらのSQLファイルのエラーは、ブートストラップフェーズを正常に完了できません。

別のクラスターからのブートストラップ

CloudNativePGは、同じメジャーバージョンの別のクラスターから開始するクラスターのブートストラップを有効にします。この操作は、ストリーミングレプリケーションpg_basebackup を介してソースクラスターに直接接続することにより、または既存の物理的な ベースバックアップ recovery を介して間接的に接続することにより発生します。

ソースクラスターは、 name で識別されるexternalClusters セクションで定義する必要があります。オリジンクラスターと同じname を使用することをお勧めします。

重要

デフォルトでは、 recovery メソッドは`externalClusters` セクションのクラスターの`name` を厳密に使用して、通常サーバーの名前に予約されているオブジェクトストア内のバックアップデータのメインフォルダーを見つけます。 barmanObjectStore.serverName プロパティデフォルトで、外部クラスター定義の`name` の値に割り当てられますを使用して、別のプロパティを指定できます。

バックアップからのブートストラップ `recovery`

バックアップとリカバリーの観点からCloudNativePGオペレーターが提供するいくつかの可能性、方法、および組み合わせを考慮して、: バックアップリカバリーを参照してください。

ライブクラスターからのブートストラップ `pg_basebackup`

pg_basebackup ブートストラップモードでは、有効な ストリーミングレプリケーション接続を介して、既存の*バイナリ互換** PostgreSQLインスタンス ソース の正確な物理コピーとして、新しいクラスター ターゲット を作成できます。ソースインスタンスは、プライマリまたはスタンバイのPostgreSQLサーバーのいずれかです。

この方法の主なユースケースは、Kubernetesの外部またはKubernetes内から別のオペレーターなどからCloudNativePGへの移行によって表されます。

警告

現在の実装では、クローンプロセスが終了し、作成されたクラスターがすぐに起動されるときに、元のPostgreSQLインスタンスの*スナップショット*を作成します。詳細については、以下の現在の制限を参照してください。

recovery ブートストラップ方法の場合と同様、クローン操作が完了すると、オペレーターは最初のインスタンスからターゲットクラスターの所有権を取得します。これには、CloudNativePGで必要ないくつかの構成パラメーターのオーバーライド、スーパーユーザーパスワードのリセット、streaming_replica ユーザーの作成、レプリカの管理などが含まれます。生成されるクラスターは、ソースインスタンスから完全に独立しています。

重要

ターゲットインスタンスとソースインスタンス間のネットワークの構成は、実際のコンテキストと環境に依存するため、CloudNativePGドキュメントの範囲を超えています。

pg_basebackup によって透過的に管理されるターゲットインスタンス上のストリーミングレプリケーションクライアントは、次のいずれかの方法でソースインスタンスで自分自身を認証できます。

ユーザー名/パスワードの認証経由
TLS client certificate 経由

後者は、CloudNativePGによって管理されているソース、またはTLS認証用に構成されているソースに接続する場合に推奨されるものです。ただし、最初のオプションは、一般にPostgreSQLサーバーへの最も一般的な認証形式であり、ソースインスタンスがKubernetes外部の従来の環境にある場合、最も簡単な方法になる可能性があります。両方の場合について以下に説明します。

要件

pg_basebackup ブートストラップ方法には、次の要件が適用されます。

ターゲットとソースは同じハードウェアアーキテクチャである必要があります
ターゲットとソースは同じメジャーPostgreSQLバージョンである必要があります
ターゲットとソースは同じテーブルスペースを持つ必要があります
バックアップ用に少なくとも1つの walsender とWALストリーミング用に1つを提供することにより、この一回限りのオペレーションのターゲットからのアクセスを許可するために、十分なmax_wal_senders でソースを構成する必要があります
ターゲットインスタンスがソースインスタンスのPostgreSQLポートに接続できるように、ソースとターゲット間のネットワークを構成する必要があります
ソースにはREPLICATION LOGIN 特権を持つロールが必要で、pg_hba.conf でこのロールのターゲットインスタンスからの接続を受け入れる必要があります、できればTLSを介して下記のレプリケーションユーザーについてを参照してください
ターゲットは、REPLICATION LOGIN 特権を持つロールを使用してソースPostgreSQLインスタンスに正常に接続できる必要があります

参考

詳細については、 Planning 、 pg_basebackup を参照してください。

High Availability, Load Balancing, and Replication

PostgreSQLドキュメント。

レプリケーションユーザーについて

要件セクションで説明したように、ソースインスタンスにSUPERUSER または、できればREPLICATION 特権のみを持つユーザーが必要です。

ソースデータベースがCloudNativePGで作成されている場合、 streaming_replica ユーザーを再利用し、クライアントTLS証明書認証を利用できます。デフォルトでは、streaming_replica に許可される唯一の接続方法です。

Kubernetesの外部を含む他のすべての場合、 REPLICATION 特権を持つユーザーが既に存在することを確認するか、以下の手順に従って新しいユーザーを作成してください。

ソースシステムのpostgres ユーザーとして、次を実行してください。

createuser -P --replication streaming_replica

ターゲットインスタンスのシークレットに追加する必要があるため、プロンプトにパスワードを入力し、後で保存します。

注釈

名前は重要ではありませんが、簡単にするために`streaming_replica` を使用します。以下のセクションの指示を調整する場合、必要に応じて変更してください。

ユーザー名/パスワードの認証

pg_basebackup ブートストラップを使用してCloudNativePGでサポートされている最初の認証方法は、ユーザー名とパスワードの一致に基づいています。

手順を開始する前に、次の情報があることを確認してください。

ホスト名またはIPアドレスとTCPポートで識別されるソースインスタンスの場所
レプリケーションユーザー名簡単にするためにstreaming_replica
パスワード

次のような行をソースPostgreSQLインスタンスのpg_hba.conf ファイルに追加する必要がある場合があります。

#  A more restrictive rule for TLS and IP of origin is recommended

host replication streaming_replica all md5

次のマニフェストは、 pg_basebackup ブートストラップ方法を使用して、 source-db externalClusters 配列内で定義された外部PostgreSQLクラスターのクローンを作成します。ご覧のとおり、source-db 定義はsource-db.foo.com ホストをポイントし、streaming_replica ユーザーとして接続します。そのパスワードはsource-db-replica-user シークレットのpassword キーに保存されます。

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: target-db
spec:
  instances: 3
  imageName: ghcr.io/cloudnative-pg/postgresql:16.1

  bootstrap:
    pg_basebackup:
      source: source-db

  storage:
    size: 1Gi

  externalClusters:
  - name: source-db
    connectionParameters:
      host: source-db.foo.com
      user: streaming_replica
    password:
      name: source-db-replica-user
      key: password

クローン操作が機能するには、同じPostgreSQLバージョンこの場合は16.1を含むすべての要件を満たす必要があります。

TLS証明書認証

pg_basebackup ブートストラップを使用してCloudNativePGでサポートされている2番目の認証方法は、TLSクライアント証明書に基づいています。これは、セキュリティの観点から推奨されるアプローチです。

次の例では、同じKubernetesクラスター内の既存のPostgreSQLクラスターcluster-example のクローンを作成します。

注釈

この例は、Kubernetesクラスターの外部にあるインスタンスをカバーするように簡単に適合できます。

マニフェストは、 cluster-clone-tls と呼ばれる新しいPostgreSQL 16.1クラスターを定義します。これは、 cluster-example 外部クラスターからpg_basebackup メソッドを使用してブートストラップされます。ホストは同じクラスター内の読み取り/書き込みサービスによって識別され、 streaming_replica ユーザーは、提供されたキー、証明書、および認証局情報それぞれcluster-example-replication およびcluster-example-ca シークレットのおかげで認証されます。

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-clone-tls
spec:
  instances: 3
  imageName: ghcr.io/cloudnative-pg/postgresql:16.1

  bootstrap:
    pg_basebackup:
      source: cluster-example

  storage:
    size: 1Gi

  externalClusters:
  - name: cluster-example
    connectionParameters:
      host: cluster-example-rw.default.svc
      user: streaming_replica
      sslmode: verify-full
    sslKey:
      name: cluster-example-replication
      key: tls.key
    sslCert:
      name: cluster-example-replication
      key: tls.crt
    sslRootCert:
      name: cluster-example-ca
      key: ca.crt
``` #### アプリケーションデータベースの構成

また、`initdb` および`recovery` ブートストラップ方法の場合と同様に、ライブクラスターからブートストラップするクラスターのアプリケーションデータベースの構成もサポートしています。新しいクラスターがレプリカクラスターとしてレプリカモードが有効化されて作成される場合、アプリケーションデータベースの構成はスキップされます。

次の例では、ライブクラスターからブートストラップした後、指定されたシークレット`app-secret` のパスワードを使用してアプリケーションデータベース`app` を構成します。

```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
[...]
spec:
  bootstrap:
    pg_basebackup:
      database: app
      owner: app
      secret:
        name: app-secret
      source: cluster-example

上記の構成では、復旧が完了すると次が発生します。

データベース app が存在しない場合、新しいデータベース app が作成されます。
ユーザーapp が存在しない場合、新しいユーザーapp が作成されます。
ユーザー app がデータベースの所有者でない場合、ユーザー app はデータベース app の所有者として付与されます。
username の値がシークレットのowner の値と一致する場合、アプリケーションデータベースのパスワードはシークレットのpassword の値に変更されます。

重要

レプリカモードが有効になっているレプリカクラスターの場合、オペレーターはPostgreSQLインスタンスにデータベースまたはユーザーを作成しません。これらは元のクラスターからリカバリされるためです。

現在の制限

スナップショットコピー

pg_basebackup メソッドは、PostgreSQLベースバックアップの形式でソースインスタンスのスナップショットを取得します。バックアップの開始からバックアップの適切な終了までに書き込まれるすべてのトランザクションは、2番目の接続を使用してターゲットインスタンスにストリーミングされます pg_basebackup の--wal-method=stream オプションを参照してください。

バックアップが完了すると、新しいインスタンスが新しいタイムラインで起動され、ソースから分岐します。このため、Kubernetesのターゲットデータベースに移行する前に、ソースデータベースへのすべての書き込み操作を停止することをお勧めします。

重要

移行を試行する前に、プロシージャとアプリケーションの両方をテストする必要があります。特に、必要なだけ移行手順を実行して、運用中のアプリケーションのダウンタイムを体系的に測定することが重要です。

Bootstrap

bootstrap セクション

externalClusters セクション