PostgreSQL Configuration ======================== 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.k8s.enterprisedb.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 .. Warning:: **OpenShiftユーザー** OpenShiftユーザーインターフェイスの現在の制限により、 YAMLペインからのみPostgreSQL設定を変更できます。 ``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ドキュメントを参照してください。 EDB 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:`Logical Replication ` を参照してください。 レプリケーションスロットも継続的バックアップも設定されていない場合、 ``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:`JSON形式のPostgreSQLエラーメッセージの標準出力ログ ` を参照してください。 共有プリロードライブラリ ^^^^^^^^^^^^^^^^^^^^^^^^ PostgreSQLの\ ``shared_preload_libraries`` オプションは、サーバー起動時にコンマ区切りリストの形式でプリロードされる1つ以上の共有ライブラリを指定するために存在します。通常、PostgreSQLで使用され、システム全体のほとんどのデータベースセッションで使用する必要がある拡張機能がロードされます\ ``pg_stat_statements`` など。 EDB CloudNativePGクラスターでは、 ``shared_preload_libraries`` オプションはデフォルトで空です。 ``shared_preload_libraries`` のコンテンツをオーバーライドすることはできますが、熟練したPostgresユーザーのみがこのオプションを利用することをお勧めします。 .. Important:: 指定されたライブラリが見つからない場合、サーバーは起動に失敗し、EDB CloudNativePGクラスターは自己修復を試行できず、手動介入が必要です。コンテンツを直接管理する予定がある場合は、 `shared_preload_libraries` の拡張機能と設定の両方を常にテストしてください。 EDB CloudNativePGクラスターは、最も使用される一部のPostgreSQL拡張機能の\ ``shared_preload_libraries`` オプションのコンテンツを自動的に管理できます。詳細については、以下の :ref:`マネージド拡張機能 <マネージド拡張機能>` セクションを参照してください。 具体的には、構成パラメーターに管理ライブラリのいずれかが必要であることにオペレーターが気づくと、必要なライブラリが自動的に追加されます。オペレーターは、実際のパラメーターが必要としないとすぐにライブラリを削除します。 .. Important:: `shared_preload_libraries` からライブラリを削除するには、クラスター内のすべてのインスタンスを再起動する必要があることに常に注意してください。 文字列のリストとして、\ ``.spec.postgresql.shared_preload_libraries`` を介して追加の\ ``shared_preload_libraries`` を提供できます。オペレーターは、それらを自動的に管理するものとマージします。 マネージド拡張機能 ^^^^^^^^^^^^^^^^^^ 前のセクションで予想されたように、EDB CloudNativePGクラスターは、いくつかのよく知られサポートされている拡張機能の\ ``shared_preload_libraries`` のコンテンツを自動的に管理します。現在のリストには以下が含まれます。 - ``auto_explain`` - ``pg_stat_statements`` - ``pgaudit`` - ``pg_failover_slots`` これらのライブラリの一部は、使用する前にデータベース内の追加オブジェクトも必要とします。通常は、データベースで実行する\ ``CREATE EXTENSION`` コマンドを介して管理されるビューおよび/またはファンクションです。通常、\ ``DROP EXTENSION`` コマンドはこれらのオブジェクトを削除します。 このようなライブラリの場合、EDB 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ロギング機能を介して詳細なセッションおよび/またはオブジェクト監査ログを提供します。 EDB CloudNativePGクラスターは、PostgreSQLクラスターで `PGAudit `_ の透過的かつネイティブサポートを備えています。詳細については、 :ref:``pgaudit` の有効化 <`pgaudit` の有効化>` を参照してください。 次の例の抜粋のように、\ ``pgaudit.`` で始まるパラメーターを構成に追加することにより、\ ``pgaudit`` を有効にできます。 .. code:: yaml # postgresql: parameters: pgaudit.log: "all, -misc" pgaudit.log_catalog: "off" pgaudit.log_parameter: "on" pgaudit.log_relation: "on" # #### Enabling `pg_failover_slots` The [`pg_failover_slots`](https://github.com/EnterpriseDB/pg_failover_slots) extension by EDB ensures that logical replication slots can survive a failover scenario. Failovers are normally implemented using physical streaming replication, like in the case of EDB CloudNativePG Cluster. You can enable `pg_failover_slots` by adding to the configuration a parameter that starts with `pg_failover_slots.`: as explained above, the operator will transparently manage the `pg_failover_slots` entry in the `shared_preload_libraries` option depending on this. Please refer to [`the `pg_failover_slots` documentation`](/pg_extensions/pg_failover_slots) for details on this extension. Additionally, for each database that you intend to you use with `pg_failover_slots` you need to add an entry in the `pg_hba` section that enables each replica to connect to the primary. For example, suppose that you want to use the `app` database with `pg_failover_slots`, you need to add this entry in the `pg_hba` section: ``` yaml postgresql: pg_hba: - hostssl appstreaming_replica all cert The ``pg_hba`` section ---------------------- ``pg_hba`` is a list of PostgreSQL Host Based Authentication rules used to create the ``pg_hba.conf`` used by the pods. !!! Important See the PostgreSQL documentation for `more information on ``pg_hba.conf`` `__. Since the first matching rule is used for authentication, the ``pg_hba.conf`` file generated by the operator can be seen as composed of four sections: 1. Fixed rules 2. User-defined rules 3. Optional LDAP section 4. Default rules Fixed rules: \``\` テキストローカル すべて すべて ピア hostssl postgresストリーミング_replica all cert hostsslレプリケーションstreaming_replica all cert hostssl all cnp_pooler_pgbouncer all cert :: Default rules: ``` text host all all all From PostgreSQL 14 the default value of the ``password_encryption`` database parameter is set to ``scram-sha-256``. Because of that, the default authentication method is ``scram-sha-256`` from this PostgreSQL version. PostgreSQL 13 and older will use ``md5`` as the default authentication method. The resulting ``pg_hba.conf`` will look like this: \``\` テキストローカル すべて すべて ピア hostssl postgresストリーミング_replica all cert hostsslレプリケーションstreaming_replica all cert host all all all scram-sha-256 #またはPostgreSQLバージョン<= 13の場合はmd5 edb_notranlate_13 yaml postgresql: pg_hba: - hostssl app app 10.244.0.0/16 md5 :: In the above example we are enabling access for the `app` user to the `app` database using MD5 password authentication (you can use `scram-sha-256` if you prefer) via a secure channel (`hostssl`). ### LDAP Configuration Under the `postgres` section of the cluster spec there is an optional `ldap` section available to define an LDAP configuration to be converted into a rule added into the `pg_hba.conf` file. This will support two modes: `simple bind` mode which requires specifying a `server`, `prefix` and `suffix` in the LDAP section and the `search+bind` mode which requires specifying `server`, `baseDN`, `binDN`, and a `bindPassword` which is a secret containing the ldap password. Additionally, in `search+bind` mode you have the option to specify a `searchFilter` or `searchAttribute`. If no `searchAttribute` is specified the default one of `uid` will be used. Additionally, both modes allow the specification of a `scheme` for ldapscheme and a `port`. Neither scheme nor port are required, however. This section filled out for search+bind could look as follows: ``` 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' The ``pg_ident`` section ------------------------ ``pg_ident`` is a list of PostgreSQL User Name Maps that EDB CloudNativePG Cluster uses to generate and maintain the ident map file (known as ``pg_ident.conf``) inside the data directory. !!! Important See the PostgreSQL documentation for `more information on ``pg_ident.conf`` `__. The ``pg_ident.conf`` file written by the operator is made up of the following two sections: 1. Fixed rules 2. User-defined rules Currently the only fixed rule, automatically generated by the operator, is: \``\` text local postgres :: The instance manager detects the user running the PostgreSQL instance and automatically adds a rule to map it to the `postgres` user in the database. If the `postgres` user is not properly configured inside the container, the instance manager will allow any local user to connect and then log a warning message like the following: ``` text 現在のユーザーを識別できません。安全でないマッピングへのフォールバック。 The resulting ``pg_ident.conf`` will look like this: \``\` text local postgres edb_notranlate_18 yaml postgresql: pg_ident: - “mymap /^(.\*)@mydomain\\.com$ \\1” :: ## Changing configuration You can apply configuration changes by editing the `postgresql` section of the `Cluster` resource. After the change, the cluster instances will immediately reload the configuration to apply the changes. If the change involves a parameter requiring a restart, the operator will perform a rolling upgrade. ## Enabling `ALTER SYSTEM` EDB CloudNativePG Cluster strongly advocates employing the Cluster manifest as the exclusive method for altering the configuration of a PostgreSQL cluster. This approach guarantees coherence across the entire high-availability cluster and aligns with best practices for Infrastructure-as-Code. In EDB CloudNativePG Cluster the default configuration disables the use of `ALTER SYSTEM` on new Postgres clusters. This decision is rooted in the recognition of potential risks associated with this command. To enable the use of `ALTER SYSTEM`, you can explicitly set `.spec.postgresql.enableAlterSystem` to `true`. !!! Warning Proceed with caution when utilizing `ALTER SYSTEM`. This command operates directly on the connected instance and does not undergo replication. EDB CloudNativePG Cluster assumes responsibility for certain fixed parameters and complete control over others, emphasizing the need for careful consideration. Starting from PostgreSQL 17, the `.spec.postgresql.enableAlterSystem` setting directly controls the [`allow_alter_system` GUC in PostgreSQL](https://www.postgresql.org/docs/17/runtime-config-compatible.html#GUC-ALLOW-ALTER-SYSTEM) — a feature directly contributed by EDB CloudNativePG Cluster to PostgreSQL. Prior to PostgreSQL 17, when `.spec.postgresql.enableAlterSystem` is set to `false`, the `postgresql.auto.conf` file is made read-only. Consequently, any attempt to execute the `ALTER SYSTEM` command will result in an error. The error message might look like this: ```出力エラー ファイル"postgresql.auto.conf"を開くことができませんでした。アクセスが拒否されました Dynamic Shared Memory settings ------------------------------ PostgreSQL supports a few implementations for dynamic shared memory management through the ```dynamic_shared_memory_type`` `__ configuration option. In EDB CloudNativePG Cluster we recommend to limit ourselves to any of the following two values: - ``posix``: which relies on POSIX shared memory allocated using ``shm_open`` (default setting) - ``sysv``: which is based on System V shared memory allocated via ``shmget`` In PostgreSQL, this setting is particularly important for memory allocation in parallel queries. For details, please refer to this `thread from the ``pgsql-general`` mailing list `__. POSIX shared memory ^^^^^^^^^^^^^^^^^^^ The default setting of ``posix`` should be enough in most cases, considering that the operator automatically mounts a *memory-bound ``EmptyDir`` volume* called ``shm`` under ``/dev/shm``. You can verify the size of such volume inside the running Postgres container with: ``sh mount |`` .. _dynamic-shared-memory-settings-1: Dynamic Shared Memory settings ------------------------------ PostgreSQL supports a few implementations for dynamic shared memory management through the ```dynamic_shared_memory_type`` `__ configuration option. In EDB CloudNativePG Cluster we recommend to limit ourselves to any of the following two values: - ``posix``: which relies on POSIX shared memory allocated using ``shm_open`` (default setting) - ``sysv``: which is based on System V shared memory allocated via ``shmget`` In PostgreSQL, this setting is particularly important for memory allocation in parallel queries. For details, please refer to this `thread from the ``pgsql-general`` mailing list `__. .. _posix-shared-memory-1: POSIX shared memory ^^^^^^^^^^^^^^^^^^^ The default setting of ``posix`` should be enough in most cases, considering that the operator automatically mounts a *memory-bound ``EmptyDir`` volume* called ``shm`` under ``/dev/shm``. You can verify the size of such volume inside the running Postgres container with: \``\` grep shm :: You should get something similar to the following output: ``` console shm on /dev/shm type tmpfs (rw,nosuid,nodev,noexec,relatime,size= **** **) edb_notranlate_22 yaml spec エフェメラルボリュームサイズ制限 shm 1Gi System V shared memory ^^^^^^^^^^^^^^^^^^^^^^ In case your Kubernetes cluster has a high enough value for the ``SHMMAX`` and ``SHMALL`` parameters, you can also set: \``\` yaml Dynamic_shared_memory_type: “sysv” \``\` You can check the ``SHMMAX``/``SHMALL`` from inside a PostgreSQL container, by running: \``\` sh ipcs -lm edb_notranlate_25 console —— 共有メモリ制限 ——– 最大セグメント数 = 4096 最大セグメントサイズキロバイト = 18014398509465599 最大合計共有メモリキロバイト = 18014398509481980 最小セグメントサイズバイト = 1 edb_notranlate_26 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`` - ``edb_audit`` - ``edb_audit_destination`` - ``edb_audit_directory`` - ``edb_audit_filename`` - ``edb_audit_rotation_day`` - ``edb_audit_rotation_seconds`` - ``edb_audit_rotation_size`` - ``edb_audit_tag`` - ``edb_log_every_bulk_value`` - ``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``