pgpool-II 4.7.0 Documentation
Prev | Up | Chapter 8. Configuration Examples | Next

# 8.4. AWS Configuration Example

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:

- Section 8.4.1 Assigning Elastic IP

- Section 8.4.2 Updating route table

## 8.4.1. Assigning Elastic IP

This section explains how to use an Elastic IP address as a virtual IP and associate it with the leader Pgpool-II (watchdog) instance.

### 8.4.1.1. 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".

### 8.4.1.2. Pgpool-II configurations

This section explains how to configure Pgpool-II. Mostly the Pgpool-II configurations for this example will be same as in the Section 8.2, except using if_up_cmd/if_down_cmd to assign/remove an Elastic IP address to/from the leader Pgpool-II instance.

Specify the Elastic IP address to delegate_ip.

    use_watchdog = on
    delegate_ip = '35.163.178.3'

Specify the script used to assign/remove Elastic IP address to if_up_cmd and if_down_cmd. if_up_cmd is the script executed by the watchdog to assign the Elastic IP to the instance when watchdog becomes the leader node. if_down_cmd is the script executed by watchdog to remove the Elastic IP from the instance when watchdog resign from the leader node.

    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 assign or remove Elastic IP address.

- <path to awscli>: Specify the path to AWS CLI command.

In this example, we use the following settings. Replace them with your own settings.

    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'

Because `arping` isn't required on AWS, set it to 'true' to always return a successful exit status.

    arping_cmd = 'true'

### 8.4.1.3. 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/sample_scripts/aws_eip_if_cmd.sh.sample /etc/pgpool-II/aws_eip_if_cmd.sh

### 8.4.1.4. 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"

## 8.4.2. 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.

### 8.4.2.1. AWS Setup

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.

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 documentation 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".

### 8.4.2.2. Pgpool-II configurations

This section explains how to configure Pgpool-II. Mostly the Pgpool-II configurations for this example will be same as in the Section 8.2, except using if_up_cmd and if_down_cmd to assign the virtual IP and update route tables.

Specify the virtual IP to delegate_ip.

    use_watchdog = on
    delegate_ip = '20.0.0.50'

Specify the script used to update route table to if_up_cmd and if_down_cmd. if_up_cmd is the script executed by watchdog to assign the virtual IP and update route tables when watchdog becomes the leader node. if_down_cmd is the script executed by watchdog to remove the virtual IP and update route tables when watchdog resign from the leader node.

    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>'

- <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.

    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'

Because `arping` isn't required on AWS, set it to 'true' to always return a successful exit status.

    arping_cmd = 'true'

### 8.4.2.3. 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/sample_scripts/aws_rtb_if_cmd.sh.sample /etc/pgpool-II/aws_rtb_if_cmd.sh

### 8.4.2.4. 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.

    $ 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

### 8.4.2.5. 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@application instance]$ psql -h 20.0.0.50 -p 9999 -U postgres -c "show pool_nodes"

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@application instance]$ psql -h 20.0.0.50 -p 9999 -U postgres -c "show pool_nodes"

### AWS Command References

"Configure AWS CLI", AWS Documentation: Configuring the AWS Command Line Interface.

"associate-address", AWS Documentation: associate-address reference.

"disassociate-address", AWS Documentation: disassociate-address reference.

"create-route", AWS Documentation: create-route reference.

"replace-route", AWS Documentation: replace-route reference.

"delete-route", AWS Documentation: delete-route reference.

"modify-network-interface-attribute", AWS Documentation: modify-network-interface-attribute.

Prev | Home | Next
Replication Mode and Snapshot Isolation Mode Configuration Example | Up | Aurora Configuration Example