Patroni REST API

Patroniには、リーダーレース中にPatroni自分自身によって使用され、フェイルオーバー/スイッチオーバー/再初期化/リスタート/リロードを実行するために patronicl ツールによって使用され、HAProxyまたはその他の種類のロードバランサーがHTTPヘルスチェックを実行します、もちろんモニタリングにも使用できます。以下に、Patroni REST APIエンドポイントのリストを示します。

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

すべてのヘルスチェック GET 要求に対して、Patroniは、ノードのステータスとHTTPステータスコードを含むJSONドキュメントを結果ます。 JSONドキュメントが不要または不要な場合は、 GET の代わりに HEAD または OPTIONS メソッドの使用を検討することができます。

  • Patroni REST APIへの次の要求は、Patroniノードがリーダーロックを使用してプライマリとして実行されている場合にのみ、HTTPステータスコード 200 を結果ます。

    • GET /

    • GET /primary

    • GET /read-write

  • GET /standby-leader は、 Patroniノードが GET /standby-leader のリーダーとして実行されている場合にのみHTTPステータスコード GET /standby-leader を返します。

  • GET /leader パトローニノードがリーダーロックがある場合、HTTPステータスコード GET /leader を結果ます。以前の2つのエンドポイントとの主な違いは、 PostgreSQLが primary または standby_leader として実行されているかどうかを考慮していないことです。

  • GET /replica レプリカヘルスチェックエンドポイント。 Patroniノードが running 状態にあり、ロールが replica で、 noloadbalance タグが設定されていない場合にのみ、HTTPステータスコード GET /replica を返します。

  • GET /replica?lag=<max-lag> レプリカチェックエンドポイント。 replica からのチェックに加えて、レプリケーションレイテンシーもチェックし、指定された値を下回る場合にのみステータスコード GET /replica?lag=<max-lag> を返します。 DCSのキーcluster.last_leader_operationは、リーダーwal位置と、パフォーマンス上の理由からレプリカのレイテンシの計算に使用されます。 max-lagは、バイト整数または人間が読み取り可能な値で指定できます。たとえば、 16KB、64MB、1GB。

    • GET /replica?lag=1048576

    • GET /replica?lag=1024kB

    • GET /replica?lag=10MB

    • GET /replica?lag=1GB

  • GET /replica?tag_key1=value1&tag_key2=value2 レプリカチェックエンドポイント。さらに、yaml構成管理の GET /replica?tag_key1=value1&tag_key2=value2 セクションのユーザー定義タグ key1 および key2 とそれぞれの値もチェックします。タグがインスタンスに定義されていない場合、またはyaml構成の値が照会値と一致しない場合、HTTPステータスコード503が返されます。

    次の要求では、リーダーまたはスタンバイリーダーステータスをチェックしているため、Patroniはユーザー定義タグを適用せず、無視されます。

    • GET /?tag_key1=value1&tag_key2=value2

    • GET /leader?tag_key1=value1&tag_key2=value2

    • GET /primary?tag_key1=value1&tag_key2=value2

    • GET /read-write?tag_key1=value1&tag_key2=value2

    • GET /standby_leader?tag_key1=value1&tag_key2=value2

    • GET /standby-leader?tag_key1=value1&tag_key2=value2

  • GET /read-only 上記のエンドポイントと似ていますが、プライマリも含まれます。

  • GET /synchronous または GET /sync パトロニノードが同期スタンバイとして実行されている場合にのみHTTPステータスコード GET /synchronous を結果ます。

  • GET /read-only-sync 上記のエンドポイントと似ていますが、プライマリも含まれます。

  • GET /quorum は、このパトロニノードがプライマリの synchronous_standby_names にクォーラムノードとしてリストされている場合にのみ、HTTPステータスコード GET /quorum を返します。

  • GET /read-only-quorum 上記のエンドポイントと似ていますが、プライマリも含まれます。

  • GET /asynchronous または GET /async パトロニノードが非同期スタンバイとして実行されている場合にのみHTTPステータスコード GET /asynchronous を結果ます。

  • GET /asynchronous?lag=<max-lag> または GET /async?lag=<max-lag> 非同期スタンバイチェックエンドポイント。 asynchronous または async からのチェックに加えて、レプリケーションレイテンシーもチェックし、指定された値を下回る場合にのみステータスコード GET /asynchronous?lag=<max-lag> を返します。 DCSのキーcluster.last_leader_operationは、リーダーwal位置と、パフォーマンス上の理由からレプリカのレイテンシの計算に使用されます。 max-lagは、バイト整数または人間が読み取り可能な値で指定できます。たとえば、 16KB、64MB、1GB。

    • GET /async?lag=1048576

    • GET /async?lag=1024kB

    • GET /async?lag=10MB

    • GET /async?lag=1GB

  • GET /health PostgreSQLが稼働している場合にのみHTTPステータスコード GET /health を結果ます。

  • GET /liveness パトロニハートビートループが正常に実行されている場合はHTTPステータスコード GET /liveness を返し、最後の実行がプライマリで ttl 秒以上前またはレプリカで 2*ttl である場合は GET /liveness を返します。 livenessProbe に使用できます。

  • GET /readiness?lag=<max-lag>&mode=apply|write は、Patroniノードがリーダーとして実行されている場合、またはPostgreSQLがアップしていて、レプリケートしており、リーダーからそれほど離れていない場合に、HTTPステータスコード GET /readiness?lag=<max-lag>&mode=apply|write を返します。 lagパラメーターは、スタンバイがどの程度遅延することを許可するかを設定します。デフォルトは maximum_lag_on_failover です。ラグは、バイトまたは人間が可読な値で指定できます。たとえば16KB、64MB、1GB。モードは、WALを再生する必要があるかどうかを設定するか、受信したばかりであるかどうかを設定します。デフォルトはapplyです。

    Kubernetes readinessProbe として使用される場合、リーダーに追いついた場合にのみ、新しく開始されたポッドの準備が整います。これとPodDisruptionBudgetと組み合わせると、ノードのローリング再起動中にリーダーが早期に終了するのを防ぎます。また、レプリケーションに追いつけないレプリカが読み取り専用トラフィックをサービスしないようにします。このエンドポイントは、リーダー選挙OpenShiftにKubernetesエンドポイントを使用できない場合、 readinessProbe に使用できます。

