path: root/doc/src/sgml/example-AWS.sgml

<!-- doc/src/sgml/example-AWS.sgml -->

<sect1 id="example-AWS">
 <title>AWS Configuration Example</title>

 <para>
  This tutorial shows an example of setting a virtual IP
  when using watchdog on <ulink url="https://aws.amazon.com/">AWS</ulink>.
 </para>
 <para>
  There are several methods to set up a virtual IP on AWS. This example describes the following methods:
 </para>
 <itemizedlist>
  <listitem>
   <para>
    <xref linkend="example-AWS-eip"> Assigning Elastic IP
   </para>
  </listitem>

  <listitem>
   <para>
    <xref linkend="example-AWS-rtb"> Updating route table
   </para>
  </listitem>
 </itemizedlist>

 <sect2 id="example-AWS-eip">
  <title>Assigning Elastic IP</title>
  <para>
   This section explains how to use an Elastic IP address as a virtual IP and associate it with the leader Pgpool-II (watchdog) instance.
  </para>

  <sect3 id="example-AWS-eip-setup">
   <title>AWS Setup</title>
   <para>
    When using this method, it is assumed that the <productname>Pgpool-II</productname>
    EC2 instance is placed in a public subnet and clients connect to
    <productname>Pgpool-II</productname> via Internet.
    <EMPHASIS>This method supports multiple availability zones.</EMPHASIS>
   </para>
   <para>
    In this example, we will use three nodes <productname>Pgpool-II</productname>
    (watchdog) cluster. So we will create three EC2 instances and one Elastic IP address.
   </para>
   <para>
    Complete the following steps to setup AWS:
   </para>

   <itemizedlist>

    <listitem>
     <para>
      Launch three EC2 instances.
     </para>
    </listitem>

    <listitem>
     <para>
      Configure the security group for the <productname>Pgpool-II</productname> instances.
     </para>
     <itemizedlist>
      <listitem>
       <para>
        Allow inbound traffic on ports used by <productname>Pgpool-II</productname> and watchdog.
       </para>
      </listitem>
      <listitem>
       <para>
        Since <productname>Pgpool-II</productname> (watchdog) will ping the virtual IP to check connectivity,
        allow inbound ICMP traffic from the Elastic IP (Source).
       </para>
      </listitem>
     </itemizedlist>
    </listitem>

    <listitem>
     <para>
      Install <productname>Pgpool-II</productname> on each instance.
     </para>
    </listitem>

    <listitem>
     <para>
      <ulink url="https://docs.aws.amazon.com/cli/index.html">AWS CLI</ulink> is
      a tool to manage your AWS services on EC2 instances.
      Install <ulink url="https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html">AWS CLI</ulink> on each <productname>Pgpool-II</productname> instance.
     </para>

     <para>
      Furthermore, <EMPHASIS>run aws configure as Pgpool-II startup user</EMPHASIS>
      to create the config and credentials files so that <productname>Pgpool-II</productname>
      startup user can run AWS CLI.
      If <productname>Pgpool-II</productname> is installed using RPM packages,
      <productname>Pgpool-II</productname> is running as <literal>postgres</literal>
      user by default.
     </para>
    </listitem>

    <listitem>
     <para>
      Allocate an Elastic IP address.
      In this example, we will use "35.163.178.3".
     </para>
    </listitem>
   </itemizedlist>
  </sect3>

  <sect3 id="example-AWS-eip-pgpool-config">
   <title><productname>Pgpool-II</productname> configurations</title>
   <para>
    This section explains how to configure <productname>Pgpool-II</productname>.
    Mostly the <productname>Pgpool-II</productname> configurations for this
    example will be same as in the <xref linkend="example-cluster">, except
    using <xref linkend="guc-if-up-cmd">/<xref linkend="guc-if-down-cmd">
    to assign/remove an Elastic IP address to/from the leader
    <productname>Pgpool-II</productname> instance.
   </para>
   <para>
    Specify the Elastic IP address to <xref linkend="guc-delegate-ip">.
   </para>
   <programlisting>
use_watchdog = on
delegate_ip = '35.163.178.3'
   </programlisting>

   <para>
    Specify the script used to assign/remove Elastic IP address to
    <xref linkend="guc-if-up-cmd"> and <xref linkend="guc-if-down-cmd">.
    <xref linkend="guc-if-up-cmd"> is the script executed by the watchdog to
    assign the Elastic IP to the instance when watchdog becomes the leader node.
    <xref linkend="guc-if-down-cmd"> is the script executed by watchdog to
    remove the Elastic IP from the instance when watchdog resign from the leader node.
   </para>

   <programlisting>
