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 セクションから構成が可能です。

これらの設定は、すべてのインスタンスで同じです。

警告

ALTER SYSTEM クエリを使用して、命令的方法でPostgreSQLインスタンスの構成を変更しないでください。通常、オペレーターによって制御されるオプションの一部を変更すると、実際にクラスターの予測不能/回復不能な状態が発生する可能性があります。さらに、 ALTER SYSTEM の変更はクラスター全体でレプリケートされません。詳細については、以下の Enabling ALTER SYSTEM を参照してください。

カスタム設定の使用に関するリファレンスはサンプルに含まれています。

cluster-example-custom.yaml を参照してください。

postgresql セクション

ポッド内のPostgreSQLインスタンスは、デフォルトのpostgresql.conf ファイルで始まり、これらの設定が自動的に追加されます。

listen_addresses = *
include custom.conf

custom.conf ファイルには、次の例にあるように、postgresql セクションのユーザー定義設定が含まれます。

# ...
postgresql:
  parameters:
    shared_buffers: "1GB"
# ...

注釈

GUC Grand Unified Configurationとしても知られる more information on the available parameters のPostgreSQLドキュメントを参照してください。 CloudNativePGはPostgreSQLパラメーターの文字列のみを受け入れることに注意してください。

custom.conf のコンテンツは、次のセクションをこの順序で適用することにより、オペレーターによって自動的に生成および維持されます。

  • グローバルデフォルトパラメーター

  • PostgreSQLメジャーバージョンに依存するデフォルトパラメーター

  • ユーザー指定パラメーター

  • 固定パラメーター

グローバルデフォルトパラメーター は次のとおりです。

archive_timeout = 5min
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
shared_preload_libraries =
ssl_max_protocol_version = TLSv1.3
ssl_min_protocol_version = TLSv1.3
wal_keep_size = 512MB
wal_level = logical
wal_log_hints = on
wal_sender_timeout = 5s
wal_receiver_timeout = 5s

警告

PostgreSQLクラスターでのWALセグメント保持を計画し、予想および観察されたワークロードに基づいて、サーバーバージョンに応じて`wal_keep_size` または`wal_keep_segments` を適切に構成するのはあなたの義務です。

また、唯一のストリーミングレプリケーションクライアントが高可用性クラスターで実行されているレプリカインスタンスである場合、クラスターレベルでレプリケーションスロットのサポートを追加するレプリケーションスロット機能を利用できます。 replicationSlots.highAvailability オプションを使用して機能を有効にできます。詳細については、 レプリケーションユーザーについて を参照してください。

レプリケーションスロットも継続的バックアップも設定されていない場合、 wal_keep_size またはwal_keep_segments の構成がスタンバイを同期外れから保護する唯一の方法です。スタンバイが同期から外れると、"could not receive data from WAL stream: ERROR: requested WAL segment  ****  ****  ****  ****  ****  ****  has already been removed" のようなエラーメッセージが生成されます。これには、 PGDATA の一部、またはWALファイルの保存専用のボリュームを専用にして、ストリーミングレプリケーションの目的で古いWALセグメントを保持する必要があります。

次のパラメーターは 固定 で、オペレーターによって排他的に制御されます。

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アーカイブとレプリケーションに必要です。

先行書き込みログレベル

wal_level

PostgreSQLのパラメーターは、先行書き込みログWALに書き込まれる情報の量を決定します。次の値を受け入れます。

  • minimal クラッシュリカバリーに必要な情報のみを書き込みます。

  • replica スタンバイインスタンスで読み取り専用クエリを実行する機能など、WALアーカイブとストリーミングレプリケーションをサポートするための十分な情報を追加します。

  • logical replica からのすべての情報に加えて、論理デコードとレプリケーションに必要な追加情報が含まれます。

デフォルトでは、上流のPostgreSQLはwal_level をreplica に設定します。 CloudNativePGは、代わりに、デフォルトでwal_level をlogical に設定して、すぐに論理レプリケーションを有効にします。これにより、外部のPostgreSQLサーバーからの移行などのユースケースのサポートが簡単になります。

クラスターが論理レプリケーションを必要としない場合は、wal_level をreplica に設定して、WALボリュームとオーバーヘッドを削減することをお勧めします。

最後に、CloudNativePGでは、WALアーカイブが無効になっているシングルインスタンスクラスターに限り、 wal_level をminimal に設定できます。

レプリケーション設定

primary_conninfo 、restore_command 、およびrecovery_target_timeline パラメーターは、クラスター内のインスタンスのロールに基づいて、オペレーターによって自動的に管理されます。これらのパラメーターは、インスタンスがレプリカとして動作している場合にのみ有効に適用されます。

primary_conninfo = host=<PRIMARY> user=postgres dbname=postgres tcp_user_timeout=5000
recovery_target_timeline = latest

注釈