liveness エンドポイントは非常に軽量で、 SQLは実行しません。プローブは、リーダーキーの有効期限が間もなくエキスパイアと失敗し始めるように構成する必要があります。デフォルト値の ttl 30s 例では、プローブは次のようになります。

readinessProbe:
  httpGet:
    scheme: HTTP
    path: /readiness
    port: 8008
  initialDelaySeconds: 3
  periodSeconds: 10
  timeoutSeconds: 5
  successThreshold: 1
  failureThreshold: 3
livenessProbe:
  httpGet:
    scheme: HTTP
    path: /liveness
    port: 8008
  initialDelaySeconds: 3
  periodSeconds: 10
  timeoutSeconds: 5
  successThreshold: 1
  failureThreshold: 3

モニタリングエンドポイント

GET /patroni は、リーダーレース中にパトローニによって使用されます。監視システムで使用される場合もあります。このエンドポイントによって生成されるJSONドキュメントは、ヘルスチェックエンドポイントによって生成されるJSONと同じ構造です。

Example: 正常なクラスター

$ curl -s http://localhost:8008/patroni | jq .
{
  "state": "running",
  "postmaster_start_time": "2024-08-28 19:39:26.352526+00:00",
  "role": "primary",
  "server_version": 160004,
  "xlog": {
    "location": 67395656
  },
  "timeline": 1,
  "replication": [
    {
      "usename": "replicator",
      "application_name": "patroni2",
      "client_addr": "10.89.0.6",
      "state": "streaming",
      "sync_state": "async",
      "sync_priority": 0
    },
    {
      "usename": "replicator",
      "application_name": "patroni3",
      "client_addr": "10.89.0.2",
      "state": "streaming",
      "sync_state": "async",
      "sync_priority": 0
    }
  ],
  "dcs_last_seen": 1692356718,
  "tags": {
    "clonefrom": true
  },
  "database_system_identifier": "7268616322854375442",
  "patroni": {
    "version": "4.0.0",
    "scope": "demo",
    "name": "patroni1"
  }
}