if_up_cmd = '&lt;path to script&gt; up $_IP_$ &lt;path to awscli&gt;'
if_down_cmd = '&lt;path to script&gt; down $_IP_$ &lt;path to awscli&gt;'
   </programlisting>

   <itemizedlist>
    <listitem>
     <para>
      &lt;path to script&gt;: Specify the path to the script used to assign or remove Elastic IP address.
     </para>
    </listitem>

    <listitem>
     <para>
      &lt;path to awscli&gt;: Specify the path to AWS CLI command.
     </para>
    </listitem>
   </itemizedlist>

   <para>
    In this example, we use the following settings. Replace them with your own settings.
   </para>

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

   <para>
    Because <command>arping</command> isn't required on AWS, set it to 'true' to always return a successful exit status.
   </para>
   <programlisting>
arping_cmd = 'true'
   </programlisting>

  </sect3>

  <sect3 id="example-AWS-eip-script">
   <title>Elastic IP assigning/removing script</title>
   <para>
    Create the script executed by if_up_cmd/if_down_cmd on each Pgpool-II instance.
   </para>
   <para>
    In this example, we use the sample script <ulink url="https://git.postgresql.org/gitweb/?p=pgpool2.git;a=blob_plain;f=src/sample/scripts/aws_eip_if_cmd.sh.sample;hb=refs/heads/V4_4_STABLE">aws_eip_if_cmd.sh</ulink>. Modify it if necessary.
   </para>
   <programlisting>