デフォルトでは、上記のように、すべてのスタンバイは`tcp_user_timeout` を**5秒**に設定します。このパラメータは、TCP接続が強制的に閉じられるまでに、送信されたデータが未確認のままでいられる時間を定義します。これを調整することにより、スタンバイがネットワークの問題にどれくらいの速さで反応するかを制御できます。デフォルト値が要件を満たさない場合は、 STANDBY_TCP_USER_TIMEOUT を使用してオペレーターが管理するすべてのスタンバイでそれをオーバーライドできます。 tcp_user_timeout の詳細については、 PostgreSQL documentation を参照してください。

ログ制御設定

オペレーターは、CSV形式でログを出力するためにPostgreSQLを必要とし、インスタンスマネージャーは自動的にそれを解析し、JSON形式で出力します。その結果、 固定パラメーター にリストされている特定のPostgreSQLログ設定は固定され、変更できません。

詳細については、 ロギング を参照してください。

共有プリロードライブラリ

PostgreSQLのshared_preload_libraries オプションは、サーバー起動時にコンマ区切りリストの形式でプリロードされる1つ以上の共有ライブラリを指定するために存在します。通常、PostgreSQLで使用され、システム全体のほとんどのデータベースセッションで使用する必要がある拡張機能がロードされますpg_stat_statements など。

CloudNativePGでは、shared_preload_libraries オプションはデフォルトで空です。 shared_preload_libraries のコンテンツをオーバーライドすることはできますが、熟練したPostgresユーザーのみがこのオプションを利用することをお勧めします。

注釈

指定されたライブラリが見つからない場合、サーバーは起動に失敗し、CloudNativePGの自己修復の試行を妨げ、手動介入が必要になります。コンテンツを直接管理する予定がある場合は、 shared_preload_libraries の拡張機能と設定の両方を常にテストしてください。

CloudNativePGは、最も使用される一部のPostgreSQL拡張機能のshared_preload_libraries オプションのコンテンツを自動的に管理できます。詳細については、以下の マネージド拡張機能 セクションを参照してください。

具体的には、構成パラメーターに管理ライブラリのいずれかが必要であることにオペレーターが気づくと、必要なライブラリが自動的に追加されます。オペレーターは、実際のパラメーターが必要としないとすぐにライブラリを削除します。

注釈

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は、次のクエリーで識別されるクラスター内の接続を受け入れるすべてのデータベースでの拡張機能の作成と削除を自動的に処理します。

SELECT datname FROM pg_database WHERE datallowconn

注釈

上記のクエリーには、template1 のようなテンプレートデータベースも含まれています。

注釈

declarative extensions の導入により

Database CRDでは、拡張機能を直接管理できるようになりました。その結果、マネージド拡張機能はCloudNativePGの将来のバージョンで重要な変更が発生する可能性があり、一部の機能は非推奨になる可能性があります。

auto_explain の有効化

auto_explain

拡張機能は、 EXPLAIN を手動で実行することなく、遅いステートメントの実行プランを自動的にログに記録する手段を提供します最適化されていないクエリーを追跡するのに役立ちます。

次の抜粋例のようにauto_explain. で始まるパラメーターを構成に追加することにより、auto_explain を有効にできます。完了までに10秒以上かかるクエリの実行プランを自動的にログに記録します。

# ...
postgresql:
  parameters:
    auto_explain.log_min_duration: "10s"
# ...

注釈

auto_explainを有効にすると、パフォーマンスの問題が発生する可能性があります。 the auto explain documentation を参照してください。

pg_stat_statements の有効化

pg_stat_statements

拡張機能は、クエリのリアルタイムモニタリングのためにPostgreSQLで使用可能な最も重要な機能の1つです。

次の例の抜粋のように、pg_stat_statements. で始まるパラメーターを構成に追加することにより、pg_stat_statements を有効にできます。

# ...
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 の透過的かつネイティブサポートを備えています。詳細については、 PG監査ログ を参照してください。

次の例の抜粋のように、pgaudit. で始まるパラメーターを構成に追加することにより、pgaudit を有効にできます。

#
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 セクションに追加する必要があります。

postgresql:
  pg_hba:
    - hostssl app streaming_replica all cert

pg_hba セクション

pg_hba は、ポッドが使用するpg_hba.conf を作成するために使用されるPostgreSQLホストベースの認証ルールのリストです。

注釈

more information on `pg_hba.conf <https://www.postgresql.org/docs/current/auth-pg-hba-conf.html>`_ については、PostgreSQLドキュメントを参照してください。

最初に一致するルールが認証に使用されるため、オペレーターによって生成されたpg_hba.conf ファイルは4つのセクションで構成されていると考えられます。

  1. 固定ルール

  2. ユーザー定義のルール

  3. オプションのLDAPセクション

  4. デフォルトルール

固定ルール

local all all peer

hostssl postgres streaming_replica all cert map=cnpg_streaming_replica
hostssl replication streaming_replica all cert map=cnpg_streaming_replica
hostssl all cnpg_pooler_pgbouncer all cert map=cnpg_pooler_pgbouncer

デフォルトルール

host all all all <default-authentication-method>

PostgreSQL 14から、 password_encryption データベースパラメーターのデフォルト値はscram-sha-256 に設定されます。そのため、このPostgreSQLバージョンからのデフォルトの認証方法はscram-sha-256 です。