Example: ロック解除されたクラスター

$ curl -s http://localhost:8008/patroni  | jq .
{
  "state": "running",
  "postmaster_start_time": "2024-08-28 19:39:26.352526+00:00",
  "role": "replica",
  "server_version": 160004,
  "xlog": {
    "received_location": 67419744,
    "replayed_location": 67419744,
    "replayed_timestamp": null,
    "paused": false
  },
  "timeline": 1,
  "replication": [
    {
      "usename": "replicator",
      "application_name": "patroni2",
      "client_addr": "10.89.0.6",
      "state": "streaming",
      "sync_state": "async",
      "sync_priority": 0
    },
    {
      "usename": "replicator",
      "application_name": "patroni3",
      "client_addr": "10.89.0.2",
      "state": "streaming",
      "sync_state": "async",
      "sync_priority": 0
    }
  ],
  "cluster_unlocked": true,
  "dcs_last_seen": 1692356928,
  "tags": {
    "clonefrom": true
  },
  "database_system_identifier": "7268616322854375442",
  "patroni": {
    "version": "4.0.0",
    "scope": "demo",
    "name": "patroni1"
  }
}

Example: Example: が有効になったロック解除されたクラスター

$ curl -s http://localhost:8008/patroni  | jq .
{
  "state": "running",
  "postmaster_start_time": "2024-08-28 19:39:26.352526+00:00",
  "role": "replica",
  "server_version": 160004,
  "xlog": {
    "location": 67420024
  },
  "timeline": 1,
  "replication": [
    {
      "usename": "replicator",
      "application_name": "patroni2",
      "client_addr": "10.89.0.6",
      "state": "streaming",
      "sync_state": "async",
      "sync_priority": 0
    },
    {
      "usename": "replicator",
      "application_name": "patroni3",
      "client_addr": "10.89.0.2",
      "state": "streaming",
      "sync_state": "async",
      "sync_priority": 0
    }
  ],
  "cluster_unlocked": true,
  "failsafe_mode_is_active": true,
  "dcs_last_seen": 1692356928,
  "tags": {
    "clonefrom": true
  },
  "database_system_identifier": "7268616322854375442",
  "patroni": {
    "version": "4.0.0",
    "scope": "demo",
    "name": "patroni1"
  }
}

Example: Example: が有効になっているクラスター

$ curl -s http://localhost:8008/patroni  | jq .
{
  "state": "running",
  "postmaster_start_time": "2024-08-28 19:39:26.352526+00:00",
  "role": "replica",
  "server_version": 160004,
  "xlog": {
    "location": 67420024
  },
  "timeline": 1,
  "replication": [
    {
      "usename": "replicator",
      "application_name": "patroni2",
      "client_addr": "10.89.0.6",
      "state": "streaming",
      "sync_state": "async",
      "sync_priority": 0
    },
    {
      "usename": "replicator",
      "application_name": "patroni3",
      "client_addr": "10.89.0.2",
      "state": "streaming",
      "sync_state": "async",
      "sync_priority": 0
    }
  ],
  "pause": true,
  "dcs_last_seen": 1724874295,
  "tags": {
    "clonefrom": true
  },
  "database_system_identifier": "7268616322854375442",
  "patroni": {
    "version": "4.0.0",
    "scope": "demo",
    "name": "patroni1"
  }
}

GET /metrics エンドポイントを介してPrometheus形式でPatroniメトリックを取得します。

$ curl http://localhost:8008/metrics