(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
   </programlisting>
  </sect3>

  <sect3 id="example-AWS-eip-try">
   <title>Try it out</title>
   <para>
    Start <productname>Pgpool-II</productname> on each <productname>Pgpool-II</productname>
    instance.
    Try to connect to <productname>Pgpool-II</productname> using the Elastic IP address.
   </para>
   <programlisting>
[user@someserver]$ psql -h 35.163.178.3 -p 9999 -U postgres -c "show pool_nodes"
   </programlisting>
   <para>
    Stop the leader <productname>Pgpool-II</productname>.
    Then the Elastic IP address is reassigned to the new leader <productname>Pgpool-II</productname>.
    Verify that you can connect to <productname>Pgpool-II</productname>
    using Elastic IP address even if the leader <productname>Pgpool-II</productname>
    has switched over.
   </para>
   <programlisting>
[user@someserver]$ psql -h 35.163.178.3 -p 9999 -U postgres -c "show pool_nodes"
   </programlisting>
  </sect3>
 </sect2>

 <sect2 id="example-AWS-rtb">
  <title>Updating Route Table</title>
  <para>
   This section describes how to control routing for the leader Pgpool-II (watchdog)
   by updating the route table entry.
  </para>
  <para>
   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.
  </para>

  <sect3 id="example-AWS-rtb-setup">
   <title>AWS Setup</title>
   <para>
    When using this method, it is assumed that the <productname>Pgpool-II</productname>
    EC2 instance is placed in a private subnet and the client application connects to
    <productname>Pgpool-II</productname> within the same VPC.
    <EMPHASIS>This method supports multiple Availability Zones.</EMPHASIS>
   </para>
   <para>
    In this example, we will use three nodes <productname>
    Pgpool-II</productname> (watchdog) cluster. So we will create three
    EC2 instances across multiple Availability Zones.
   </para>
   <para>
    Complete the following steps to setup AWS:
   </para>

   <itemizedlist>

    <listitem>
     <para>
      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
      <ulink url="https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Scenario2.html">documentation</ulink>.
     </para>
    </listitem>

    <listitem>
     <para>
      create two route tables associated with the public subnet and the private subnet
      respectively. Please refer to this <ulink url="https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Scenario2.html#VPC_Scenario2_Routing">documentation</ulink>
      for detailed information.
     </para>
    </listitem>

    <listitem>
     <para>
      Launch one application EC2 instance in the public subnet and
      three Pgpool-II EC2 instances in different private subnets.
     </para>
    </listitem>

    <listitem>
     <para>
      Configure a security group allowing traffic from the VPC CIDR block range
      on the ports used by <productname>Pgpool-II</productname> and watchdog.
     </para>
    </listitem>

    <listitem>
     <para>
      Install <productname>Pgpool-II</productname> on each Pgpool-II EC2 instance.
     </para>
    </listitem>

    <listitem>
     <para>
      <ulink url="https://docs.aws.amazon.com/cli/index.html">AWS CLI</ulink> is
      a tool to manage your AWS services on EC2 instances.
      Install <ulink url="https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html">AWS CLI</ulink> on each <productname>Pgpool-II</productname> instance.
     </para>

     <para>
      Furthermore, <EMPHASIS>run aws configure as Pgpool-II startup user</EMPHASIS>
      to create the config and credentials files so that <productname>Pgpool-II</productname>
      startup user can run AWS CLI.
      If <productname>Pgpool-II</productname> is installed using RPM packages,
      <productname>Pgpool-II</productname> is running as <literal>postgres</literal>
      user by default.
     </para>
    </listitem>

    <listitem>
     <para>
      Assigning or removing a virtual IP address requires root privileges.
      If you start <productname>Pgpool-II</productname> as a non-root user,
      configure the sudoers file and allow this user to run sudo without being
      asked for the password.
      If <productname>Pgpool-II</productname> is installed using RPM packages,
      the settings for <literal>postgres</literal> user are automatically added to sudoers.
     </para>
    </listitem>

    <listitem>
     <para>
      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".
     </para>
    </listitem>
   </itemizedlist>
  </sect3>

  <sect3 id="example-AWS-rtb-pgpool-config">
   <title><productname>Pgpool-II</productname> configurations</title>
   <para>
    This section explains how to configure <productname>Pgpool-II</productname>.
    Mostly the <productname>Pgpool-II</productname> configurations for this
    example will be same as in the <xref linkend="example-cluster">, except
    using <xref linkend="guc-if-up-cmd"> and <xref linkend="guc-if-down-cmd">
    to assign the virtual IP and update route tables.
   </para>
   <para>
    Specify the virtual IP to <xref linkend="guc-delegate-ip">.
   </para>

   <programlisting>
use_watchdog = on
delegate_ip = '20.0.0.50'
   </programlisting>

   <para>
    Specify the script used to update route table to
    <xref linkend="guc-if-up-cmd"> and <xref linkend="guc-if-down-cmd">.
    <xref linkend="guc-if-up-cmd"> is the script executed by watchdog to
    assign the virtual IP and update route tables when watchdog becomes the leader node.
    <xref linkend="guc-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.
   </para>
   <programlisting>
if_up_cmd = '&lt;path to script&gt; up $_IP_$ &lt;interface&gt; &lt;route table ID&gt; &lt;path to awscli&gt;'
if_down_cmd = '&lt;path to script&gt; down $_IP_$ &lt;interface&gt; &lt;route table ID&gt; &lt;path to awscli&gt;'
   </programlisting>

   <itemizedlist>

    <listitem>
     <para>
      &lt;path to script&gt;: Specify the path to the script used to assign the virtual IP and update route tables.
     </para>
    </listitem>

    <listitem>
     <para>
      &lt;interface&gt;: Specify the network interface to assign the virtual IP.
     </para>
    </listitem>

    <listitem>
     <para>
      &lt;route table ID&gt;: Specify the route table IDs (e.g. client application or
      <productname>Pgpool-II</productname> instance) to be updated.
      You can specify multiple comma separated route table IDs.
     </para>
    </listitem>

    <listitem>
     <para>
      &lt;path to awscli&gt;: Specify the path to AWS CLI command.
     </para>
    </listitem>

   </itemizedlist>

   <para>
    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 <productname>Pgpool-II</productname>
    EC2 instances are located.
   </para>

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

   <para>
    Because <command>arping</command> isn't required on AWS, set it to 'true' to always return a successful exit status.
   </para>
   <programlisting>
arping_cmd = 'true'
   </programlisting>
  </sect3>

  <sect3 id="example-AWS-rtb-script">
   <title>Route table updating script</title>
   <para>
    Create the script executed by <varname>if_up_cmd/if_down_cmd</varname> on each
    <productname>Pgpool-II</productname> instance.
   </para>
   <para>
    In this example, we use the sample script <ulink url="https://git.postgresql.org/gitweb/?p=pgpool2.git;a=blob_plain;f=src/sample/scripts/aws_rtb_if_cmd.sh.sample;hb=refs/heads/V4_4_STABLE">aws_rtb_if_cmd.sh</ulink>. Modify it if necessary.
   </para>
   <programlisting>
(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
   </programlisting>
  </sect3>

  <sect3 id="example-AWS-rtb-eni">
   <title>Disabling source/destination check</title>
   <para>
    AWS EC2 instance checks the source or the destination of any received
    traffics by default. You <EMPHASIS>must disable source/destination check</EMPHASIS> on each
    <productname>Pgpool-II</productname> instance to route the traffic for virtual IP
    to the target instance.
   </para>
   <para>
    Disable "source/destination check" in the network interface settings of all
    <productname>Pgpool-II</productname> instances.
    It can be configured through the AWS Management Console
    or using AWS CLI. When using the AWS CLI, execute the following command.
    Set <varname>LOCAL_INTERFACE</varname> to the network interface where the virtual IP will be added.
    In the example, we use eth0.
   </para>

   <programlisting>
$ 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=<EMPHASIS>eth0</EMPHASIS>
$ 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
   </programlisting>
  </sect3>

  <sect3 id="example-AWS-rbt-try">
   <title>Try it out</title>
   <para>
    Start <productname>Pgpool-II</productname> on each <productname>Pgpool-II</productname>
    instance.
    Try to connect to <productname>Pgpool-II</productname> using the virtual IP
    from the application instance.
   </para>
   <programlisting>
[user@application instance]$ psql -h 20.0.0.50 -p 9999 -U postgres -c "show pool_nodes"
   </programlisting>
   <para>
    Stop the leader <productname>Pgpool-II</productname>.
    Then the virtual IP is reassigned to the new leader <productname>Pgpool-II</productname>.
    Verify that you can connect to <productname>Pgpool-II</productname>
    using Elastic IP address from application instance even if the leader
    <productname>Pgpool-II</productname> has switched over.
   </para>
   <programlisting>
[user@application instance]$ psql -h 20.0.0.50 -p 9999 -U postgres -c "show pool_nodes"
   </programlisting>
  </sect3>
 </sect2>

 <bibliography>
  <title>AWS Command References</title>

  <biblioentry>
   <biblioset relation="article">
    <title><ulink url="http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html">Configure AWS CLI</ulink></title>
   </biblioset>
   <biblioset relation="book">
    <title>AWS Documentation: Configuring the AWS Command Line Interface</title>
   </biblioset>
  </biblioentry>

  <biblioentry>
   <biblioset relation="article">
    <title><ulink url="http://docs.aws.amazon.com/cli/latest/reference/ec2/associate-address.html">associate-address</ulink></title>
   </biblioset>
   <biblioset relation="book">
    <title>AWS Documentation: associate-address reference</title>
   </biblioset>
  </biblioentry>

  <biblioentry>
   <biblioset relation="article">
    <title><ulink url="http://docs.aws.amazon.com/cli/latest/reference/ec2/disassociate-address.html">disassociate-address</ulink></title>
   </biblioset>
   <biblioset relation="book">
    <title>AWS Documentation: disassociate-address reference</title>
   </biblioset>
  </biblioentry>

  <biblioentry>
   <biblioset relation="article">
    <title><ulink url="https://docs.aws.amazon.com/cli/latest/reference/ec2/create-route.html">create-route</ulink></title>
   </biblioset>
   <biblioset relation="book">
    <title>AWS Documentation: create-route reference</title>
   </biblioset>
  </biblioentry>

  <biblioentry>
   <biblioset relation="article">
    <title><ulink url="https://docs.aws.amazon.com/cli/latest/reference/ec2/replace-route.html">replace-route</ulink></title>
   </biblioset>
   <biblioset relation="book">
    <title>AWS Documentation: replace-route reference</title>
   </biblioset>
  </biblioentry>

  <biblioentry>
   <biblioset relation="article">
    <title><ulink url="https://docs.aws.amazon.com/cli/latest/reference/ec2/delete-route.html">delete-route</ulink></title>
   </biblioset>
   <biblioset relation="book">
    <title>AWS Documentation: delete-route reference</title>
   </biblioset>
  </biblioentry>

  <biblioentry>
   <biblioset relation="article">
    <title><ulink url="https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-network-interface-attribute.html">modify-network-interface-attribute</ulink></title>
   </biblioset>
   <biblioset relation="book">
    <title>AWS Documentation: modify-network-interface-attribute</title>
   </biblioset>
  </biblioentry>

  </bibliography>
</sect1>