diff --git a/doc.ja/src/sgml/example-AWS.sgml b/doc.ja/src/sgml/example-AWS.sgml
index bc5e689..2996583 100644
--- a/doc.ja/src/sgml/example-AWS.sgml
+++ b/doc.ja/src/sgml/example-AWS.sgml
@@ -1,356 +1,476 @@
-
AWS設定の例
-
- このチュートリアルでは、AWS上で"Watchdog"を使う簡単な例を示します。
- この例では、高可用性のためにElastic IP Addressを仮想IPとして使います。
-
+
+
- watchdogは、Pgpool-IIのすべてのモード、すなわちレプリケーションモード、マスタ／スレーブモード、ローモードのいずれでも使えます。
+ Elastic IPアドレスの付け替え
-
-
+
+
+
+
+ ルートテーブルの書き換え
+
+
+
-
-
- AWSのセットアップ
+
+ Elastic IPアドレスの付け替え
-
- この例では、2ノードのPgpool-II watchdogクラスタを使います。
- そこで、2つのAmazon Linux EC2インスタンスを設定し、ひとつのElastic IPアドレスを使用します。
- 以下のステップを実施してください。
+ この節では、Elastic IPアドレスを仮想IPとして使い、複数のEC2インスタンス間で付け替える方法を説明します。
-
-
-
-
-
- Amazon Linux EC2インスタンスを2つ起動します。
- この例では、それぞれ"instance-1"と"instance-2"という名前を付けます。
-
-
-
-
-
-
- これらのインスタンスのセキュリティグループを設定し、Pgpool-IIとwatchdogが使用するポートへのインバウンドトラフィックを許可します。
-
-
-
-
-
-
- Pgpool-IIを両方のインスタンスにインストールします。
-
-
-
-
-
-
- Elastic IPアドレスを確保します。
- この例では、Elastic IPアドレスに"35.163.178.3"を設定します。
-
-
-
-
-
+
+ AWSのセットアップ
+
+ この方法を利用する場合は、Pgpool-II EC2インスタンスをパブリックサブネットに配置し、クライアントはインターネット経由でPgpool-IIに接続することを想定しています。
+ この方法はMulti-AZ構成に対応しています。
+
+
+ この設定例では、3ノードのPgpool-II（watchdog）クラスタを使います。
+ そこで、3つのEC2インスタンスと、1つのElastic IPアドレスを作成します。
+
+
+ 以下のステップを実施してください。
+
-
-
- <productname>Pgpool-II</productname>の設定
-
- この例の設定はとほとんど同じになりますが、を設定せず、代わりにとを使ってleader/Active Pgpool-IIノードのElastic IPアドレスを切り替えるのが異なります。
-
+
+
+
+ EC2インスタンスを3つ起動します。
+
+
-
-use_watchdog = on
-delegate_ip = ''
-...
-wd_escalation_command = '$path_to_script/aws-escalation.sh'
-wd_de_escalation_command = '$path_to_script/aws-de-escalation.sh'
-
-
+
+
+ これらのインスタンスのセキュリティグループを設定します。
+ Pgpool-IIを動かすために必要な最低限の設定は、以下のように設定してください。
+
-
-
- エスカレーションおよびディエスカレーション用のスクリプト
-
-
- aws-escalation.shとaws-de-escalation.shスクリプトを2つのインスタンス上に作成し、とがそれぞれそれらを指すようにしてください。
-
+
+
+
+ Pgpool-IIとwatchdogが使用するポートへのインバウンドトラフィックを許可します。
+
+
+
+
+ Pgpool-II（watchdog）が仮想IPに対してpingを実行し疎通確認を行うため、Elastic IP（送信元）からのICMPトラフィックを許可します。
+
+
+
+
+
+
+
+ Pgpool-IIをすべてのインスタンスにインストールします。
+
+
+
+
+
+ AWSのEC2インスタンス上でAWSサービスを操作・管理するために、AWS CLIを使用します。
+ すべてのPgpool-IIのインスタンスにAWS CLIをインストールします。
+
+
+ また、Pgpool-IIの起動ユーザでAWS CLIを実行できるように、Pgpool-IIの起動ユーザでaws configureを実行し、認証情報設定を行います。
+ RPMからインストールした場合、デフォルトでPgpool-IIはpostgresユーザで起動します。
+
+
+
+
+
+ Elastic IPアドレスを確保します。
+ この設定例では、Elastic IPアドレスは"35.163.178.3"となります。
+
+
+
+
-
+
+ <productname>Pgpool-II</productname>の設定
-
- AWSインスタンス上でwd-escalation.shとwd-de-escalation.shで使用するコマンドが実行できるようにするために、AWS CLIの設定が必要になるかもしれません。
- configure AWS CLIを参照してください。
+ Pgpool-IIの設定を説明します。
+ この設定例はとほとんど同じになりますが、とを使ってElastic IPアドレスを付与・解除するのが異なります。
+
+
+ に仮想IPとして使用するElastic IPアドレスを指定します。
-
-
-
- エスカレーションスクリプト
+
+use_watchdog = on
+delegate_ip = '35.163.178.3'
+
-
- このスクリプトは、watchdogがactive/leaderノードになったときに、Elastic IPをアサインするためにwatchdogが実行します。
+ とにElastic IPアドレスを付与・解除するスクリプトを以下のように指定します。
+ は、watchdogがリーダーノードになったときに、Elastic IPアドレスを付与するためにwatchdogが実行します。
+ は、watchdogがリーダーノードを退任するときに、Elastic IPアドレスを解除するためにwatchdogが実行します。
-
- aws-escalation.sh:
-
- #! /bin/sh
- ELASTIC_IP=35.163.178.3
- # replace it with the Elastic IP address you
- # allocated from the aws console
- INSTANCE_ID=i-0a9b64e449b17ed4b
- # replace it with the instance id of the Instance
- # this script is installed on
+
+if_up_cmd = '<path to script> up $_IP_$ <path to awscli>'
+if_down_cmd = '<path to script> down $_IP_$ <path to awscli>'
+
+
+
+
+
+ <path to script>: 仮想IPの付与・解除を行うスクリプトのパスを指定します。
+
+
- echo "Assigning Elastic IP $ELASTIC_IP to the instance $INSTANCE_ID"
- # bring up the Elastic IP
- aws ec2 associate-address --instance-id $INSTANCE_ID --public-ip $ELASTIC_IP
+
+
+ <path to awscli>: AWS CLIのパスを指定します。
+
+
+
- exit 0
-
+
+ この設定例では、以下のように指定します。環境に合わせて、設定してください。
+
+
+
+if_up_cmd = '/etc/pgpool-II/aws_eip_if_cmd.sh up $_IP_$ /usr/local/bin/aws'
+if_down_cmd = '/etc/pgpool-II/aws_eip_if_cmd.sh down $_IP_$ /usr/local/bin/aws'
+
+
+ arpingコマンドは実行不要なので、常に成功させるようにtrueに設定します。
+
+arping_cmd = 'true'
+
-
-
- ディエスカレーションスクリプト
+
+
+ Elastic IPアドレス付与・解除用のスクリプト
-
- このスクリプトは、watchdogがactive/leaderノードを退任するときに、Elastic IPのアサインを解除するためにwatchdogが実行します。
+ if_up_cmd/if_down_cmdで実行するスクリプトをすべてのPgpool-IIインスタンス上に作成します。
- aws-de-escalation.sh:
-
- #! /bin/sh
-
- ELASTIC_IP=35.163.178.3
- # replace it with the Elastic IP address you
- # allocated from the aws console
-
- echo "disassociating the Elastic IP $ELASTIC_IP from the instance"
- # bring down the Elastic IP
- aws ec2 disassociate-address --public-ip $ELASTIC_IP
- exit 0
-
+ この設定例では、サンプルスクリプトaws_eip_if_cmd.shを使用します。必要に応じて、編集してください。
-
+
+(すべてのPgpool-IIインスタンスで実行)
+# cp -p /etc/pgpool-II/aws_eip_if_cmd.sh{.sample,}
+
-
-
- AWSコマンドリファレンス
-
-
-
- <ulink url="http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html">Configure AWS CLI</ulink>
-
-
- AWS Documentation: Configuring the AWS Command Line Interface
-
-
-
-
-
- <ulink url="http://docs.aws.amazon.com/cli/latest/reference/ec2/associate-address.html">associate-address</ulink>
-
-
- AWS Documentation: associate-address reference
-
-
-
-
-
- <ulink url="http://docs.aws.amazon.com/cli/latest/reference/ec2/disassociate-address.html">disassociate-address</ulink>
-
-
- AWS Documentation: disassociate-address reference
-
-
+
+ 以上で、設定は完了です。
+
+
-
+
+ 実行してみる
+
+ Pgpool-IIを起動し、ローカル環境からElastic IPアドレスを使ってPgpool-IIに接続してみます。
+
+
+[user@someserver]$ psql -h 35.163.178.3 -p 9999 -U postgres -c "show pool_nodes"
+
+
+ リーダーPgpool-IIを停止し、Elastic IPアドレスが新しいリーダーに付与され、Elastic IPアドレスを使ってPgpool-IIに接続できることを確認します。
+
+
+[user@someserver]$ psql -h 35.163.178.3 -p 9999 -U postgres -c "show pool_nodes"
+
+
-
-
- 実行してみる
+
+ ルートテーブルの書き換え
-
- それぞれのサーバ上でPgpool-IIを"-n"スイッチ付きで起動し、pgpool.logにログメッセージをリダイレクトします。
- leader/active Pgpool-IIノードは、Elastic IPのアサインメッセージを表示します。
+ この節では、ルートテーブルの書き換えにより、リーダーPgpool-II（watchdog）へのルーティングを制御する方法を説明します。
+
+
+ この方法では、プライベートIPアドレスを仮想IPとして使い、リーダーPgpool-IIインスタンスに付与します。
+ フェイルオーバー時に、仮想IPの付け替えを行い、ルートテーブルを書き換えることで、仮想IPへのトラフィックを新しいリーダーPgpool-IIインスタンスへルーティングすることが可能です。
+
+
+
+ AWSのセットアップ
+
+ この方法を利用する場合は、Pgpool-II EC2インスタンスがプライベートサブネットに配置されており、クライアントアプリケーションも同一VPC内に存在することを想定しています。
+ この方法はMulti-AZ構成に対応しています。
+
+
+ この例では、複数のアベイラビリティゾーンを跨いだ3ノードのPgpool-II (watchdog)クラスタを使います。
+
+
+ 以下のステップを実施してください。
+
+
+
+
+
+
+ 1つのパブリックサブネットと3つのプライベートサブネットを持つVPCを作成し、各プライベートサブネットは異なるアベイラビリティーゾーンに属しています。
+ 詳細については、こちらのドキュメントを参照してください。
+
+
+
+
+
+ パブリックサブネットに関連付けるルートテーブルとプライベートサブネットに関連付けるルートテーブルをそれぞれ作成します。
+ エントリの設定については、こちらのドキュメントを参照してください。
+
+
+
+
+
+ 1つのアプリケーションEC2インスタンスと3つのPgpool-II EC2インスタンスを起動します。
+ アプリケーションインスタンスをパブリックサブネットに配置し、それぞれのPgpool-IIインスタンスを異なるプライベートサブネットに配置します。
+
+
+
+
+
+ Pgpool-II EC2インスタンスのセキュリティグループを設定し、VPCのCIDR範囲内にあるIPアドレスからPgpool-IIとwatchdogが使用するポートへのトラフィックを許可します。
+
+
+
+
+
+ すべてのPgpool-IIインスタンスにPgpool-IIをインストールします。
+
+
+
+
+
+ AWSインスタンス上でAWSサービスを操作・管理するために、AWS CLIを使用します。
+ すべてのインスタンスにAWS CLIをインストールします。
+
+
+ また、Pgpool-IIの起動ユーザでAWS CLIを実行できるように、Pgpool-IIの起動ユーザでaws configureを実行し、認証情報設定を行います。
+ RPMからインストールした場合、デフォルトでPgpool-IIはpostgresユーザで起動します。
+
+
+
+
+
+ 仮想IPの付与や解除にはroot権限が必要です。
+ 一般ユーザでPgpool-IIを起動する場合、起動ユーザがパスワードなしでsudoできるようにsudoersファイルを設定する必要があります。
+ RPMからインストールした場合、postgresユーザの権限が自動的に設定されます。
+
+
+
+
+
+ あらかじめ仮想IPとして使うプライベートIPアドレスを決めておきます。
+ セカンダリIPアドレスはアベイラビリティーゾーンを跨ぐことができないため、VPCのCIDR範囲外のプライベートIPアドレスを仮想IPとして使用します。この設定例では、"20.0.0.50"を使用します。
+
+
+
+
+
+
+ <productname>Pgpool-II</productname>の設定
+
+ この節では、Pgpool-IIの設定を説明します。
+
+
+ この設定例はとほとんど同じになりますが、とを使ってリーダーPgpool-IIインスタンスへのルーティングを切り替えるのが異なります。
+
+
+ に仮想IPとして使用するプライベートIPを指定します。
+
+
- LOG: I am the cluster leader node. Starting escalation process
- LOG: escalation process started with PID:23543
- LOG: watchdog: escalation started
-
- Assigning Elastic IP 35.163.178.3 to the instance i-0a9b64e449b17ed4b
- {
- "AssociationId": "eipassoc-39853c42"
- }
-
- LOG: watchdog escalation successful
- LOG: watchdog escalation process with pid: 23543 exit with SUCCESS.
+use_watchdog = on
+delegate_ip = '20.0.0.50'
-
-
-
- Elastic IPアドレスにpingが通ることを確かめます。
+
+ とにルートテーブルの書き換えを行うスクリプトを以下のように指定します。
+ は、watchdogがリーダーノードになったときに、ルートテーブルの書き換えおよび仮想IPの割り当てを行うためにwatchdogが実行します。
+ は、watchdogがリーダーノードを退任するときに、ルートテーブルの書き換えおよび仮想IPの解除を行うためにwatchdogが実行します。
+
- [user@someserver]$ ping 35.163.178.3
- PING 35.163.178.3 (35.163.178.3) 56(84) bytes of data.
- 64 bytes from 35.163.178.3: icmp_seq=1 ttl=64 time=0.328 ms
- 64 bytes from 35.163.178.3: icmp_seq=2 ttl=64 time=0.264 ms
- 64 bytes from 35.163.178.3: icmp_seq=3 ttl=64 time=0.412 ms
+if_up_cmd = '<path to script> up $_IP_$ <interface> <route table ID> <path to awscli>'
+if_down_cmd = '<path to script> down $_IP_$ <interface> <route table ID> <path to awscli>'
-
-
-
- "psql -h ELASTIC_IP -p port"でPostgreSQLに接続してみます。
+
+
+
+
+ <path to script>: ルートテーブルの書き換えを行うスクリプトのパスを指定します。
+
+
+
+
+
+ <interface>: 仮想IPを割り当てるネットワークインターフェイスを指定します。
+
+
+
+
+
+ <route table ID>: 書き換え対象（接続元のアプリケーションやPgpool-IIインスタンス）となるルートテーブルIDを指定します。カンマ区切りで複数のルートテーブルIDを指定できます。
+
+
+
+
+
+ <path to awscli>: AWS CLIのパスを指定します。
+
+
+
+
+
+
+ この設定例では、以下のように指定します。環境に合わせて、設定してください。ルートテーブルIDにパブリックサブネットおよびプライベートサブネットのルートテーブルIDを指定します。
+
+
- [user@someserver]$ psql -h 35.163.178.3 -p 9999 -l
+if_up_cmd = '/etc/pgpool-II/aws_rtb_if_cmd.sh up $_IP_$ eth0 rtb-012345abcd,rtb-67890abcd /usr/local/bin/aws'
+if_down_cmd = '/etc/pgpool-II/aws_rtb_if_cmd.sh down $_IP_$ eth0 rtb-012345abcd,rtb-67890abcd /usr/local/bin/aws'
-
-
-
-
- Elastic IPの切換
-
-
- アクティブなサーバが使用できなくなった時にスタンバイサーバがElastic IPを獲得できることを確認するために、アクティブサーバ上のPgpool-IIを停止します。
- すると、スタンバイサーバはElastic IPアドレスを使い始めるはずです。
- Pgpool-IIのログには以下のようなメッセージが表示されます。
+
+ arpingコマンドは実行不要なので、常に成功させるようにtrueに設定します。
+
-
- LOG: remote node "172.31.2.94:9999 [Linux ip-172-31-2-94]" is shutting down
- LOG: watchdog cluster has lost the coordinator node
-
- LOG: watchdog node state changed from [STANDBY] to [JOINING]
- LOG: watchdog node state changed from [JOINING] to [INITIALIZING]
- LOG: I am the only alive node in the watchdog cluster
- HINT: skipping stand for coordinator state
- LOG: watchdog node state changed from [INITIALIZING] to [LEADER]
- LOG: I am announcing my self as leader/coordinator watchdog node
- LOG: I am the cluster leader node
- DETAIL: our declare coordinator message is accepted by all nodes
- LOG: I am the cluster leader node. Starting escalation process
- LOG: escalation process started with PID:23543
- LOG: watchdog: escalation started
-
- Assigning Elastic IP 35.163.178.3 to the instance i-0dd3e60734a6ebe14
- {
- "AssociationId": "eipassoc-39853c42"
- }
-
- LOG: watchdog escalation successful
- LOG: watchdog escalation process with pid: 61581 exit with SUCCESS.
+arping_cmd = 'true'
-
- Elastic IPアドレスにpingが通ることを再度確かめます。
+
+
+
+ ルートテーブル書き換え用のスクリプト
+
+ if_up_cmd/if_down_cmdで実行するスクリプトをすべてのPgpool-IIインスタンス上に作成します。
+
+
+ この設定例では、サンプルスクリプトaws_rtb_if_cmd.shを使用します。必要に応じて、編集してください。
+
- [user@someserver]$ ping 35.163.178.3
- PING 35.163.178.3 (35.163.178.3) 56(84) bytes of data.
- 64 bytes from 35.163.178.3: icmp_seq=1 ttl=64 time=0.328 ms
- 64 bytes from 35.163.178.3: icmp_seq=2 ttl=64 time=0.264 ms
- 64 bytes from 35.163.178.3: icmp_seq=3 ttl=64 time=0.412 ms
+(すべてのPgpool-IIインスタンスで実行)
+# cp -p /etc/pgpool-II/aws_rtb_if_cmd.sh{.sample,}
-
-
-
- "psql -h ELASTIC_IP -p port"でPostgreSQLに接続してみます。
+
+
+
+ 「送信元/送信先チェック」の無効化
+
+ AWSのネットワークインターフェイスのデフォルト設定では、トラフィックの送信元または送信先をチェックします。
+ ルーティングの設定を行うインスタンスでは、この設定を無効にする必要があります。
+
+
+ すべてのPgpool-IIインスタンスのネットワークインターフェイスの設定で「送信元/送信先チェック」を無効にします。
+ AWSコンソールまたは AWS CLIを使用して設定可能です。
+ AWS CLIを使って設定を行う場合、以下のコマンドを実行します。
+ LOCAL_INTERFACEに仮想IPを割り当てるネットワークインターフェイスを指定します。
+ この設定例では、eth0を指定します。
+
+
- [user@someserver]$ psql -h 35.163.178.3 -p 9999 -l
+$ sudo su - postgres
+$ TOKEN=$(curl -sX PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
+$ LOCAL_INTERFACE=eth0
+$ MAC_ADDR=$(ip -br link show dev ${LOCAL_INTERFACE} | tr -s ' ' | cut -d ' ' -f3)
+$ EC2_NETWORK_INTERFACE_ID=$(curl -H "X-aws-ec2-metadata-token: ${TOKEN}" -s http://169.254.169.254/latest/meta-data/network/interfaces/macs/${MAC_ADDR}/interface-id)
+$ aws ec2 modify-network-interface-attribute --network-interface-id ${EC2_NETWORK_INTERFACE_ID} --no-source-dest-check
-
+
+
+ 以上で、設定は完了です。
+
+
+
+
+ 実行してみる
+
+ Pgpool-IIを起動し、アプリケーションインスタンスから仮想IPアドレスを使ってPgpool-IIに接続してみます。
+
+
+[user@someserver]$ psql -h 20.0.0.50 -p 9999 -U postgres -c "show pool_nodes"
+
+
+ リーダーPgpool-IIを停止し、仮想IPが新しいリーダーに付与され、仮想IPを使ってPgpool-IIに接続できることを確認します。
+
+
+[user@someserver]$ psql -h 20.0.0.50 -p 9999 -U postgres -c "show pool_nodes"
+
+
+
+
+ AWSコマンドリファレンス
+
+
+
+ <ulink url="http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html">Configure AWS CLI</ulink>
+
+
+ AWS Documentation: Configuring the AWS Command Line Interface
+
+
+
+
+
+ <ulink url="http://docs.aws.amazon.com/cli/latest/reference/ec2/associate-address.html">associate-address</ulink>
+
+
+ AWS Documentation: associate-address reference
+
+
+
+
+
+ <ulink url="http://docs.aws.amazon.com/cli/latest/reference/ec2/disassociate-address.html">disassociate-address</ulink>
+
+
+ AWS Documentation: disassociate-address reference
+
+
+
+
+
+ <ulink url="https://docs.aws.amazon.com/cli/latest/reference/ec2/create-route.html">create-route</ulink>
+
+
+ AWS Documentation: create-route reference
+
+
+
+
+
+ <ulink url="https://docs.aws.amazon.com/cli/latest/reference/ec2/replace-route.html">replace-route</ulink>
+
+
+ AWS Documentation: replace-route reference
+
+
+
+
+
+ <ulink url="https://docs.aws.amazon.com/cli/latest/reference/ec2/delete-route.html">delete-route</ulink>
+
+
+ AWS Documentation: delete-route reference
+
+
+
+
+
+ <ulink url="https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-network-interface-attribute.html">modify-network-interface-attribute</ulink>
+
+
+ AWS Documentation: modify-network-interface-attribute
+
+
+
+
diff --git a/doc/src/sgml/example-AWS.sgml b/doc/src/sgml/example-AWS.sgml
index 0b33306..ab561da 100644
--- a/doc/src/sgml/example-AWS.sgml
+++ b/doc/src/sgml/example-AWS.sgml
@@ -4,273 +4,529 @@
AWS Configuration Example
- This tutorial explains the simple way to try "Watchdog"
- on AWS and using
- the
- Elastic IP Address as the Virtual IP for the high availability solution.
-
+ This tutorial shows an example of setting a virtual IP
+ when using watchdog on AWS.
+
+
+ There are several methods to set up a virtual IP on AWS. This example describes the following methods:
+
+
+
- You can use watchdog with
- Pgpool-II in any mode: replication mode,
- native replication mode and raw mode.
+ Assigning Elastic IP
-
-
+
-
- AWS Setup
+
+
+ Updating route table
+
+
+
+
+
+ Assigning Elastic IP
- For this example, we will use two node
- Pgpool-II watchdog cluster. So we will set up two
- Linux Amazon EC2 instances and one Elastic IP address.
- So for this example, do the following steps:
+ This section explains how to use an Elastic IP address as a virtual IP and associate it with the leader Pgpool-II (watchdog) instance.
-
-
-
-
- Launch two Linux Amazon EC2 instances. For this example, we name these
- instances as "instance-1" and "instance-2"
-
-
-
-
-
- Configure the security group for the instances and allow inbound traffic
- on ports used by pgpool-II and watchdog.
-
-
-
-
-
- Install the Pgpool-II on both instances.
-
-
-
-
-
- Allocate an Elastic IP address.
- For this example, we will use "35.163.178.3" as an Elastic IP address"
-
-
-
-
+
+ AWS Setup
+
+ When using this method, it is assumed that the Pgpool-II
+ EC2 instance is placed in a public subnet and clients connect to
+ Pgpool-II via Internet.
+ This method supports multiple availability zones.
+
+
+ In this example, we will use three nodes Pgpool-II
+ (watchdog) cluster. So we will create three EC2 instances and one Elastic IP address.
+
+
+ Complete the following steps to setup AWS:
+
-
+
+
+
+
+ Launch three EC2 instances.
+
+
+
+
+
+ Configure the security group for the Pgpool-II instances.
+
+
+
+
+ Allow inbound traffic on ports used by Pgpool-II and watchdog.
+
+
+
+
+ Since Pgpool-II (watchdog) will ping the virtual IP to check connectivity,
+ allow inbound ICMP traffic from the Elastic IP (Source).
+
+
+
+
+
+
+
+ Install Pgpool-II on each instance.
+
+
+
+
+
+ AWS CLI is
+ a tool to manage your AWS services on EC2 instances.
+ Install AWS CLI on each Pgpool-II instance.
+
+
+
+ Furthermore, run aws configure as Pgpool-II startup user
+ to create the config and credentials files so that Pgpool-II
+ startup user can run AWS CLI.
+ If Pgpool-II is installed using RPM packages,
+ Pgpool-II is running as postgres
+ user by default.
+
+
+
+
+
+ Allocate an Elastic IP address.
+ In this example, we will use "35.163.178.3".
+
+
+
+
-
- <productname>Pgpool-II</productname> configurations
-
- Mostly the Pgpool-II configurations for this
- example will be same as in the , except the
- which we will not set in this example instead
- we will use and
- to switch the
- Elastic IP address to the leader/Active Pgpool-II node.
-
-
+
+ <productname>Pgpool-II</productname> configurations
+
+ This section explains how to configure Pgpool-II.
+ Mostly the Pgpool-II configurations for this
+ example will be same as in the , except
+ using /
+ to assign/remove an Elastic IP address to/from the leader
+ Pgpool-II instance.
+
+
+ Specify the Elastic IP address to .
+
+
use_watchdog = on
-delegate_ip = ''
-...
-wd_escalation_command = '$path_to_script/aws-escalation.sh'
-wd_de_escalation_command = '$path_to_script/aws-de-escalation.sh'
-
-
-
-
- escalation and de-escalation Scripts
-
- Create the aws-escalation.sh and aws-de-escalation.sh scripts on both
- instances and point the and
- to the respective scripts.
-
+delegate_ip = '35.163.178.3'
+
-
- You may need to configure the AWS CLI first on all AWS instances
- to enable the execution of commands used by wd-escalation.sh and wd-de-escalation.sh.
- See configure AWS CLI
+ Specify the script used to assign/remove Elastic IP address to
+ and .
+ is the script executed by the watchdog to
+ assign the Elastic IP to the instance when watchdog becomes the leader node.
+ is the script executed by watchdog to
+ remove the Elastic IP from the instance when watchdog resign from the leader node.
-
-
- escalation script
+
+if_up_cmd = '<path to script> up $_IP_$ <path to awscli>'
+if_down_cmd = '<path to script> down $_IP_$ <path to awscli>'
+
+
+
+
+
+ <path to script>: Specify the path to the script used to assgin or remove Elastic IP address.
+
+
+
+
+
+ <path to awscli>: Specify the path to AWS CLI command.
+
+
+
- This script will be executed by the watchdog
- to assign the Elastic IP on the instance when the watchdog becomes the active/leader node.
- Change the INSTANCE_ID and ELASTIC_IP values as per your AWS setup values.
+ In this example, we use the following settings. Replace them with your own settings.
-
- aws-escalation.sh:
-
- #! /bin/sh
- ELASTIC_IP=35.163.178.3
- # replace it with the Elastic IP address you
- # allocated from the aws console
- INSTANCE_ID=i-0a9b64e449b17ed4b
- # replace it with the instance id of the Instance
- # this script is installed on
+
+if_up_cmd = '/etc/pgpool-II/aws_eip_if_cmd.sh up $_IP_$ /usr/local/bin/aws'
+if_down_cmd = '/etc/pgpool-II/aws_eip_if_cmd.sh down $_IP_$ /usr/local/bin/aws'
+
- echo "Assigning Elastic IP $ELASTIC_IP to the instance $INSTANCE_ID"
- # bring up the Elastic IP
- aws ec2 associate-address --instance-id $INSTANCE_ID --public-ip $ELASTIC_IP
+
+ Because arping isn't required on AWS, set it to 'true' to always return a successful exit status.
+
+
+arping_cmd = 'true'
+
- exit 0
-
+
+
+ Elastic IP assigning/removing script
+
+ Create the script executed by if_up_cmd/if_down_cmd on each Pgpool-II instance.
+
+
+ In this example, we use the sample script aws_eip_if_cmd.sh. Modify it if necessary.
+
+(run the following command on each Pgpool-II instance)
+# cp -p /etc/pgpool-II/aws_eip_if_cmd.sh{.sample,}
+
-
- de-escalation script
+
+ Try it out
+
+ Start Pgpool-II on each Pgpool-II
+ instance.
+ Try to connect to Pgpool-II using the Elastic IP address.
+
+
+[user@someserver]$ psql -h 35.163.178.3 -p 9999 -U postgres -c "show pool_nodes"
+
+
+ Stop the leader Pgpool-II.
+ Then the Elastic IP address is reassigned to the new leader Pgpool-II.
+ Verify that you can connect to Pgpool-II
+ using Elastic IP address even if the leader Pgpool-II
+ has switched over.
+
+
+[user@someserver]$ psql -h 35.163.178.3 -p 9999 -U postgres -c "show pool_nodes"
+
+
+
+
+
+ Updating Route Table
+
+ This section describes how to control routing for the leader Pgpool-II (watchdog)
+ by updating the route table entry.
+
+
+ In this method, a private IP address is used as a virtual IP and assigned to the
+ leader Pgpool-II instance. If a failover occurs, reassign the virtual IP,
+ and route traffic with a destination address of the virtual IP to the new leader
+ Pgpool-II instance by updating route tables.
+
+
+ AWS Setup
- This script will be executed by watchdog
- to remove the Elastic IP from the instance when the watchdog resign from the active/leader node.
+ When using this method, it is assumed that the Pgpool-II
+ EC2 instance is placed in a private subnet and the client application connects to
+ Pgpool-II within the same VPC.
+ This method supports multiple Availability Zones.
- aws-de-escalation.sh:
-
- #! /bin/sh
-
- ELASTIC_IP=35.163.178.3
- # replace it with the Elastic IP address you
- # allocated from the aws console
-
- echo "disassociating the Elastic IP $ELASTIC_IP from the instance"
- # bring down the Elastic IP
- aws ec2 disassociate-address --public-ip $ELASTIC_IP
- exit 0
-
+ In this example, we will use three nodes
+ Pgpool-II (watchdog) cluster. So we will create three
+ EC2 instances across multiple Availability Zones.
+
+ Complete the following steps to setup AWS:
+
+
+
+
+
+
+ Create a VPC with one public subnet and three private subnets,
+ and each private subnet is in a different Availability Zone.
+ For detailed information, please refer to the
+ documentation.
+
+
+
+
+
+ create two route tables associated with the public subnet and the private subnet
+ respectively. Please refer to this documetation
+ for detailed information.
+
+
+
+
+
+ Launch one application EC2 instance in the public subnet and
+ three Pgpool-II EC2 instances in different private subnets.
+
+
+
+
+
+ Configure a security group allowing traffic from the VPC CIDR block range
+ on the ports used by Pgpool-II and watchdog.
+
+
+
+
+
+ Install Pgpool-II on each Pgpool-II EC2 instance.
+
+
+
+
+
+ AWS CLI is
+ a tool to manage your AWS services on EC2 instances.
+ Install AWS CLI on each Pgpool-II instance.
+
+
+
+ Furthermore, run aws configure as Pgpool-II startup user
+ to create the config and credentials files so that Pgpool-II
+ startup user can run AWS CLI.
+ If Pgpool-II is installed using RPM packages,
+ Pgpool-II is running as postgres
+ user by default.
+
+
+
+
+
+ Assigning or removing a virtual IP address requires root privileges.
+ If you start Pgpool-II as a non-root user,
+ configure the sudoers file and allow this user to run sudo without being
+ asked for the password.
+ If Pgpool-II is installed using RPM packages,
+ the settings for postgres user are automatically added to sudoers.
+
+
+
+
+
+ Choose an IPv4 address to be used as the virtual IP.
+ Because the secondary IP address cannot be reassigned across multiple subnets,
+ you need to choose a private IP address which should not belong to
+ the IP addresses range for VPC.
+ In this example, we use "20.0.0.50".
+
+
+
-
- AWS Command References
-
-
-
- <ulink url="http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html">Configure AWS CLI</ulink>
-
-
- AWS Documentation: Configuring the AWS Command Line Interface
-
-
-
-
-
- <ulink url="http://docs.aws.amazon.com/cli/latest/reference/ec2/associate-address.html">associate-address</ulink>
-
-
- AWS Documentation: associate-address reference
-
-
-
-
-
- <ulink url="http://docs.aws.amazon.com/cli/latest/reference/ec2/disassociate-address.html">disassociate-address</ulink>
-
-
- AWS Documentation: disassociate-address reference
-
-
+
+ <productname>Pgpool-II</productname> configurations
+
+ This section explains how to configure Pgpool-II.
+ Mostly the Pgpool-II configurations for this
+ example will be same as in the , except
+ using and
+ to assign the virtaul IP and update route tables.
+
+
+ Specify the virtual IP to .
+
-
-
+
+use_watchdog = on
+delegate_ip = '20.0.0.50'
+
-
- Try it out
-
- Start Pgpool-II on each server with "-n" switch
- and redirect log messages to the pgpool.log file.
- The log message of leader/active Pgpool-II node
- will show the message of Elastic IP assignment.
+
+ Specify the script used to update route table to
+ and .
+ is the script executed by watchdog to
+ assign the virtual IP and update route tables when watchdog becomes the leader node.
+ is the script executed by watchdog to
+ remove the virtual IP and update route tables when watchdog resign from the leader node.
+
- LOG: I am the cluster leader node. Starting escalation process
- LOG: escalation process started with PID:23543
- LOG: watchdog: escalation started
-
- Assigning Elastic IP 35.163.178.3 to the instance i-0a9b64e449b17ed4b
- {
- "AssociationId": "eipassoc-39853c42"
- }
-
- LOG: watchdog escalation successful
- LOG: watchdog escalation process with pid: 23543 exit with SUCCESS.
+if_up_cmd = '<path to script> up $_IP_$ <interface> <route table ID> <path to awscli>'
+if_down_cmd = '<path to script> down $_IP_$ <interface> <route table ID> <path to awscli>'
-
-
- Confirm to ping to the Elastic IP address.
+
+
+
+
+ <path to script>: Specify the path to the script used to assign the virtual IP and update route tables.
+
+
+
+
+
+ <interface>: Specify the network interface to assign the virtual IP.
+
+
+
+
+
+ <route table ID>: Specify the route table IDs (e.g. client application or
+ Pgpool-II instance) to be updated.
+ You can specify multiple comma separated route table IDs.
+
+
+
+
+
+ <path to awscli>: Specify the path to AWS CLI command.
+
+
+
+
+
+
+ In this example, we use the following settings. Replace them with your own settings.
+ Specify the route table IDs associated with the public subnet where the application
+ EC2 instance is located and the private subnet where the Pgpool-II
+ EC2 instances are located.
+
+
- [user@someserver]$ ping 35.163.178.3
- PING 35.163.178.3 (35.163.178.3) 56(84) bytes of data.
- 64 bytes from 35.163.178.3: icmp_seq=1 ttl=64 time=0.328 ms
- 64 bytes from 35.163.178.3: icmp_seq=2 ttl=64 time=0.264 ms
- 64 bytes from 35.163.178.3: icmp_seq=3 ttl=64 time=0.412 ms
+if_up_cmd = '/etc/pgpool-II/aws_rtb_if_cmd.sh up $_IP_$ eth0 rtb-012345abcd,rtb-67890abcd /usr/local/bin/aws'
+if_down_cmd = '/etc/pgpool-II/aws_rtb_if_cmd.sh down $_IP_$ eth0 rtb-012345abcd,rtb-67890abcd /usr/local/bin/aws'
-
-
- Try to connect PostgreSQL by "psql -h ELASTIC_IP -p port".
+
+ Because arping isn't required on AWS, set it to 'true' to always return a successful exit status.
+
- [user@someserver]$ psql -h 35.163.178.3 -p 9999 -l
+arping_cmd = 'true'
-
-
+
-
- Switching Elastic IP
-
- To confirm if the Standby server acquires the Elastic IP when the
- Active server becomes unavailable, Stop the Pgpool-II
- on the Active server. Then, the Standby server should start using the Elastic IP address,
- And the Pgpool-II log will show the below messages.
+
+ Route table updating script
+
+ Create the script executed by if_up_cmd/if_down_cmd on each
+ Pgpool-II instance.
+
+
+ In this example, we use the sample script aws_rtb_if_cmd.sh. Modify it if necessary.
+
+
+(run the following command on each Pgpool-II instance)
+# cp -p /etc/pgpool-II/aws_rtb_if_cmd.sh{.sample,}
+
+
+
+
+ Disabling source/destination check
+
+ AWS EC2 instance checks the source or the destination of any received
+ traffics by default. You must disable source/destination check on each
+ Pgpool-II instance to route the traffic for virtual IP
+ to the target instance.
+
+
+ Disable "source/destination check" in the network interface settings of all
+ Pgpool-II instances.
+ It can be configured through the AWS Management Console
+ or using AWS CLI. When using the AWS CLI, execute the following command.
+ Set LOCAL_INTERFACE to the network interface where the virtual IP will be added.
+ In the example, we use eth0.
+
-
- LOG: remote node "172.31.2.94:9999 [Linux ip-172-31-2-94]" is shutting down
- LOG: watchdog cluster has lost the coordinator node
-
- LOG: watchdog node state changed from [STANDBY] to [JOINING]
- LOG: watchdog node state changed from [JOINING] to [INITIALIZING]
- LOG: I am the only alive node in the watchdog cluster
- HINT: skipping stand for coordinator state
- LOG: watchdog node state changed from [INITIALIZING] to [LEADER]
- LOG: I am announcing my self as leader/coordinator watchdog node
- LOG: I am the cluster leader node
- DETAIL: our declare coordinator message is accepted by all nodes
- LOG: I am the cluster leader node. Starting escalation process
- LOG: escalation process started with PID:23543
- LOG: watchdog: escalation started
-
- Assigning Elastic IP 35.163.178.3 to the instance i-0dd3e60734a6ebe14
- {
- "AssociationId": "eipassoc-39853c42"
- }
-
- LOG: watchdog escalation successful
- LOG: watchdog escalation process with pid: 61581 exit with SUCCESS.
+$ sudo su - postgres
+$ TOKEN=$(curl -sX PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
+$ LOCAL_INTERFACE=eth0
+$ MAC_ADDR=$(ip -br link show dev ${LOCAL_INTERFACE} | tr -s ' ' | cut -d ' ' -f3)
+$ EC2_NETWORK_INTERFACE_ID=$(curl -H "X-aws-ec2-metadata-token: ${TOKEN}" -s http://169.254.169.254/latest/meta-data/network/interfaces/macs/${MAC_ADDR}/interface-id)
+$ aws ec2 modify-network-interface-attribute --network-interface-id ${EC2_NETWORK_INTERFACE_ID} --no-source-dest-check
-
- Confirm to ping to the Elastic IP address again.
+
+
+ Try it out
+
+ Start Pgpool-II on each Pgpool-II
+ instance.
+ Try to connect to Pgpool-II using the virtual IP
+ from the application instance.
+
- [user@someserver]$ ping 35.163.178.3
- PING 35.163.178.3 (35.163.178.3) 56(84) bytes of data.
- 64 bytes from 35.163.178.3: icmp_seq=1 ttl=64 time=0.328 ms
- 64 bytes from 35.163.178.3: icmp_seq=2 ttl=64 time=0.264 ms
- 64 bytes from 35.163.178.3: icmp_seq=3 ttl=64 time=0.412 ms
+[user@appliaction instance]$ psql -h 20.0.0.50 -p 9999 -U postgres -c "show pool_nodes"
-
-
- Try to connect PostgreSQL by "psql -h ELASTIC_IP -p port".
+
+ Stop the leader Pgpool-II.
+ Then the virtual IP is reassigned to the new leader Pgpool-II.
+ Verify that you can connect to Pgpool-II
+ using Elastic IP address from application instance even if the leader
+ Pgpool-II has switched over.
+
- [user@someserver]$ psql -h 35.163.178.3 -p 9999 -l
+[user@application instance]$ psql -h 20.0.0.50 -p 9999 -U postgres -c "show pool_nodes"
-
+
+
+
+ AWS Command References
+
+
+
+ <ulink url="http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html">Configure AWS CLI</ulink>
+
+
+ AWS Documentation: Configuring the AWS Command Line Interface
+
+
+
+
+
+ <ulink url="http://docs.aws.amazon.com/cli/latest/reference/ec2/associate-address.html">associate-address</ulink>
+
+
+ AWS Documentation: associate-address reference
+
+
+
+
+
+ <ulink url="http://docs.aws.amazon.com/cli/latest/reference/ec2/disassociate-address.html">disassociate-address</ulink>
+
+
+ AWS Documentation: disassociate-address reference
+
+
+
+
+
+ <ulink url="https://docs.aws.amazon.com/cli/latest/reference/ec2/create-route.html">create-route</ulink>
+
+
+ AWS Documentation: create-route reference
+
+
+
+
+
+ <ulink url="https://docs.aws.amazon.com/cli/latest/reference/ec2/replace-route.html">replace-route</ulink>
+
+
+ AWS Documentation: replace-route reference
+
+
+
+
+
+ <ulink url="https://docs.aws.amazon.com/cli/latest/reference/ec2/delete-route.html">delete-route</ulink>
+
+
+ AWS Documentation: delete-route reference
+
+
+
+
+
+ <ulink url="https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-network-interface-attribute.html">modify-network-interface-attribute</ulink>
+
+
+ AWS Documentation: modify-network-interface-attribute
+
+
+
+
diff --git a/src/sample/scripts/aws_eip_if_cmd.sh b/src/sample/scripts/aws_eip_if_cmd.sh
index e69de29..ea81a01 100755
--- a/src/sample/scripts/aws_eip_if_cmd.sh
+++ b/src/sample/scripts/aws_eip_if_cmd.sh
@@ -0,0 +1,50 @@
+#!/bin/bash
+set -o xtrace
+
+CMD=$1
+ELASTIC_IP=$2
+AWSCLI=$3
+
+TOKEN=$(curl -sX PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
+INSTANCE_ID=$(curl -H "X-aws-ec2-metadata-token: $TOKEN" -s http://169.254.169.254/latest/meta-data/instance-id)
+ALLOCATION_ID=$(aws ec2 describe-addresses --query "Addresses[?PublicIp=='${ELASTIC_IP}'].AllocationId" --output text)
+
+if [ "${CMD}" == "up" ]; then
+
+ echo "running if_up_cmd"
+
+ echo "associate Elastic IP ${ELASTIC_IP} with instance ${INSTANCE_ID}"
+ ${AWSCLI} ec2 associate-address \
+ --instance-id ${INSTANCE_ID} \
+ --allocation-id ${ALLOCATION_ID}
+
+ if [ $? -ne 0 ]; then
+ echo "ERROR: failed to associates Elastic IP ${ELASTIC_IP} with instance ${INSTANCE_ID}" >&2
+ exit 1
+ fi
+
+elif [ "${CMD}" == "down" ]; then
+
+ echo "running if_down_cmd"
+
+ ASSOCIATION_ID=$(${AWSCLI} ec2 describe-addresses \
+ --query "Addresses[?PublicIp=='${ELASTIC_IP}'].AssociationId" --output text)
+
+ if [ -z "${ASSOCIATION_ID}" ]; then
+ echo "ERROR: failed to retrieve ASSOCIATION_ID while bringing down Elastic IP ${ELASTIC_IP}" >&2
+ exit 1
+ fi
+
+ echo "disassociate Elastic IP ${ELASTIC_IP} from instance ${INSTANCE_ID}"
+
+ ${AWSCLI} ec2 disassociate-address --association-id ${ASSOCIATION_ID}
+
+ if [ $? -ne 0 ]; then
+ echo "ERROR: failed to disassociate Elastic IP ${ELASTIC_IP} from instance ${INSTANCE_ID}" >&2
+ exit 1
+ fi
+
+fi
+
+echo "Elastic IP ${ELASTIC_IP} ${CMD} successfully"
+exit 0
diff --git a/src/sample/scripts/aws_rtb_if_cmd.sh b/src/sample/scripts/aws_rtb_if_cmd.sh
index e69de29..6434138 100755
--- a/src/sample/scripts/aws_rtb_if_cmd.sh
+++ b/src/sample/scripts/aws_rtb_if_cmd.sh
@@ -0,0 +1,75 @@
+#!/bin/bash
+set -o xtrace
+
+CMD=$1
+VIP=$2
+LOCAL_INTERFACE=$3
+ROUTE_TABLE_ID=$4
+AWSCLI=$5
+
+TOKEN=$(curl -sX PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
+INSTANCE_ID=$(curl -H "X-aws-ec2-metadata-token: $TOKEN" -s http://169.254.169.254/latest/meta-data/instance-id)
+
+#SUBNET_ID=$(/usr/local/bin/aws ec2 describe-instances --instance-id ${INSTANCE_ID} --query "Reservations[*].Instances[].SubnetId" --output text)
+#ROUTE_TABLE_ID=$(/usr/local/bin/aws ec2 describe-route-tables --query "RouteTables[*].Associations[?SubnetId=='${SUBNET_ID}'].RouteTableId" --output text)
+MAC_ADDR=$(ip -br link show dev ${LOCAL_INTERFACE} | tr -s ' ' | cut -d ' ' -f3)
+NETWORK_INTERFACE_ID=$(curl -H "X-aws-ec2-metadata-token: $TOKEN" -s http://169.254.169.254/latest/meta-data/network/interfaces/macs/${MAC_ADDR}/interface-id)
+
+if [ "${CMD}" == "up" ]; then
+
+ echo "running if_up_cmd"
+
+ for rtb in $(echo ${ROUTE_TABLE_ID} | sed -e 's/,/ /g'); do
+
+ echo "create route entry for ${VIP}/32 if it doesn't exist"
+ ${AWSCLI} ec2 create-route --route-table-id ${rtb} \
+ --destination-cidr-block ${VIP}/32 --network-interface-id ${NETWORK_INTERFACE_ID}
+
+ if [ $? -ne 0 ]; then
+ echo "replace route entry for ${VIP}/32"
+ ${AWSCLI} ec2 replace-route --route-table-id ${rtb} \
+ --destination-cidr-block ${VIP}/32 --network-interface-id ${NETWORK_INTERFACE_ID}
+
+ if [ $? -ne 0 ]; then
+ echo "ERROR: failed to replace route entry for ${VIP}/32" >&2
+ exit 1
+ fi
+ fi
+ done
+
+ echo "assign virtual IP ${VIP}/32 to local network interface ${LOCAL_INTERFACE}"
+ /usr/bin/sudo /sbin/ip addr add ${VIP}/32 dev ${LOCAL_INTERFACE} label ${LOCAL_INTERFACE}:1
+
+ if [ $? -ne 0 ]; then
+ echo "ERROR: failed to assign virtual IP ${VIP}/32" >&2
+ exit 1
+ fi
+
+elif [ "${CMD}" == "down" ]; then
+
+ echo "running if_down_cmd"
+
+ echo "remove virtual IP ${VIP}/32 from local network interface ${LOCAL_INTERFACE}"
+ /usr/bin/sudo /sbin/ip addr del ${VIP}/32 dev ${LOCAL_INTERFACE}
+
+ if [ $? -ne 0 ]; then
+ echo "ERROR: failed to remove virtual IP ${VIP}/32" >&2
+ fi
+
+ for rtb in $(echo ${ROUTE_TABLE_ID} | sed -e 's/,/ /g'); do
+ echo "remove route entry for ${VIP}/32"
+ ${AWSCLI} ec2 delete-route --route-table-id ${rtb} --destination-cidr-block ${VIP}/32
+
+ if [ $? -ne 0 ]; then
+ echo "ERROR: failed to remove route from route table ${rtb}" >&2
+ fi
+ done
+
+ echo "remove remaining route entry if any"
+ ip route show to exact ${VIP}/32 dev ${LOCAL_INTERFACE} | xargs -r ip route delete
+ ip route show table local to exact ${VIP}/32 dev ${LOCAL_INTERFACE} | xargs -r ip route delete
+
+fi
+
+echo "virtual IP ${VIP} ${CMD} successfully"
+exit 0