# HELP patroni_version Patroni semver without periods. \
# TYPE patroni_version gauge
patroni_version{scope="batman",name="patroni1"} 040000
# HELP patroni_postgres_running Value is 1 if Postgres is running, 0 otherwise.
# TYPE patroni_postgres_running gauge
patroni_postgres_running{scope="batman",name="patroni1"} 1
# HELP patroni_postmaster_start_time Epoch seconds since Postgres started.
# TYPE patroni_postmaster_start_time gauge
patroni_postmaster_start_time{scope="batman",name="patroni1"} 1724873966.352526
# HELP patroni_primary Value is 1 if this node is the leader, 0 otherwise.
# TYPE patroni_primary gauge
patroni_primary{scope="batman",name="patroni1"} 1
# HELP patroni_xlog_location Current location of the Postgres transaction log, 0 if this node is not the leader.
# TYPE patroni_xlog_location counter
patroni_xlog_location{scope="batman",name="patroni1"} 22320573386952
# HELP patroni_standby_leader Value is 1 if this node is the standby_leader, 0 otherwise.
# TYPE patroni_standby_leader gauge
patroni_standby_leader{scope="batman",name="patroni1"} 0
# HELP patroni_replica Value is 1 if this node is a replica, 0 otherwise.
# TYPE patroni_replica gauge
patroni_replica{scope="batman",name="patroni1"} 0
# HELP patroni_sync_standby Value is 1 if this node is a sync standby replica, 0 otherwise.
# TYPE patroni_sync_standby gauge
patroni_sync_standby{scope="batman",name="patroni1"} 0
# HELP patroni_quorum_standby Value is 1 if this node is a quorum standby replica, 0 otherwise.
# TYPE patroni_quorum_standby gauge
patroni_quorum_standby{scope="batman",name="patroni1"} 0
# HELP patroni_xlog_received_location Current location of the received Postgres transaction log, 0 if this node is not a replica.
# TYPE patroni_xlog_received_location counter
patroni_xlog_received_location{scope="batman",name="patroni1"} 0
# HELP patroni_xlog_replayed_location Current location of the replayed Postgres transaction log, 0 if this node is not a replica.
# TYPE patroni_xlog_replayed_location counter
patroni_xlog_replayed_location{scope="batman",name="patroni1"} 0
# HELP patroni_xlog_replayed_timestamp Current timestamp of the replayed Postgres transaction log, 0 if null.
# TYPE patroni_xlog_replayed_timestamp gauge
patroni_xlog_replayed_timestamp{scope="batman",name="patroni1"} 0
# HELP patroni_xlog_paused Value is 1 if the Postgres xlog is paused, 0 otherwise.
# TYPE patroni_xlog_paused gauge
patroni_xlog_paused{scope="batman",name="patroni1"} 0
# HELP patroni_postgres_streaming Value is 1 if Postgres is streaming, 0 otherwise.
# TYPE patroni_postgres_streaming gauge
patroni_postgres_streaming{scope="batman",name="patroni1"} 1
# HELP patroni_postgres_in_archive_recovery Value is 1 if Postgres is replicating from archive, 0 otherwise.
# TYPE patroni_postgres_in_archive_recovery gauge
patroni_postgres_in_archive_recovery{scope="batman",name="patroni1"} 0
# HELP patroni_postgres_server_version Version of Postgres (if running), 0 otherwise.
# TYPE patroni_postgres_server_version gauge
patroni_postgres_server_version{scope="batman",name="patroni1"} 160004
# HELP patroni_cluster_unlocked Value is 1 if the cluster is unlocked, 0 if locked.
# TYPE patroni_cluster_unlocked gauge
patroni_cluster_unlocked{scope="batman",name="patroni1"} 0
# HELP patroni_postgres_timeline Postgres timeline of this node (if running), 0 otherwise.
# TYPE patroni_postgres_timeline counter
patroni_failsafe_mode_is_active{scope="batman",name="patroni1"} 0
# HELP patroni_postgres_timeline Postgres timeline of this node (if running), 0 otherwise.
# TYPE patroni_postgres_timeline counter
patroni_postgres_timeline{scope="batman",name="patroni1"} 24
# HELP patroni_dcs_last_seen Epoch timestamp when DCS was last contacted successfully by Patroni.
# TYPE patroni_dcs_last_seen gauge
patroni_dcs_last_seen{scope="batman",name="patroni1"} 1724874235
# HELP patroni_pending_restart Value is 1 if the node needs a restart, 0 otherwise.
# TYPE patroni_pending_restart gauge
patroni_pending_restart{scope="batman",name="patroni1"} 1
# HELP patroni_is_paused Value is 1 if auto failover is disabled, 0 otherwise.
# TYPE patroni_is_paused gauge
patroni_is_paused{scope="batman",name="patroni1"} 1
# HELP patroni_postgres_state Numeric representation of Postgres state.
# Values: 0=initdb, 1=initdb_failed, 2=custom_bootstrap, 3=custom_bootstrap_failed, 4=creating_replica, 5=running, 6=starting, 7=bootstrap_starting, 8=start_failed, 9=restarting, 10=restart_failed, 11=stopping, 12=stopped, 13=stop_failed, 14=crashed
# TYPE patroni_postgres_state gauge
patroni_postgres_state{scope="batman",name="patroni1"} 5

