Patroni と PostgreSQL の高可用性etcd

パート 2: インストールと構成

xdev.asia_

目標

このレッスンを終えると、次のことができるようになります:

• ファイルの各セクションを詳しく理解する patroni.yml
• ブートストラップを構成するオプション
• HA 用の PostgreSQL パラメーターの調整
• 認証とセキュリティの構成
• タグと制約の使用
• タイミング パラメーターの最適化

1。 Patroni 構成の概要_

1.1。構成レイヤー

Patroni には多くの構成レイヤーがあります:

┌─────────────────────────────────────┐
│   1. Command line arguments         │ (Highest priority)
│      patroni --config-file=...      │
├─────────────────────────────────────┤
│   2. Environment variables          │
│      PATRONI_SCOPE=postgres         │
├─────────────────────────────────────┤
│   3. Configuration file             │
│      /etc/patroni/patroni.yml       │
├─────────────────────────────────────┤
│   4. DCS (Dynamic configuration)    │
│      Stored in etcd                 │
└─────────────────────────────────────┘
↓
Merged configuration

優先順位: コマンド ライン > ;環境＞設定ファイル > DCS

1.2。静的構成と動的構成

静的構成(patroni.yml):

• ノード固有の設定 (名前、アドレス)
• etcd 接続情報
• データ ディレクトリ、bin ディレクトリ
• 変更を適用するには再起動が必要

動的構成_ (DCS 内):

• PostgreSQL パラメーター
• ブートストラップ設定_
• TTL、loop_wait、 retry_timeout
• ランタイムを更新できます: patronictl edit-config

2。セクション: スコープと名前空間

2.1。スコープ (クラスター名)

scope: postgres

Scope は、DCS 内のクラスターの一意の名前です。

Italy意味:

• 同じクラスタ内のすべてのノードは同じでなければなりません スコープ_
• 接頭辞が付いている DCS キースコープ:/service/postgres/...
• 同じ etcd クラスター上で複数のクラスターを許可_

Best実践_:

# Development
scope: postgres-dev

Staging
scope: postgres-staging
Production
scope: postgres-prod
Multi-tenant
scope: customer1-postgres
scope: customer2-postgres

2.2。名前空間

namespace: /service/

名前空間 は、DCS のすべてのキーのプレフィックスです。

完全な DCS キー構造:

/service/postgres/leader
/service/postgres/members/node1
/service/postgres/config

複数のクラスターの例:

/service/postgres-prod/leader
/service/postgres-staging/leader
/application/myapp-db/leader

3。セクション: ノード情報_

3.1。ノード名_

name: node1

要件:

• クラスター内で一意
• ブートストラップ後の定数
• ホスト名または FQDN を使用します

例: c発明:

# Simple
name: node1
name: node2
name: node3

With datacenter
name: dc1-node1
name: dc2-node1
With role hint (not recommended)
name: pg-primary-01   # ❌ Role changes
name: pg-db-01        # ✅ Better

3.2。ホスト情報

# Optional: Override hostname
host: 10.0.1.11

Patroni はホスト名を自動的に検出しますが、必要に応じて上書きできます。

4。セクション: REST API

4.1。基本構成

restapi:
listen: 0.0.0.0:8008
connect_address: 10.0.1.11:8008

パラメータ:

• listen: バインド用のインターフェイスとポート (0.0.0.0 = すべてインターフェース)
• connect_address: 他のノードが接続に使用するアドレス

4.2。認証_

restapi:
listen: 0.0.0.0:8008
connect_address: 10.0.1.11:8008
authentication:
username: admin
password: secret_password

認証はどのような場合に必要ですか?:

• REST API 公開インターネット
• コンプライアンス要件_
• マルチテナント環境

curl と併用:

curl -u admin:secret_password http://10.0.1.11:8008/

4.3。 SSL/TLS_

restapi:
listen: 0.0.0.0:8008
connect_address: 10.0.1.11:8008
certfile: /etc/patroni/ssl/server.crt
keyfile: /etc/patroni/ssl/server.key
cafile: /etc/patroni/ssl/ca.crt
verify_client: required  # none, optional, required

自己署名証明書の生成:

# CA
openssl genrsa -out ca.key 4096
openssl req -new -x509 -days 3650 -key ca.key -out ca.crt

