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

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

警告

ALTER SYSTEM クエリを使用して、命令的方法でPostgreSQLインスタンスの構成を変更しないでください。通常、オペレーターによって制御されるオプションの一部を変更すると、実際にクラスターの予測不能/回復不能な状態が発生する可能性があります。さらに、 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 ファイルで始まり、これらの設定が自動的に追加されます。

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メジャーバージョンに依存するデフォルトパラメーター

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

  • 固定パラメーター

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

dynamic_shared_memory_type = posix
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_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
archive_mode = on
full_page_writes = on
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
wal_level = logical
wal_log_hints = on

固定パラメーターは最後に追加されるため、ユーザーがYAML構成を介してオーバーライドすることはできません。これらのパラメーターは、正しいWALアーカイブとレプリケーションに必要です。

レプリケーション設定

primary_conninfo 、restore_command 、およびrecovery_target_timeline パラメーターは、クラスター内のインスタンスの状態に応じて、オペレーターによって自動的に管理されます。

primary_conninfo = host=cluster-example-rw user=postgres dbname=postgres
recovery_target_timeline = latest

ログ制御設定

オペレーターは、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 のようなテンプレートデータベースも含まれています。

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 の有効化

拡張機能は、クエリのリアルタイムモニタリングのために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 の透過的かつネイティブサポートを備えています。詳細については、

PGAuditログ を参照してください。

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

yaml #postgresql

パラメーター pgaudit.log: “all, -misc” pgaudit.log_catalog: “off” pgaudit.log_parameter: “on” pgaudit.log_relation: “on” #

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
hostssl replication streaming_replica all cert

デフォルトルール

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
hostssl replication streaming_replica all cert

<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バージョン1.22以降では、デフォルト構成では、新しいPostgresクラスターでのALTER SYSTEM の使用が無効になっています。この決定は、このコマンドに関連する潜在的なリスクの認識に基づいています。 ALTER SYSTEM の使用を有効にするには、.spec.postgresql.enableAlterSystem をtrue に明示的に設定します。

警告

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

.spec.postgresql.enableAlterSystem がfalse として構成されている場合、 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_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

  • full_page_writes

  • 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

  • wal_level

  • wal_log_hints