PostgreSQLの状態値

patroni_postgres_state メトリックは、現在のPostgreSQLインスタンスの状態の数値表現を提供します。これは、時間の経過とともに状態の変化を追跡する必要があるシステムの監視と警告に役立ちます。数値は、 PostgresqlState.get_metrics_description() 静的メソッドを使用して生成されます。

PostgreSQLの状態値

バリュー

州名

説明

0

initdb

新しいクラスターの初期化

1

initdb_failed

新しいクラスターの初期化に失敗しました

2

custom_bootstrap

カスタムブートストラップスクリプトの実行

3

custom_bootstrap_failed

カスタムブートストラップスクリプトが失敗しました

4

created_replica

プライマリからのレプリカの作成

5

ランニング

PostgreSQLは正常に実行されています

6

スタート

PostgreSQLが起動しています

7

bootstrap_starting

カスタムブートストラップ後の起動

8

start_failed

PostgreSQLの起動に失敗しました

9

再起動

PostgreSQLが再起動しています

10

restart_failed

PostgreSQLの再起動に失敗しました

11

停止

PostgreSQLが停止しています

12

止まった

PostgreSQLは停止しています

13

stop_failed

PostgreSQLの停止に失敗しました

14

クラッシュした

PostgreSQLがクラッシュしました

注釈

これらの数値は固定され、既存の監視システムとの下位互換性を維持するために変更されることはありません。将来的に新しい状態が追加される場合、既存の状態を変更せずに新しい数値が割り当てられます。

クラスターステータスエンドポイント

  • GET /cluster エンドポイントは、現在のクラスタートポロジと状態を説明するJSONドキュメントを生成します。

$ curl -s http://localhost:8008/cluster | jq .
{
  "members": [
    {
      "name": "patroni1",
      "role": "leader",
      "state": "running",
      "api_url": "http://10.89.0.4:8008/patroni",
      "host": "10.89.0.4",
      "port": 5432,
      "timeline": 5,
      "tags": {
        "clonefrom": true
      }
    },
    {
      "name": "patroni2",
      "role": "replica",
      "state": "streaming",
      "api_url": "http://10.89.0.6:8008/patroni",
      "host": "10.89.0.6",
      "port": 5433,
      "timeline": 5,
      "tags": {
        "clonefrom": true
      },
      "receive_lag": 0,
      "receive_lsn": "0/4000060",
      "replay_lag": 0,
      "replay_lsn": "0/4000060",
      "lag": 0,
      "lsn": "0/4000060"
    }
  ],
  "scope": "demo",
  "scheduled_switchover": {
    "at": "2023-09-24T10:36:00+02:00",
    "from": "patroni1",
    "to": "patroni3"
  }
}

  • GET /history エンドポイントは、クラスタースイッチオーバー/フェールオーバーの履歴に関するビューを提供します。このフォーマットは、 pg_wal ディレクトリの履歴ファイルの内容に非常に似ています。唯一の違いは、新しいタイムラインが作成された時期を示すタイムスタンプフィールドです。