Server certificate
openssl genrsa -out server.key 4096
openssl req -new -key server.key -out server.csr
openssl x509 -req -days 365 -in server.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out server.crt

4.4。 REST API エンドポイント_

ヘルスチェックエンドポイント:

# General health
GET /health

Returns: 200 if healthy, 503 if not
Primary check
GET /primary
GET /master  # deprecated
Returns: 200 if primary, 503 if not
Replica check
GET /replica
Returns: 200 if replica, 503 if primary or unhealthy
Read-only check (replica or sync standby)
GET /read-only
Returns: 200 if can serve reads
Synchronous standby check
GET /synchronous
GET /sync
Returns: 200 if synchronous standby

管理エンドポイント_:

# Restart PostgreSQL
POST /restart

Reload configuration
POST /reload
Reinitialize
POST /reinitialize

5。セクション: ブートストラップ_

5.1。 DCS 設定_

bootstrap:
dcs:
ttl: 30
loop_wait: 10
retry_timeout: 10
maximum_lag_on_failover: 1048576
maximum_lag_on_syncnode: 1048576
synchronous_mode: false
synchronous_mode_strict: false

TTL (Time To Live):

ttl: 30  # seconds

• リーダー ロックの有効期限
• リーダーが TTL で更新されない場合→ ロックの有効期限が切れます_
• トレードオフ:
  • _ 低 TTL (10 秒): 高速フェイルオーバーですが、誤ったリスク陽性_
  • 高 TTL (60 秒): より安定していますが、時間がかかります。ダウンタイム_
• 推奨__HTMLTAG_272___: 30秒_

loop_wait:

loop_wait: 10  # seconds

• ヘルスチェックの間隔
• リーダーがロックを更新する_loop_wait 秒
• 推奨: 10 秒 (1/3) TTL)

retry_timeout:

retry_timeout: 10  # seconds

• DCS 操作のタイムアウト
• DCS がタイムアウト以内に応答しない場合は → 検討してください失敗
• 推奨: 10秒_

フェイルオーバー時の最大ラグ:

maximum_lag_on_failover: 1048576  # bytes (1MB)

• プロモーションの対象となる最大レプリケーション ラグ
• ラグのあるレプリカ>閾値は賢明だろうg がプライマリとして選択されます
• 0 = 制限なし(任意のレプリカを昇格可能)
• 推奨: データ損失ゼロの場合は 1MB設定

synchronous_mode___HTMLTAG_325__ _:

synchronous_mode: false
synchronous_mode_strict: false

• false: 非同期レプリケーション(デフォルト)
• true: 同期レプリケーションを有効にする
• synchronous_mode_strict: 厳密同期モード (同期しない場合は書き込みなし)スタンバイ)

5.2。 PostgreSQL ブートストラップ パラメーター

bootstrap:
dcs:
postgresql:
use_pg_rewind: true
use_slots: true
parameters:
# Replication
wal_level: replica
hot_standby: "on"
wal_keep_size: "1GB"
max_wal_senders: 10
max_replication_slots: 10
wal_log_hints: "on"

    # Archiving (optional)
    archive_mode: "on"
    archive_timeout: 300
    archive_command: "cp %p /var/lib/postgresql/18/archive/%f"
    
    # Performance
    shared_buffers: "2GB"
    effective_cache_size: "6GB"
    maintenance_work_mem: "512MB"
    checkpoint_completion_target: 0.9
    wal_buffers: "16MB"
    default_statistics_target: 100
    random_page_cost: 1.1
    effective_io_concurrency: 200
    work_mem: "16MB"
    min_wal_size: "1GB"
    max_wal_size: "4GB"
    max_worker_processes: 4
    max_parallel_workers_per_gather: 2
    max_parallel_workers: 4
    max_parallel_maintenance_workers: 2

use_pg_rewind:

use_pg_rewind: true

• 自動リカバリを有効にするpg_rewind
• クラスター再参加時の迅速なリカバリ
• 必須: wal_log_hints = on データチェックサム

use_slots:HTMLTAG_362__CODEBLOCK_24

• 動的レプリケーションスロットを自分で作成
• レプリカ時の WAL 削除の防止ラグ_
• 推奨: true

