PostgreSQLの構成 ================ PostgreSQLに慣れているユーザーは、インスタンスを構成するための次の3つのファイルの存在に気づいています。 - postgresql.conf PostgreSQLのメインランタイム構成ファイル - pg_hba.conf クライアント認証ファイル - pg_ident.conf 外部ユーザーを内部ユーザーにマッピング PostgreSQLコンテナの宣言的構成と不変性の概念により、ユーザーはこれらのファイルに直接触れることはできません。 parameters 、 pg_hba 、および pg_ident キーを介してカスタム postgresql.conf 、 pg_hba.conf 、および pg_ident.conf 設定を定義することにより、 Cluster リソース定義の postgresql セクションから構成が可能です。 これらの設定は、すべてのインスタンスで同じです。 .. Warning:: ALTER SYSTEM クエリを使用して、命令的方法でPostgreSQLインスタンスの構成を変更しないでください。通常、オペレーターによって制御されるオプションの一部を変更すると、実際にクラスターの予測不能/回復不能な状態が発生する可能性があります。さらに、 ALTER SYSTEM` の変更はクラスター全体でレプリケートされません。詳細については、以下の :ref:`Enabling ALTER SYSTEM <#enabling-alter-system>` を参照してください。 カスタム設定の使用に関するリファレンスはサンプルに含まれています。以下を参照してください。 :: apiVersion: postgresql.cnpg.io/v1 kind: Cluster metadata: name: cluster-example-custom spec: instances: 3 # Parameters and pg_hba configuration will be append # to the default ones to make the cluster work postgresql: parameters: max_worker_processes: "60" pg_hba: # To access through TCP/IP you will need to get username # and password from the secret cluster-example-custom-app - host all all all md5 # Example of rolling update strategy: # - unsupervised: automated update of the primary once all # replicas have been upgraded (default) # - supervised: requires manual supervision to perform # the switchover of the primary primaryUpdateStrategy: unsupervised # Require 1Gi of space per instance using default storage class storage: size: 1Gi postgresql セクション ------------------------- ポッド内のPostgreSQLインスタンスは、デフォルトの postgresql.conf ファイルで始まり、これらの設定が自動的に追加されます。 .. code:: text listen_addresses = * include custom.conf custom.conf ファイルには、次の例にあるように、 postgresql セクションのユーザー定義設定が含まれます。 .. code:: yaml # ... postgresql: parameters: shared_buffers: "1GB" # ... .. Seealso:: GUC Grand Unified Configurationとしても知られる `more information on the available parameters `_ のPostgreSQLドキュメントを参照してください。 CloudNativePGはPostgreSQLパラメーターの文字列のみを受け入れることに注意してください。 custom.conf のコンテンツは、次のセクションをこの順序で適用することにより、オペレーターによって自動的に生成および維持されます。 - グローバルデフォルトパラメーター - PostgreSQLメジャーバージョンに依存するデフォルトパラメーター - ユーザー指定パラメーター - 固定パラメーター **グローバルデフォルトパラメーター** は次のとおりです。 .. code:: text archive_mode = on dynamic_shared_memory_type = posix full_page_writes = on logging_collector = on log_destination = csvlog log_directory = /controller/log log_filename = postgres log_rotation_age = 0 log_rotation_size = 0 log_truncate_on_rotation = false max_parallel_workers = 32 max_replication_slots = 32 max_worker_processes = 32 shared_memory_type = mmap # for PostgreSQL >= 12 only wal_keep_size = 512MB # for PostgreSQL >= 13 only wal_keep_segments = 32 # for PostgreSQL <= 12 only wal_level = logical wal_log_hints = on wal_sender_timeout = 5s wal_receiver_timeout = 5s .. Warning:: PostgreSQLクラスターでのWALセグメント保持を計画し、予想および観察されたワークロードに基づいて、サーバーバージョンに応じてwal_keep_size またはwal_keep_segments` を適切に構成するのはあなたの義務です。 また、唯一のストリーミングレプリケーションクライアントが高可用性クラスターで実行されているレプリカインスタンスである場合、クラスターレベルでレプリケーションスロットのサポートを追加するレプリケーションスロット機能を利用できます。 `replicationSlots.highAvailability ` オプション詳細については、 :ref:`レプリケーションユーザーについて <レプリケーションユーザーについて>` を参照してください。レプリケーションスロットも継続的バックアップも設定せずに、 `wal_keep_size ` または `wal_keep_segments ` を構成することが、スタンバイを同期外れから保護する唯一の方法です。スタンバイが同期が外れると、 `"could not receive data from WAL stream: ERROR: requested WAL segment **** **** **** **** **** **** has already been removed" ` のようなエラーメッセージが生成されます。これには、 `PGDATA ` の一部、またはWALファイルの保存専用のボリュームを専用にして、ストリーミングレプリケーションの目的で古いWALセグメントを保持する必要があります。 次のパラメーターは **固定** で、オペレーターによって排他的に制御されます。 .. code:: text archive_command = /controller/manager wal-archive %p hot_standby = true listen_addresses = * port = 5432 restart_after_crash = false ssl = on ssl_ca_file = /controller/certificates/client-ca.crt ssl_cert_file = /controller/certificates/server.crt ssl_key_file = /controller/certificates/server.key unix_socket_directories = /controller/run 固定パラメーターは最後に追加されるため、ユーザーがYAML構成を介してオーバーライドすることはできません。これらのパラメーターは、正しいWALアーカイブとレプリケーションに必要です。 レプリケーション設定 ^^^^^^^^^^^^^^^^^^^^ `primary_conninfo ` 、 `restore_command ` 、および `recovery_target_timeline ` パラメーターは、クラスター内のインスタンスの状態に応じて、オペレーターによって自動的に管理されます。 .. code:: text primary_conninfo = host=cluster-example-rw user=postgres dbname=postgres recovery_target_timeline = latest ログ制御設定 ^^^^^^^^^^^^ オペレーターは、CSV形式でログを出力するためにPostgreSQLを必要とし、インスタンスマネージャーは自動的にそれを解析し、JSON形式で出力します。このため、PostgreSQLのすべてのログ設定は固定され、変更できません。 詳細については、 :ref:`ロギング <ロギング>` を参照してください。 共有プリロードライブラリ ^^^^^^^^^^^^^^^^^^^^^^^^ PostgreSQLの `shared_preload_libraries ` オプションは、サーバー起動時にコンマ区切りリストの形式でプリロードされる1つ以上の共有ライブラリを指定するために存在します。通常、PostgreSQLで使用され、システム全体のほとんどのデータベースセッションで使用する必要がある拡張機能がロードされます `pg_stat_statements ` など。 CloudNativePGでは、 `shared_preload_libraries ` オプションはデフォルトで空です。 `shared_preload_libraries ` のコンテンツをオーバーライドすることはできますが、熟練したPostgresユーザーのみがこのオプションを利用することをお勧めします。 .. Important:: 指定されたライブラリが見つからない場合、サーバーは起動に失敗し、CloudNativePGの自己修復の試行を妨げ、手動介入が必要になります。コンテンツを直接管理する予定がある場合は、 `shared_preload_libraries` の拡張機能と設定の両方を常にテストしてください。 CloudNativePGは、最も使用される一部のPostgreSQL拡張機能の `shared_preload_libraries ` オプションのコンテンツを自動的に管理できます。詳細については、以下の :ref:`マネージド拡張機能 <マネージド拡張機能>` セクションを参照してください。 具体的には、構成パラメーターに管理ライブラリのいずれかが必要であることにオペレーターが気づくと、必要なライブラリが自動的に追加されます。オペレーターは、実際のパラメーターが必要としないとすぐにライブラリを削除します。 .. Important:: `shared_preload_libraries` からライブラリを削除するには、クラスター内のすべてのインスタンスを再起動する必要があることに常に注意してください。 文字列のリストとして、 `.spec.postgresql.shared_preload_libraries ` を介して追加の `shared_preload_libraries ` を提供できます。オペレーターは、それらを自動的に管理するものとマージします。 マネージド拡張機能 ^^^^^^^^^^^^^^^^^^ 前のセクションで予想されたように、CloudNativePGは、一部のよく知られサポートされている拡張機能の `shared_preload_libraries ` のコンテンツを自動的に管理します。現在のリストには以下が含まれます。 - `auto_explain ` - `pg_stat_statements ` - `pgaudit ` - `pg_failover_slots ` これらのライブラリの一部は、使用する前にデータベース内の追加オブジェクトも必要とします。通常は、データベースで実行する `CREATE EXTENSION ` コマンドを介して管理されるビューおよび/またはファンクションです。通常、 `DROP EXTENSION ` コマンドはこれらのオブジェクトを削除します。 このようなライブラリの場合、CloudNativePGは、次のクエリーで識別されるクラスター内の接続を受け入れるすべてのデータベースでの拡張機能の作成と削除を自動的に処理します。 .. code:: sql SELECT datname FROM pg_database WHERE datallowconn .. Note:: 上記のクエリーには、`template1` のようなテンプレートデータベースも含まれています。 `auto_explain ` の有効化 ^^^^^^^^^^^^^^^^^^^^^^^^^ `auto_explain `_ 拡張機能は、 `EXPLAIN ` を手動で実行することなく、遅いステートメントの実行プランを自動的にログに記録する手段を提供します最適化されていないクエリーを追跡するのに役立ちます。 次の抜粋例のように `auto_explain. ` で始まるパラメーターを構成に追加することにより、 `auto_explain ` を有効にできます。完了までに10秒以上かかるクエリの実行プランを自動的にログに記録します。 .. code:: yaml # ... postgresql: parameters: auto_explain.log_min_duration: "10s" # ... .. Note:: auto_explainを有効にすると、パフォーマンスの問題が発生する可能性があります。 `the auto explain documentation `_ を参照してください。 `pg_stat_statements ` の有効化 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `pg_stat_statements `_ 拡張機能は、クエリのリアルタイムモニタリングのためにPostgreSQLで使用可能な最も重要な機能の1つです。 次の例の抜粋のように、 `pg_stat_statements. ` で始まるパラメーターを構成に追加することにより、 `pg_stat_statements ` を有効にできます。 .. code:: yaml # ... postgresql: parameters: pg_stat_statements.max: "10000" pg_stat_statements.track: all # ... 前述のように、オペレーターは `pg_stat_statements ` を `shared_preload_libraries ` に自動的に追加し、各データベースで `CREATE EXTENSION IF NOT EXISTS pg_stat_statements ` を実行します。これにより、 `pg_stat_statements ` ビューに対してクエリーを実行できます。 `pgaudit ` の有効化 ^^^^^^^^^^^^^^^^^^^^ `pgaudit ` 拡張機能は、標準のPostgreSQLロギング機能を介して詳細なセッションおよび/またはオブジェクト監査ログを提供します。 CloudNativePGは、PostgreSQLクラスターで `PGAudit `_ の透過的かつネイティブサポートを備えています。詳細については、 :ref:`PG監査ログ ` を参照してください。 次の例の抜粋のように、 `pgaudit. ` で始まるパラメーターを構成に追加することにより、 `pgaudit ` を有効にできます。 .. code:: yaml # postgresql: parameters: pgaudit.log: "all, -misc" pgaudit.log_catalog: "off" pgaudit.log_parameter: "on" pgaudit.log_relation: "on" # `pg_failover_slots ` の有効化 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `pg_failover_slots `_ EDBによる拡張機能により、論理レプリケーションスロットがフェールオーバーシナリオでも生き残ることができます。フェールオーバーは、CloudNativePGの場合と同様、物理的ストリーミングレプリケーションを使用して実装されます。 `pg_failover_slots. ` で始まるパラメーターを構成に追加することにより、 `pg_failover_slots ` を有効にできます。上記で説明したように、オペレーターは、これに応じて `shared_preload_libraries ` オプションの `pg_failover_slots ` エントリーを透過的に管理します。 `the `_ を参照してください。 この拡張機能の詳細については、 さらに、 `pg_failover_slots ` で使用するデータベースごとに、各レプリカがプライマリに接続できるようにする `pg_hba ` セクションにエントリを追加する必要があります。たとえば、 `app ` データベースを `pg_failover_slots ` で使用する場合、次のエントリを `pg_hba ` セクションに追加する必要があります。 .. code:: yaml postgresql: pg_hba: - hostssl app streaming_replica all cert `pg_hba ` セクション --------------------- `pg_hba ` は、ポッドが使用する `pg_hba.conf ` を作成するために使用されるPostgreSQLホストベースの認証ルールのリストです。 .. Important:: `more information on `pg_hba.conf` `_ については、PostgreSQLドキュメントを参照してください。 最初に一致するルールが認証に使用されるため、オペレーターによって生成された `pg_hba.conf ` ファイルは4つのセクションで構成されていると考えられます。 1. 固定ルール 2. ユーザー定義のルール 3. オプションのLDAPセクション 4. デフォルトルール 固定ルール .. code:: text local all all peer hostssl postgres streaming_replica all cert hostssl replication streaming_replica all cert hostssl all cnpg_pooler_pgbouncer all cert デフォルトルール .. code:: text host all all all PostgreSQL 14から、 `password_encryption ` データベースパラメーターのデフォルト値は `scram-sha-256 ` に設定されます。そのため、このPostgreSQLバージョンからのデフォルトの認証方法は `scram-sha-256 ` です。 PostgreSQL 13以前では、デフォルトの認証方法として `md5 ` を使用します。 結果の `pg_hba.conf ` は次のようになります。 .. code:: text local all all peer hostssl postgres streaming_replica all cert hostssl replication streaming_replica all cert host all all all scram-sha-256 # (or md5 for PostgreSQL version <= 13) クラスターマニフェスト内では、次の抜粋にあるように、 `pg_hba ` 行が `.spec.postgresql.pg_hba ` のリスト項目として追加されます。 .. code:: yaml postgresql: pg_hba: - hostssl app app 10.244.0.0/16 md5 上記の例では、安全なチャネル `hostssl ` を介してMD5パスワード認証必要に応じて `scram-sha-256 ` を使用して、 `app ` ユーザーの `app ` データベースへのアクセスを有効にしています。 LDAP構成 ^^^^^^^^ クラスター仕様の `postgres ` セクションの下には、 `pg_hba.conf ` ファイルに追加されるルールに変換するLDAP構成を定義するオプションの `ldap ` セクションがあります。 これは、2つのモードをサポートします。LDAPセクションで `server ` 、 `prefix ` 、および `suffix ` を指定する必要がある `simple bind ` モードと、 `server ` 、 `baseDN ` 、 `binDN ` 、およびldapパスワードを含むシークレットである `bindPassword ` を指定する必要がある `search+bind ` モード。さらに、 `search+bind ` モードでは、 `searchFilter ` または `searchAttribute ` を指定するオプションがあります。 `searchAttribute ` が指定されていない場合、 `uid ` のデフォルトの14が使用されます。 さらに、両方のモードで、 ldapschemeの `scheme ` と `port ` の指定ができます。ただし、スキームもポートも必要ありません。 search+bindのために入力されたこのセクションは次のようになります。 .. code:: yaml postgresql: ldap: server: "openldap.default.svc.cluster.local" bindSearchAuth: baseDN: "ou=org,dc=example,dc=com" bindDN: "cn=admin,dc=example,dc=com" bindPassword: name: "ldapBindPassword" key: "data" searchAttribute: "uid" `pg_ident ` セクション ----------------------- `pg_ident ` は、CloudNativePGがデータディレクトリ内のidentマップファイル `pg_ident.conf ` と呼ばれるを生成および維持するために使用するPostgreSQLユーザー名マップのリストです。 .. Important:: `more information on `pg_ident.conf` `_ については、PostgreSQLドキュメントを参照してください。 オペレーターが書き込んだ `pg_ident.conf ` ファイルは、次の2つのセクションで構成されています。 1. 固定ルール 2. ユーザー定義のルール 現在、オペレーターによって自動的に生成される唯一の固定ルールは次のとおりです。 .. code:: text local postgres インスタンスマネージャーは、PostgreSQLインスタンスを実行しているユーザーを検出し、データベースの `postgres ` ユーザーにマップするルールを自動的に追加します。 `postgres ` ユーザーがコンテナ内で適切に構成されていない場合、インスタンスマネージャーはローカルユーザーの接続を許可し、次のような警告メッセージをログに記録します。 .. code:: text Unable to identify the current user. Falling back to insecure mapping. 結果の `pg_ident.conf ` は次のようになります。 .. code:: text local postgres クラスターマニフェスト内で、 `pg_ident ` 行が `.spec.postgresql.pg_ident ` のリスト項目として追加されます。例 .. code:: yaml postgresql: pg_ident: - "mymap /^(.*)@mydomain .com$ 1" 構成の変更 ---------- `Cluster ` リソースの `postgresql ` セクションを編集することにより、構成変更を適用できます。 変更後、クラスターインスタンスはすぐに構成をリロードして変更を適用します。変更に再起動が必要なパラメーターが含まれる場合、オペレーターはローリングアップグレードを実行します。 `ALTER SYSTEM ` の有効化 ------------------------- CloudNativePGは、PostgreSQLクラスターの構成を変更するための排他的な方法として、クラスターマニフェストを使用することを強くお勧めします。このアプローチは、高可用性クラスター全体の一貫性を保証し、インフラストラクチャ・アズ・コードのベストプラクティスと連携しています。 CloudNativePGでは、デフォルト構成により、新しいPostgresクラスターで `ALTER SYSTEM ` の使用が無効になっています。この決定は、このコマンドに関連する潜在的なリスクの認識に基づいています。 `ALTER SYSTEM ` の使用を有効にするには、 `.spec.postgresql.enableAlterSystem ` を `true ` に明示的に設定します。 .. Warning:: `ALTER SYSTEM` を利用するときは注意してください。このコマンドは、接続されたインスタンスで直接動作し、レプリケーションは行いません。 CloudNativePGは、特定の固定パラメーターに対する責任とその他の完全な制御を引き受け、注意深い検討の必要性を強調します。 PostgreSQL 17以降、 `.spec.postgresql.enableAlterSystem ` 設定は `allow_alter_system `_ を直接制御します — CloudNativePGによってPostgreSQLに直接提供された機能。 PostgreSQL 17より前では、 `.spec.postgresql.enableAlterSystem ` が `false ` に設定されている場合、 `postgresql.auto.conf ` ファイルは読み取り専用になります。したがって、 `ALTER SYSTEM ` コマンドを実行しようとするとエラーになります。エラーメッセージは次のようになります。 .. code:: output ERROR: could not open file "postgresql.auto.conf": Permission denied 動的共有メモリ設定 ------------------ PostgreSQLは、 `dynamic_shared_memory_type `_ を介した動的共有メモリ管理のいくつかの実装をサポートしています 構成オプション。 CloudNativePGでは、次の2つの値のいずれかに制限することをお勧めします。 - `posix ` `shm_open ` デフォルト設定を使用して割り当てられたPOSIX共有メモリに依存します - `sysv ` `shmget ` を介して割り当てられたSystem V共有メモリに基づいています PostgreSQLでは、この設定はパラレルクエリーでのメモリ割り当てにとって特に重要です。詳細は、 `thread from the `pgsql-general` mailing list `_ を参照してください。 POSIX共有メモリ ^^^^^^^^^^^^^^^ オペレーターが `/dev/shm ` の下に `shm ` と呼ばれるメモリバインドの `EmptyDir ` volume_を自動的にマウントすることを考慮すると、ほとんどの場合、 `posix ` のデフォルト設定で十分です。次の方法で、実行中のPostgresコンテナ内のこのようなボリュームのサイズを確認できます。 .. code:: sh mount | grep shm 次の出力のようなものを取得するはずです。 .. code:: console shm on /dev/shm type tmpfs (rw,nosuid,nodev,noexec,relatime,size= **** **) `shm ` ボリュームの最大サイズを設定する場合は、 `Cluster ` リソースの `.spec.ephemeralVolumesSizeLimit.shm ` フィールドを設定することにより設定できます。例 .. code:: yaml spec: ephemeralVolumesSizeLimit: shm: 1Gi System V共有メモリ ^^^^^^^^^^^^^^^^^^ Kubernetesクラスターの `SHMMAX ` および `SHMALL ` パラメーターの十分な値がある場合、次のことを設定することもできます。 .. code:: yaml dynamic_shared_memory_type: "sysv" 次のコマンドを実行して、PostgreSQLコンテナ内から `SHMMAX ` / `SHMALL ` を確認できます。 .. code:: sh ipcs -lm 例 .. code:: console - ----- Shared Memory Limits -------- max number of segments = 4096 max seg size (kbytes) = 18014398509465599 max total shared memory (kbytes) = 18014398509481980 min seg size (bytes) = 1 ご覧のとおり、 `max total shared memory ` の数が非常に多いため、 `dynamic_shared_memory_type ` を `sysv ` に設定することをお勧めします。 別の方法は次を実行することです。 .. code:: sh cat /proc/sys/kernel/shmall cat /proc/sys/kernel/shmmax 固定パラメーター ---------------- 一部のPostgreSQL構成パラメーターは、オペレーターが排他的に管理する必要があります。オペレーターは、ユーザーがWebhookを使用してそれらを設定できないようにします。 ユーザーは `postgresql ` セクションで次の構成パラメーターを設定することはできません。 - `allow_alter_system ` - `allow_system_table_mods ` - `archive_cleanup_command ` - `archive_command ` - `archive_mode ` - `bonjour ` - `bonjour_name ` - `cluster_name ` - `config_file ` - `data_directory ` - `data_sync_retry ` - `event_source ` - `external_pid_file ` - `hba_file ` - `hot_standby ` - `ident_file ` - `jit_provider ` - `listen_addresses ` - `log_destination ` - `log_directory ` - `log_file_mode ` - `log_filename ` - `log_rotation_age ` - `log_rotation_size ` - `log_truncate_on_rotation ` - `logging_collector ` - `port ` - `primary_conninfo ` - `primary_slot_name ` - `promote_trigger_file ` - `recovery_end_command ` - `recovery_min_apply_delay ` - `recovery_target ` - `recovery_target_action ` - `recovery_target_inclusive ` - `recovery_target_lsn ` - `recovery_target_name ` - `recovery_target_time ` - `recovery_target_timeline ` - `recovery_target_xid ` - `restart_after_crash ` - `restore_command ` - `shared_preload_libraries ` - `ssl ` - `ssl_ca_file ` - `ssl_cert_file ` - `ssl_crl_file ` - `ssl_dh_params_file ` - `ssl_ecdh_curve ` - `ssl_key_file ` - `ssl_passphrase_command ` - `ssl_passphrase_command_supports_reload ` - `ssl_prefer_server_ciphers ` - `stats_temp_directory ` - `synchronous_standby_names ` - `syslog_facility ` - `syslog_ident ` - `syslog_sequence_numbers ` - `syslog_split_messages ` - `unix_socket_directories ` - `unix_socket_group ` - `unix_socket_permissions `