$ curl -s http://localhost:8008/history | jq .
[
  [
    1,
    25623960,
    "no recovery target specified",
    "2019-09-23T16:57:57+02:00"
  ],
  [
    2,
    25624344,
    "no recovery target specified",
    "2019-09-24T09:22:33+02:00"
  ],
  [
    3,
    25624752,
    "no recovery target specified",
    "2019-09-24T09:26:15+02:00"
  ],
  [
    4,
    50331856,
    "no recovery target specified",
    "2019-09-24T09:35:52+02:00"
  ]
]

構成エンドポイント

GET /config 動的構成の現在のバージョンを取得します。

$ curl -s http://localhost:8008/config | jq .
{
  "ttl": 30,
  "loop_wait": 10,
  "retry_timeout": 10,
  "maximum_lag_on_failover": 1048576,
  "postgresql": {
    "use_slots": true,
    "use_pg_rewind": true,
    "parameters": {
      "hot_standby": "on",
      "wal_level": "hot_standby",
      "max_wal_senders": 5,
      "max_replication_slots": 5,
      "max_connections": "100"
    }
  }
}

PATCH /config 既存の構成を変更します。

$ curl -s -XPATCH -d \
        '{"loop_wait":5,"ttl":20,"postgresql":{"parameters":{"max_connections":"101"}}}' \
        http://localhost:8008/config | jq .
{
  "ttl": 20,
  "loop_wait": 5,
  "maximum_lag_on_failover": 1048576,
  "retry_timeout": 10,
  "postgresql": {
    "use_slots": true,
    "use_pg_rewind": true,
    "parameters": {
      "hot_standby": "on",
      "wal_level": "hot_standby",
      "max_wal_senders": 5,
      "max_replication_slots": 5,
      "max_connections": "101"
    }
  }
}

上記のREST API呼び出しは、既存の構成にパッチを適用し、新しい構成を返します。

ノードがこの構成を処理したことを確認してみましょう。最初に、5秒ごとにログ行の印刷を開始する必要がありますloop_wait=5 。 /"max_connections/"の変更には再起動が必要であるため、/"pending_restart/"フラグを公開する必要があります。

$ curl -s http://localhost:8008/patroni | jq .
{
  "database_system_identifier": "6287881213849985952",
  "postmaster_start_time": "2024-08-28 19:39:26.352526+00:00",
  "xlog": {
    "location": 2197818976
  },
  "timeline": 1,
  "dcs_last_seen": 1724874545,
  "database_system_identifier": "7408277255830290455",
  "pending_restart": true,
  "pending_restart_reason": {
    "max_connections": {
      "old_value": "100",
      "new_value": "101"
    }
  },
  "patroni": {
    "version": "4.0.0",
    "scope": "batman",
    "name": "patroni1"
  },
  "state": "running",
  "role": "primary",
  "server_version": 160004
}

パラメーターの削除

一部の設定を削除またはリセットしたい場合は、 null でパッチを適用するだけです。

$ curl -s -XPATCH -d \
        '{"postgresql":{"parameters":{"max_connections":null}}}' \
        http://localhost:8008/config | jq .
{
  "ttl": 20,
  "loop_wait": 5,
  "retry_timeout": 10,
  "maximum_lag_on_failover": 1048576,
  "postgresql": {
    "use_slots": true,
    "use_pg_rewind": true,
    "parameters": {
      "hot_standby": "on",
      "unix_socket_directories": ".",
      "wal_level": "hot_standby",
      "max_wal_senders": 5,
      "max_replication_slots": 5
    }
  }
}

上記の呼び出しは、動的構成から postgresql.parameters.max_connections を削除します。