5.3。 initdb オプション

bootstrap:
initdb:
- encoding: UTF8
- locale: en_US.UTF-8
- data-checksums
- auth-host: scram-sha-256
- auth-local: peer

共通オプション:

• encoding: 文字エンコーディング (UTF8)推奨)
• locale: システム ロケール
• data-checksums: ページ チェックサムを有効にする (検出)破損)
• auth-host: ホスト接続のデフォルトの認証方法_
• auth-local: ローカルのデフォルトの認証方法接続_

注: initdb ブートストラップ クラスターがヘッドの時間に達した場合にのみ実行されます。

5.4。 pg_hba 構成

bootstrap:
pg_hba:
# Local connections
- local all all peer
- local all all md5

# Localhost
- host all all 127.0.0.1/32 scram-sha-256
- host all all ::1/128 scram-sha-256

# Replication connections
- host replication replicator 10.0.1.11/32 scram-sha-256
- host replication replicator 10.0.1.12/32 scram-sha-256
- host replication replicator 10.0.1.13/32 scram-sha-256

# Application connections
- host all all 10.0.1.0/24 scram-sha-256

# Allow from specific app servers
- host myapp myapp_user 10.0.2.0/24 scram-sha-256

ベスト プラクティス:

• ✅ scram-sha-256 (最も安全)
• ✅ 特定の IP アドレス/サブネット
• ✅ 目的ごとにユーザーを分離
• ❌ trust メソッド
• ❌0.0.0.0/0 を避けてください。必須_

5.5。靴のタスク

application: アプリケーション データベース ユーザー

monitoring: Prometheus エクスポータ、 etc_

replication: Patroni_

5.6 によってすでに処理されています。ブートストラップ後スクリプト

bootstrap:
post_bootstrap: /etc/patroni/scripts/post_bootstrap.sh
post_init: /etc/patroni/scripts/post_init.sh

post_bootstrap: ブートストラップ クラスタの後に実行 (プライマリのみ) post_init: 初期化後に実行データベース

スクリプト例 (/etc/patroni/scripts/post_bootstrap.sh):

#!/bin/bash

Create extensions
psql -U postgres -c "CREATE EXTENSION IF NOT EXISTS pg_stat_statements;"
psql -U postgres -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;"
Create databases
psql -U postgres -c "CREATE DATABASE myapp;"
Grant permissions
psql -U postgres -d myapp -c "GRANT ALL ON SCHEMA public TO myapp;"

6。セクション: PostgreSQL

6.1。接続設定

postgresql:
listen: 0.0.0.0:5432
connect_address: 10.0.1.11:5432
proxy_address: 10.0.1.100:5432  # Optional: VIP address

listen: リッスンする PostgreSQL のインターフェースconnect_address: レプリケーション用のアドレス接続proxy_address: 仮想 IP (HAProxy、pgBouncer)

6.2。データおよびバイナリ ディレクトリ_

postgresql:
data_dir: /var/lib/postgresql/18/data
bin_dir: /usr/lib/postgresql/18/bin
config_dir: /etc/postgresql/18/main  # Optional
pgpass: /var/lib/postgresql/.pgpass  # Optional

Note:

• data_dir: 保存データベースfiles
• bin_dir: PostgreSQL バイナリ (psql、pg_ctl など) を保存する場所
• config_dir: 構成ファイルが他の場所にある場合data_dir_

6.3.認証_

postgresql:
authentication:
replication:
username: replicator
password: replicator_password

superuser:
  username: postgres
  password: postgres_password

rewind:
  username: rewind_user
  password: rewind_password

replication: ストリーミング レプリケーションのユーザーsuperuser: 管理に使用する Patroni PostgreSQL rewind: pg_rewind のユーザー (オプション、スーパーユーザーを使用可能)

セキュリティのベストプラクティス: パスワードを環境変数またはシークレットに保存するマネージャー。

6.4。ランタイムパラメータ

postgresql:
parameters:
# Connection
max_connections: 200
superuser_reserved_connections: 3

# Memory
shared_buffers: "4GB"              # 25% of RAM
effective_cache_size: "12GB"       # 50-75% of RAM
maintenance_work_mem: "1GB"
work_mem: "20MB"