PostgreSQL 13以前では、デフォルトの認証方法としてmd5 を使用します。

結果のpg_hba.conf は次のようになります。

local all all peer

hostssl postgres streaming_replica all cert map=cnpg_streaming_replica
hostssl replication streaming_replica all cert map=cnpg_streaming_replica
hostssl all cnpg_pooler_pgbouncer all cert map=cnpg_pooler_pgbouncer

<user defined rules>
<user defined LDAP>

host all all all scram-sha-256 # (or md5 for PostgreSQL version <= 13)

クラスターマニフェスト内では、次の抜粋にあるように、 pg_hba 行が.spec.postgresql.pg_hba のリスト項目として追加されます。

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のために入力されたこのセクションは次のようになります。

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ユーザー名マップのリストです。

注釈

more information on `pg_ident.conf <https://www.postgresql.org/docs/current/auth-username-maps.html>`_ のPostgreSQLドキュメントを参照してください。

オペレーターが書き込んだpg_ident.conf ファイルは、次の2つのセクションで構成されています。

  1. 固定ルール

  2. ユーザー定義のルール

現在、オペレーターによって自動的に生成される唯一の固定ルールは次のとおりです。

local <postgres system user> postgres

インスタンスマネージャーは、PostgreSQLインスタンスを実行しているユーザーを検出し、データベースのpostgres ユーザーにマップするルールを自動的に追加します。

postgres ユーザーがコンテナ内で適切に構成されていない場合、インスタンスマネージャーはローカルユーザーの接続を許可し、次のような警告メッセージをログに記録します。

Unable to identify the current user. Falling back to insecure mapping.

結果のpg_ident.conf は次のようになります。

local <postgres system user> postgres

<user defined lines>

クラスターマニフェスト内で、 pg_ident 行が.spec.postgresql.pg_ident のリスト項目として追加されます。例

postgresql:
  pg_ident:
    - "mymap /^(.*)@mydomain\.com$ \1"

構成の変更

Cluster リソースのpostgresql セクションを編集することにより、構成変更を適用できます。

変更後、クラスターインスタンスはすぐに構成をリロードして変更を適用します。変更に再起動が必要なパラメーターが含まれる場合、オペレーターはローリングアップグレードを実行します。

ALTER SYSTEM の有効化

CloudNativePGは、PostgreSQLクラスターの構成を変更するための排他的な方法として、クラスターマニフェストを使用することを強くお勧めします。このアプローチは、高可用性クラスター全体の一貫性を保証し、インフラストラクチャ・アズ・コードのベストプラクティスと連携しています。

CloudNativePGでは、デフォルト構成により、新しいPostgresクラスターでALTER SYSTEM の使用が無効になっています。この決定は、このコマンドに関連する潜在的なリスクの認識に基づいています。 ALTER SYSTEM の使用を有効にするには、.spec.postgresql.enableAlterSystem をtrue に明示的に設定します。

警告

ALTER SYSTEM を利用するときは注意してください。このコマンドは、接続されたインスタンスで直接動作し、レプリケーションは行いません。 CloudNativePGは、特定の固定パラメーターに対する責任とその他の完全な制御を引き受け、注意深い検討の必要性を強調します。

PostgreSQL 17以降、.spec.postgresql.enableAlterSystem 設定は allow_alter_system を直接制御します

— CloudNativePGによってPostgreSQLに直接提供された機能。

PostgreSQL 17より前では、 .spec.postgresql.enableAlterSystem がfalse に設定されている場合、 postgresql.auto.conf ファイルは読み取り専用になります。したがって、ALTER SYSTEM コマンドを実行しようとするとエラーになります。エラーメッセージは次のようになります。

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 <https://www.postgresql.org/message-id/CA%2BhUKGJOj7qzDLxeFPVvto8YEWop6FSQoTYPO9Z6Ee%3Di-nPS_Q%40mail.gmail.com>`_ を参照してください。

POSIX共有メモリ

オペレーターが/dev/shm の下にshm と呼ばれる メモリバインドの``EmptyDir`` ボリューム を自動的にマウントすることを考慮すると、ほとんどの場合、 posix のデフォルト設定で十分です。次の方法で、実行中のPostgresコンテナ内のこのようなボリュームのサイズを確認できます。

mount | grep shm

次の出力のようなものを取得するはずです。

shm on /dev/shm type tmpfs (rw,nosuid,nodev,noexec,relatime,size= **** **)

shm ボリュームの最大サイズを設定する場合は、 Cluster リソースの.spec.ephemeralVolumesSizeLimit.shm フィールドを設定することにより設定できます。例

spec:
  ephemeralVolumesSizeLimit:
    shm: 1Gi

System V共有メモリ

KubernetesクラスターのSHMMAX およびSHMALL パラメーターの十分な値がある場合、次のことを設定することもできます。

dynamic_shared_memory_type: "sysv"

次のコマンドを実行して、PostgreSQLコンテナ内からSHMMAX /SHMALL を確認できます。

ipcs -lm

例

- ----- 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 に設定することをお勧めします。

別の方法は次を実行することです。

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