PUT /config 既存の動的構成の完全な書き換えを無条件に実行することもできます。

$ curl -s -XPUT -d \
        '{"maximum_lag_on_failover":1048576,"retry_timeout":10,"postgresql":{"use_slots":true,"use_pg_rewind":true,"parameters":{"hot_standby":"on","wal_level":"hot_standby","unix_socket_directories":".","max_wal_senders":5}},"loop_wait":3,"ttl":20}' \
        http://localhost:8008/config | jq .
{
  "ttl": 20,
  "maximum_lag_on_failover": 1048576,
  "retry_timeout": 10,
  "postgresql": {
    "use_slots": true,
    "parameters": {
      "hot_standby": "on",
      "unix_socket_directories": ".",
      "wal_level": "hot_standby",
      "max_wal_senders": 5
    },
    "use_pg_rewind": true
  },
  "loop_wait": 3
}

スイッチオーバーおよびフェイルオーバーエンドポイント

スイッチオーバー

/switchover エンドポイントは、クラスターが正常な場合にのみ機能しますリーダーがあります。特定の時間にスイッチオーバーをスケジュールすることもできます。

/switchover エンドポイントを呼び出す場合、 /failover エンドポイントとは異なり、候補を指定できますが必須ではありません。候補が提供されない場合、クラスターのすべての資格のあるノードは、リーダーが退任した後、リーダーレースに参加します。

POST 要求のJSON本文で、 leader フィールドを指定する必要があります。 candidate および scheduled_at フィールドはオプショナルであり、特定の時間にスイッチオーバーをスケジュールするために使用できます。

状況に応じて、要求はさまざまなHTTPステータスコードと本文を返す場合があります。ステータスコード 200 は、スイッチオーバーまたはフェイルオーバーが正常に完了すると、返されます。スイッチオーバーが正常にスケジュールされた場合、PatroniはHTTPステータスコード 200 を返します。何か問題が発生した場合、エラーステータスコード 200 、 200 、または 200 のいずれか が応答本文の詳細とともに返されます。

DELETE /switchover は、現在スケジュールされているスイッチオーバーを削除するために使用できます。

Example: は、正常なスタンバイへのスイッチオーバーを実行します

$ curl -s http://localhost:8008/switchover -XPOST -d '{"leader":"postgresql1"}'
Successfully switched over to "postgresql2"

Example: 特定のノードへのスイッチオーバーを実行します

$ curl -s http://localhost:8008/switchover -XPOST -d \
        '{"leader":"postgresql1","candidate":"postgresql2"}'
Successfully switched over to "postgresql2"

Example: は、特定の時刻にリーダーからクラスター内の他の正常なスタンバイへのスイッチオーバーをスケジュールします。

$ curl -s http://localhost:8008/switchover -XPOST -d \
        '{"leader":"postgresql0","scheduled_at":"2019-09-24T12:00+00"}'
Switchover scheduled

フェイルオーバー

/failover エンドポイントは、正常なノードがない場合に手動フェイルオーバーを実行できますたとえば、すべての同期スタンバイが昇格するほど十分に健全でない場合は非同期スタンバイに。ただし、クラスターがリーダーを持たないための要件はありません。フェールオーバーは、正常なクラスターで実行することもできます。

POST 要求のJSON本文で、 candidate フィールドを指定する必要があります。 leader フィールドが指定されている場合、代わりにスイッチオーバーがトリガーされます。

Example:

$ curl -s http://localhost:8008/failover -XPOST -d '{"candidate":"postgresql1"}'
Successfully failed over to "postgresql1"

警告

Be very careful 。特定の状況でデータ損失が発生する可能性があるため、このエンドポイントを使用する場合。ほとんどの場合、 Be very careful は管理者のニーズを満たします。

POST /switchover および POST /failover エンドポイントは、それぞれ POST /switchover および POST /switchover によって使用されます。

DELETE /switchover は、 DELETE /switchover によって使用されます。

フェイルオーバー/スイッチオーバーの比較

フェイルオーバー