# WAL
wal_buffers: "16MB"
min_wal_size: "2GB"
max_wal_size: "8GB"
wal_compression: "on"

# Checkpoints
checkpoint_timeout: "15min"
checkpoint_completion_target: 0.9

# Query planning
default_statistics_target: 100
random_page_cost: 1.1              # SSD
effective_io_concurrency: 200      # SSD

# Parallel query
max_worker_processes: 8
max_parallel_workers_per_gather: 4
max_parallel_workers: 8
max_parallel_maintenance_workers: 4

# Logging
log_line_prefix: "%t [%p]: [%l-1] user=%u,db=%d,app=%a,client=%h "
log_checkpoints: "on"
log_connections: "on"
log_disconnections: "on"
log_lock_waits: "on"
log_temp_files: 0
log_autovacuum_min_duration: 0

# Auto-vacuum
autovacuum: "on"
autovacuum_max_workers: 3
autovacuum_naptime: "10s"

# Locale
lc_messages: "en_US.UTF-8"
lc_monetary: "en_US.UTF-8"
lc_numeric: "en_US.UTF-8"
lc_time: "en_US.UTF-8"

# Extensions
shared_preload_libraries: "pg_stat_statements"

メモリサイジングガイド:

Total RAM: 16GB

shared_buffers: 4GB (25%)
effective_cache_size: 12GB (75%)
maintenance_work_mem: 1GB
work_mem: 20MB × max_connections = 4GB max

6.5。追加の pg_hba エントリ

postgresql:
pg_hba:
# Additional entries beyond bootstrap
- hostssl all all 10.0.3.0/24 scram-sha-256
- host replication replicator 10.0.4.0/24 scram-sha-256

bootstrap.pg_hba.

6.6 のエントリと結合します。コールバック スクリプト

postgresql:
callbacks:
on_reload: /etc/patroni/scripts/on_reload.sh
on_restart: /etc/patroni/scripts/on_restart.sh
on_role_change: /etc/patroni/scripts/on_role_change.sh
on_start: /etc/patroni/scripts/on_start.sh
on_stop: /etc/patroni/scripts/on_stop.sh

on_role_change の例:

#!/bin/bash

/etc/patroni/scripts/on_role_change.sh
ROLE=$1  # 'master' or 'replica'
CLUSTER=$2
LEADER=$3
if [ "$ROLE" = "master" ]; then
echo "$(date): Promoted to PRIMARY" >> /var/log/patroni/role_changes.log
# Update HAProxy
curl -X POST http://haproxy:9999/update

# Send notification
curl -X POST https://slack.webhook.url \
  -d "{\"text\": \"PostgreSQL node promoted to PRIMARY\"}"

else
echo "$(date): Demoted to REPLICA" >> /var/log/patroni/role_changes.log
fi

6.7。カスタム構成ファイル

postgresql:
custom_conf: /etc/postgresql/18/main/custom.conf

カスタム構成を含めるファイル.

例 (custom.conf):

# Custom settings
statement_timeout = 30000
idle_in_transaction_session_timeout = 60000

6.8。フェールオーバー時にデータ ディレクトリを削除

postgresql:
remove_data_directory_on_rewind_failure: true
remove_data_directory_on_diverged_timelines: true

注意: 回復が失敗した場合はデータ ディレクトリを削除します。

7。セクション: タグ

7.1。フェイルオーバー タグ

tags:
nofailover: false
noloadbalance: false
clonefrom: false
nosync: false

フェイルオーバーなし:

nofailover: false  # Node có thể become primary
nofailover: true   # Node KHÔNG BAO GIỜ become primary

ユースケース: レプリカはレポートにのみ使用されます。 Analytics.

noloadbalance:

noloadbalance: false  # Node có thể serve read queries
noloadbalance: true   # Node KHÔNG serve read queries

ユースケース: ノードはメンテナンス中か、問題。

clonefrom:

clonefrom: false  # Node có thể làm source cho basebackup
clonefrom: true   # Node ưu tiên làm source

ユースケース: 指定されたバックアップノード。

nosync:

nosync: false  # Node có thể become synchronous standby
nosync: true   # Node KHÔNG become synchronous standby

ユースケース: データセンターでの非同期レプリケーションその他。

7.2。カスタムタグ

tags:
datacenter: dc1
environment: production
application: myapp
version: v1.0.0
rack: rack1
zone: us-east-1a

ユースケース:

• 監視とラベル付け
• カスタムフェイルオーバーロジック
• 地理的ルーティング
• マルチテナント識別

7.3。優先タグ_

tags:
nofailover: false

Higher number = higher priority for promotion
failover_priority: 100

クラスターの例:_

node1: failover_priority: 100  ← Preferred primary
node2: failover_priority: 50
node3: failover_priority: 10   ← Last resort

8。セクション: ウォッチドッグ

8.1。基本的なウォッチドッグ構成

watchdog:
mode: required     # off, automatic, required
device: /dev/watchdog
safety_margin: 5

モード:

• off: 無効にするwatchdog
• automatic: 利用可能な場合は使用
• required: ウォッチドッグが利用できない場合は失敗

8.2。ハードウェア ウォッチドッグ

ウォッチドッグの可用性を確認:

ls -l /dev/watchdog

crw------- 1 root root 10, 130 ... /dev/watchdog

ウォッチドッグをロードmodule:

# Load softdog module
sudo modprobe softdog

Make persistent
echo "softdog" | sudo tee -a /etc/modules
Verify
lsmod | grep dog
softdog   ...

postgres ユーザーへのアクセスを許可_:_

# Create udev rule
sudo tee /etc/udev/rules.d/60-watchdog.rules << EOF
KERNEL=="watchdog", OWNER="postgres", GROUP="postgres", MODE="0660"
EOF

Reload udev
sudo udevadm control --reload-rules
sudo udevadm trigger

8.3。ウォッチドッグを使用する理由_

スプリット ブレイン防止:

• Patroni はハングしますが、PostgreSQL は依然としてハングします run
• ネットワークの問題: Patroni は DCS を失いますが、ノード生きている_
• ウォッチドッグがノードを再起動 → プライマリゾンビを阻止_

フロー:

1. Patroni healthy → Kicks watchdog every 10s
2. Patroni hangs/loses DCS → Stops kicking
3. Watchdog timeout (safety_margin) → Reboot node
4. Node reboots → No zombie primary

9。セクション: 同期レプリケーション

9.1。同期モードを有効にする

bootstrap:
dcs:
synchronous_mode: true
synchronous_mode_strict: false
synchronous_node_count: 1

synchronous_mode: 同期レプリケーションを有効にするsynchronous_mode_strict: プライマリは同期なしの書き込みを拒否しますスタンバイsynchronous_node_count: 同期スタンバイの数 (≥1)

9.2。同期モードのバリアント

非同期 (デフォルト):

synchronous_mode: false

• 高速書き込み
• プライマリに障害が発生した場合はデータ損失の危険性

同期_:

synchronous_mode: true
synchronous_mode_strict: false

• スタンバイを 1 回待ちます確認_
• スタンバイがない場合は非同期に低下

厳密な同期:

synchronous_mode: true
synchronous_mode_strict: true

• REFUSE は同期なしで書き込みますスタンバイ_
• データ損失ゼロ保証_
• _リスク可用性への影響

9.3。複数の同期スタンバイ

bootstrap:
dcs:
synchronous_mode: true
synchronous_node_count: 2  # Wait for 2 standbys

PostgreSQL 18 は、

synchronous_standby_names = 'FIRST 2 (node2, node3, node4)'
-- or
synchronous_standby_names = 'ANY 2 (node2, node3, node4)'

10 をサポートします。完全な構成例

10.1。製品グレードの patroni.yml

scope: postgres-prod
namespace: /service/
name: node1