スイッチオーバー

リーダーの指定が必要です

いいえ

はい

候補者の指定が必要です

はい

いいえ

一時停止中に実行できます

はい

はい 特定の候補者にのみ

スケジュール可能

いいえ

はい一時停止中でない場合

正常スタンバイ

スイッチオーバー中にリーダーレースに参加できるように、またはフェールオーバー/スイッチオーバー候補としてリーダーになるためには、クラスターのメンバーが合格する必要があるチェックがいくつかあります。

  • Patroni APIを介して到達可能であること。

  • nofailover タグが true に設定されていません。

  • ウォッチドッグが完全に機能するように構成する必要がある場合。

  • 正常なクラスターでのスイッチオーバーまたは自動フェイルオーバーの場合、最大レプリケーションラグ maximum_lag_on_failover maximum_lag_on_failover を超えません。

  • 正常なクラスターでのスイッチオーバーまたは自動フェイルオーバーの場合、 check_timeline check_timeline が true に設定されている場合、クラスタータイムラインより小さいタイムライン番号を持たない。

  • synchronous mode で

    • スイッチオーバーの場合 候補ありとなしの両方 /sync キーメンバーにリストされます。

    • 正常なクラスターと異常なクラスターの両方でのフェールオーバーの場合、このチェックは省略されます。

警告

リーダーのないクラスターで手動フェイルオーバーが発生する場合、次の場合でも候補者は昇格できます。

  • 同期モードが有効になっている場合、 /sync キーメンバーにはありません。

  • その遅延が許容される最大レプリケーション遅延を超えています。

  • 最後の既知のクラスタータイムラインよりも小さいタイムライン番号があります。

エンドポイントを再起動します

  • POST /restart POST /restart 呼び出しを実行することにより、特定のノードでPostgresを再起動できます。 POST 要求のJSON本文では、オプションでいくつかのリスタート条件を指定できます。

    • restart_pending true に設定されている場合 ブール値、PatroniはPostgreSQL構成にいくつかの変更を適用するために、再起動が保留中の場合にのみPostgreSQLを再起動します。

    • role ノードの現在のロールがPOST要求のロールと一致する場合にのみ再起動を実行します。

    • postgres_version : postgresの現在のバージョンがPOST要求で指定されたものよりも小さい場合にのみ再起動を実行します。

    • timeout PostgreSQLが接続の受け入れを開始するまで待機する時間。 primary_start_timeout をオーバーライドします。

    • schedule タイムゾーンを含むタイムスタンプ、将来のどこかで再起動をスケジュールします。

  • DELETE /restart スケジュールされた再起動を削除します

POST /restart および DELETE /restart エンドポイントは、それぞれ POST /restart および POST /restart によって使用されます。

エンドポイントのリロード

POST /reload 呼び出しは、Patroniに構成ファイルを再読み取りおよび適用するように指示します。これは、 SIGHUP シグナルをPatroniプロセスに送信することと同じです。再起動が必要なPostgresパラメーター POST /reload などを変更した場合、 POST /restart エンドポイントを呼び出すか、 POST /reload のヘルプを使用して、Postgresのリスタートを明示的に行う必要があります。

リロードエンドポイントは、 patronicl reload によって使用されます。

エンドポイントを再初期化する

POST /reinitialize 指定されたノードでPostgreSQLデータディレクトリを再初期化します。レプリカでのみ実行が許可されます。呼び出されると、データディレクトリを削除し、 pg_basebackup または代替の POST /reinitialize を起動します。

Patroniが障害が発生したPostgresを復旧または再起動しようとするループに入っている場合、呼び出しは失敗する可能性があります。この問題を解決するためには、要求本文で {/"force/":true} を指定できます。

要求本文で{/"from-leader/":true}を指定して、リーダーノードからベースバックアップを直接取得できます。これは、すべてのレプリカノードに障害が発生しているときに再初期化を実行する場合に役立ちます。

再初期化エンドポイントは patronicl reinit によって使用されます。