restapi:
listen: 0.0.0.0:8008
connect_address: 10.0.1.11:8008
authentication:
username: admin
password: ${PATRONI_RESTAPI_PASSWORD}
certfile: /etc/patroni/ssl/server.crt
keyfile: /etc/patroni/ssl/server.key
etcd:
hosts: 10.0.1.11:2379,10.0.1.12:2379,10.0.1.13:2379
bootstrap:
dcs:
ttl: 30
loop_wait: 10
retry_timeout: 10
maximum_lag_on_failover: 1048576
maximum_lag_on_syncnode: 1048576
synchronous_mode: true
synchronous_mode_strict: false
postgresql:
  use_pg_rewind: true
  use_slots: true
  
  parameters:
    # Replication
    wal_level: replica
    hot_standby: "on"
    wal_keep_size: "2GB"
    max_wal_senders: 10
    max_replication_slots: 10
    wal_log_hints: "on"
    
    # Performance
    max_connections: 200
    shared_buffers: "4GB"
    effective_cache_size: "12GB"
    maintenance_work_mem: "1GB"
    work_mem: "20MB"
    wal_buffers: "16MB"
    checkpoint_completion_target: 0.9
    
    # Logging
    logging_collector: "on"
    log_directory: "log"
    log_filename: "postgresql-%Y-%m-%d_%H%M%S.log"
    log_line_prefix: "%t [%p]: [%l-1] user=%u,db=%d,app=%a,client=%h "
    log_checkpoints: "on"
    log_connections: "on"
    log_disconnections: "on"
    log_min_duration_statement: 1000
    
    # Extensions
    shared_preload_libraries: "pg_stat_statements"

initdb:
- encoding: UTF8
- locale: en_US.UTF-8
- data-checksums
pg_hba:
- local all all peer
- host replication replicator 10.0.1.11/32 scram-sha-256
- host replication replicator 10.0.1.12/32 scram-sha-256
- host replication replicator 10.0.1.13/32 scram-sha-256
- host all all 10.0.1.0/24 scram-sha-256
- hostssl all all 0.0.0.0/0 scram-sha-256
users:
admin:
password: ${ADMIN_PASSWORD}
options:
- createrole
- createdb
postgresql:
listen: 0.0.0.0:5432
connect_address: 10.0.1.11:5432
data_dir: /var/lib/postgresql/18/data
bin_dir: /usr/lib/postgresql/18/bin
authentication:
replication:
username: replicator
password: ${REPLICATION_PASSWORD}
superuser:
username: postgres
password: ${POSTGRES_PASSWORD}
parameters:
unix_socket_directories: "/var/run/postgresql"
callbacks:
on_role_change: /etc/patroni/scripts/on_role_change.sh
on_start: /etc/patroni/scripts/on_start.sh
on_stop: /etc/patroni/scripts/on_stop.sh
tags:
nofailover: false
noloadbalance: false
clonefrom: false
nosync: false
datacenter: dc1
environment: production
failover_priority: 100
watchdog:
mode: automatic
device: /dev/watchdog
safety_margin: 5

10.2。環境変数_

# /etc/patroni/patroni.env
export PATRONI_RESTAPI_PASSWORD="secure_api_password"
export ADMIN_PASSWORD="secure_admin_password"
export REPLICATION_PASSWORD="secure_replication_password"
export POSTGRES_PASSWORD="secure_postgres_password"

systemd にロード:

[Service]
EnvironmentFile=/etc/patroni/patroni.env

11。概要

重要なポイント

✅ 構成レイヤー: コマンド ライン >環境 >設定ファイル > DCS

✅ 静的構成: ノード固有、再起動が必要

✅ 動的構成: クラスター全体、更新via patronictl edit-config

✅ Bootstrap: 1 回限りの初期化設定

✅ タグ: フェイルオーバー動作とノードの役割を制御

✅ 同期レプリケーション: 耐久性とノードの役割のバランス可用性_

ベスト プラクティス チェックリスト

•  環境変数を使用するパスワード
•  use_pg_rewind wal_log_hints を有効にする: on
•  適切に設定 ttl、 loop_wait、 retry_timeo ut
•  maximum_lag_on_failover ゼロデータ用に構成するloss
•  initdb でdata-checksums を使用
•  通知用のコールバック スクリプトを設定
•  設定スプリット ブレイン防止のウォッチドッグ
•  使用scram-sha-256 認証
•  カスタム タグとその文書化意味_
•  構成ファイルの定期バックアップ

レッスン 9 の準備_

レッスン 9 では、標準構成で初めてクラスターをブートストラップします。取得:

• S3 つのノードで Patroni をタルト
• クラスター形成を確認
• 基本操作をテスト
• 一般的な問題のトラブルシューティング_