pgpool2.git / summary / log / commit / refs
commit 2fec3c85e6e5a9e49974221560fd347b80455b8a
Author: Bo Peng <pengbo@sraoss.co.jp>
Date: Wed Nov 25 15:55:55 2020 +0000
Doc: add documentation of "Pgpool-II on Kubernetes".
doc.ja/src/figures/pgpool_on_k8s.gif | Bin 0 -> 101410 bytes
doc.ja/src/figures/pgpool_on_k8s.pptx | Bin 0 -> 306210 bytes
doc.ja/src/sgml/example-Kubernetes.sgml | 332 +++++++++++++++++++++++++++++++
doc.ja/src/sgml/examples.sgml | 1 +
doc.ja/src/sgml/filelist.sgml | 1 +
doc/src/figures/pgpool_on_k8s.gif | Bin 0 -> 101410 bytes
doc/src/figures/pgpool_on_k8s.pptx | Bin 0 -> 306210 bytes
doc/src/sgml/example-Kubernetes.sgml | 335 ++++++++++++++++++++++++++++++++
doc/src/sgml/examples.sgml | 1 +
doc/src/sgml/filelist.sgml | 1 +
10 files changed, 671 insertions(+)
diff --git a/doc.ja/src/figures/pgpool_on_k8s.gif b/doc.ja/src/figures/pgpool_on_k8s.gif
new file mode 100644
index 000000000..e78f7cc12
Binary files /dev/null and b/doc.ja/src/figures/pgpool_on_k8s.gif differ
diff --git a/doc.ja/src/figures/pgpool_on_k8s.pptx b/doc.ja/src/figures/pgpool_on_k8s.pptx
new file mode 100644
index 000000000..0fea033c4
Binary files /dev/null and b/doc.ja/src/figures/pgpool_on_k8s.pptx differ
diff --git a/doc.ja/src/sgml/example-Kubernetes.sgml b/doc.ja/src/sgml/example-Kubernetes.sgml
new file mode 100644
index 000000000..6a5654978
--- /dev/null
+++ b/doc.ja/src/sgml/example-Kubernetes.sgml
@@ -0,0 +1,332 @@
+<sect1 id="example-Kubernetes">
+ <title>Kubernetesの設定例</title>
+ <para>
+ この章では、<productname>Kubernetes</productname>上で<productname>Pgpool-II</productname>を利用し、読み取りクエリの負荷分散とコネクションプーリングを実現する方法について説明します。
+ </para>
+ <sect2 id="example-Kubernetes-intro">
+ <title>はじめに</title>
+ <para>
+ <productname>PostgreSQL</productname>はステートフルなアプリケーションであり、また<productname>PostgreSQL</productname>の運用ではバックアップ、リカバリ、障害対策などの管理が必要になります。
+ <productname>Kubernetes</productname>の標準的な機能ではこれらの機能を実現できません。
+ そのために、<productname>Kubernetes</productname>を使って<productname>PostgreSQL</productname>を運用するには、
+ <productname>Kubernetes</productname>の本来の機能を拡張するためのOperatorが必要になります。
+ </para>
+ <para>
+ 代表的なPostgreSQL Operatorとしては、
+ <ulink url="https://github.com/CrunchyData/postgres-operator">Crunchy PostgreSQL Operator</ulink>や
+ <ulink url="https://github.com/zalando/postgres-operator">Zalando PostgreSQL Operator</ulink>、
+ <ulink url="https://github.com/kubedb/operator">KubeDB</ulink>があります。
+ しかし、これらのPostgreSQL Operatorには読み取りクエリの負荷分散機能はありません。
+ </para>
+ <para>
+ この章では、PostgreSQL OperatorをPgpool-IIと組み合わせて、<productname>Kubernetes</productname>上で読み取りクエリの負荷分散とコネクションプーリング機能を備えた<productname>PostgreSQL</productname>クラスタの構築方法について説明します。Pgpool-IIは、上記PostgreSQL Operatorのいずれかと組み合わせることができます。
+ </para>
+ </sect2>
+
+ <sect2 id="example-Kubernetes-architecture">
+ <title>全体構成図</title>
+ <para>
+ <figure>
+ <title>全体構成図</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="pgpool_on_k8s.gif">
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </para>
+ </sect2>
+
+ <sect2 id="example-Kubernetes-pre-setup">
+ <title>前提条件</title>
+ <para>
+ Pgpool-IIの設定の前に、以下の設定を行ってください。
+ <itemizedlist>
+ <listitem>
+ <para>
+ Kubernetesクラスタを構築し、<command>kubectl</command>をインストールしておきます。
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ KubernetesクラスタにPostgreSQL Operatorをインストールし、PostgreSQLクラスタを1つ作成しておきます。
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
+
+ <sect2 id="example-Kubernetes-deploy-pgpool">
+ <title>Pgpool-IIのデプロイ</title>
+ <para>
+ <productname>Pgpool-II</productname>のPodに<productname>Pgpool-II</productname>コンテナと
+ <ulink url="https://github.com/pgpool/pgpool2_exporter">Pgpool-II Exporter</ulink>コンテナを作成します。
+ </para>
+ <programlisting>
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: pgpool
+spec:
+ replicas: 1
+ selector:
+ matchLabels:
+ app: pgpool
+ template:
+ metadata:
+ labels:
+ app: pgpool
+ spec:
+ containers:
+ - name: pgpool
+ image: pgpool/pgpool:4.2
+ ...
+ - name: pgpool-stats
+ image: pgpool/pgpool2_exporter:1.0
+ ...
+ </programlisting>
+ <para>
+ <productname>pgpool-II</productname>のヘルスチェック、自動フェイルオーバー、Watchdogおよびオンラインリカバリ機能は<productname>Kubernetes</productname>環境では必要ありません。
+ 読み取りクエリの負荷分散とコネクションプーリング機能のみを有効ににすれば良いです。
+ </para>
+ <para>
+ Kubernetes上でpgpool を動かすために、以下の設定が必要最低限の設定です。
+ </para>
+ <programlisting>
+backend_hostname0='primary service name'
+backend_hostname1='replica service name'
+backend_port0='5432'
+backend_port1='5432'
+backend_flag0='ALWAYS_PRIMARY|DISALLOW_TO_FAILOVER'
+backend_flag1='DISALLOW_TO_FAILOVER'
+
+sr_check_period = 10
+sr_check_user='PostgreSQL user name'
+
+load_balance_mode = on
+connection_cache = on
+listen_addresses = '*'
+ </programlisting>
+ <para>
+ Pgpool-IIを構成する方法は2つあります。
+ <orderedlist>
+ <listitem>
+ <para>
+ 環境変数を利用する
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="https://kubernetes.io/docs/concepts/configuration/configmap/">ConfigMap</ulink>を利用する
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ <para>
+ プロダクション環境では、クライアント認証、または多くのパラメーターを設定する必要があります。
+ プロダクション環境の場合は、<literal>ConfigMap</literal>を使用して<literal>Pgpool-II</literal>の設定ファイル、
+ 例えば、pgpool.conf、pcp.conf、pool_passwd、pool_hba.confなどを設定することをお勧めします。
+ </para>
+ <para>
+ 次のセクションでは、環境変数と<literal>ConfigMap</literal>をそれぞれ使用して<productname>Pgpool-II</productname>
+ を設定およびデプロイする方法について説明します。
+ <productname>Pgpool-II</productname>のデプロイに使用される各種マニフェストファイルは、
+ <ulink url="https://github.com/pgpool/pgpool2_on_k8s">ここ</ulink>からダウンロードできます。
+ </para>
+
+ <sect3 id="example-Kubernetes-configure-pgpool-env">
+ <title>環境変数を使用したPgpool-IIの設定</title>
+ <para>
+ <productname>Kubernetes</productname>環境変数は、Pod内のコンテナに渡すことができます。
+ マニフェストで環境変数を定義することで、Pgpool-IIのパラメーターを設定することができます。
+ <filename>pgpool_deploy.yaml</filename>は、Deploymentマニフェストの例です。
+ <filename>pgpool_deploy.yaml</filename>をダウンロードして、このマニフェストにて必要な環境変数を指定します。
+ </para>
+ <programlisting>
+$ curl -LO https://raw.githubusercontent.com/pgpool/pgpool2_on_k8s/master/pgpool_deploy.yaml
+ </programlisting>
+ <para>
+ <literal>PGPOOL_PARAMS_</literal>で始まる環境変数は、Pgpool-IIの設定パラメーターに変換され、
+ デフォルトの設定値を上書きすることができます。
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Pgpool-IIコンテナのDockerイメージは、ストリーミングレプリケーションモードでビルドされています。
+ デフォルトでは、クエリの負荷分散、コネクションプーリング、およびストリーミングレプリケーションチェックが有効になっています。
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>2つのバックエンドノードのみ</emphasis>を指定すれば良いです。
+ <xref linkend="GUC-BACKEND-HOSTNAME">0にプライマリservice名を指定します。
+ <xref linkend="GUC-BACKEND-HOSTNAME">1にレプリカservice名を指定します。
+ 自動フェイルオーバがKubernetesによって管理されているので、両方のノードの<xref linkend="GUC-BACKEND-FLAG">に
+ DISALLOW_TO_FAILOVERフラグを指定します。
+ <xref linkend="GUC-BACKEND-FLAG">0にALWAYS_PRIMARYフラグを指定します。
+ <xref linkend="GUC-BACKEND-WEIGHT">は通常どおり設定します。
+ <xref linkend="GUC-BACKEND-DATA-DIRECTORY">を設定する必要はありません。
+ </para>
+ <para>
+ 例えば、マニフェストで定義されている環境変数は、
+ </para>
+ <programlisting>
+env:
+- name: PGPOOL_PARAMS_BACKEND_HOSTNAME0
+ value: "hippo"
+- name: PGPOOL_PARAMS_BACKEND_HOSTNAME1
+ value: "hippo-replica"
+- name: PGPOOL_PARAMS_BACKEND_FLAG0
+ value: "ALWAYS_PRIMARY|DISALLOW_TO_FAILOVER"
+- name: PGPOOL_PARAMS_BACKEND_FLAG1
+ value: "DISALLOW_TO_FAILOVER"
+ </programlisting>
+ <para>
+ 以下のように<filename>pgpool.conf</filename>の設定パラメータに変換されます。
+ </para>
+ <programlisting>
+backend_hostname0='hippo'
+backend_hostname1='hippo-replica'
+backend_flag0='ALWAYS_PRIMARY|DISALLOW_TO_FAILOVER'
+backend_flag1='DISALLOW_TO_FAILOVER'
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>
+ ストリーミングレプリケーションチェックを実行するための<productname>PostgreSQL</productname>のユーザー名とパスワードを指定します。
+ セキュリティ上の理由から、暗号化されたパスワードを指定することをお勧めします。
+ </para>
+ <programlisting>
+- name: PGPOOL_PARAMS_SR_CHECK_USER
+ value: "PostgreSQL user name"
+- name: PGPOOL_PARAMS_SR_CHECK_PASSWORD
+ value: "encrypted PostgreSQL user's password"
+ </programlisting>
+ <para>
+ または、作成済のSecretを利用し環境変数を設定することもできます。
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ ヘルスチェックは<productname>Kubernetes</productname>によって実施されているため、
+ Pgpool-IIのヘルスチェックを無効にする必要があります。
+ デフォルト値がオフになっているため、このパラメーターを設定する必要はありません。
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ デフォルトでは、Pgpool-IIコンテナの起動時に以下の環境変数が設定済です。
+ </para>
+ <programlisting>
+export PGPOOL_PARAMS_LISTEN_ADDRESSES=*
+export PGPOOL_PARAMS_SR_CHECK_USER=${POSTGRES_USER:-"postgres"}
+export PGPOOL_PARAMS_SOCKET_DIR=/var/run/postgresql
+export PGPOOL_PARAMS_PCP_SOCKET_DIR=/var/run/postgresql
+ </programlisting>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+ <sect3 id="example-Kubernetes-configure-pgpool-configmap">
+ <title>ConfigMapを使用したPgpool-IIの設定</title>
+ <para>
+ Kubernetesの<literal>ConfigMap</literal>を使用し、pgpool.conf、pcp.conf、pool_passwd、pool_hba.conf、
+ これらの設定ファイル全体を保存することができます。
+ また、ConfigMapは、ボリュームとしてはpgpool-IIのコンテナにマウントすることができます。
+ </para>
+ <para>
+ <literal>ConfigMap</literal>とDeploymentを定義するサンプルマニフェストファイルは
+ <ulink url="https://github.com/pgpool/pgpool2_on_k8s">リポジトリ</ulink>からダウンロードできます。
+ </para>
+ <programlisting>
+curl -LO https://raw.githubusercontent.com/pgpool/pgpool2_on_k8s/master/pgpool_configmap.yaml
+curl -LO https://raw.githubusercontent.com/pgpool/pgpool2_on_k8s/master/pgpool_deploy_with_mount_configmap.yaml
+ </programlisting>
+ <para>
+ サンプルのConfigMapは以下のような形式で定義されています。必要に応じて更新してください。
+ </para>
+ <programlisting>
+apiVersion: v1
+kind: ConfigMap
+metadata:
+ name: pgpool-config
+ labels:
+ app: pgpool-config
+data:
+ pgpool.conf: |-
+ listen_addresses = '*'
+ port = 9999
+ socket_dir = '/var/run/postgresql'
+ pcp_listen_addresses = '*'
+ pcp_port = 9898
+ pcp_socket_dir = '/var/run/postgresql'
+ backend_hostname0 = 'hippo'
+ backend_port0 = 5432
+ backend_weight0 = 1
+ backend_flag0 = 'ALWAYS_PRIMARY|DISALLOW_TO_FAILOVER'
+ backend_hostname1 = 'hippo-replica'
+ backend_port1 = 5432
+ backend_weight1 = 1
+ backend_flag1 = 'DISALLOW_TO_FAILOVER'
+ sr_check_user = 'postgres'
+ sr_check_period = 10
+ enable_pool_hba = on
+ master_slave_mode = on
+ num_init_children = 32
+ max_pool = 4
+ child_life_time = 300
+ child_max_connections = 0
+ connection_life_time = 0
+ client_idle_limit = 0
+ connection_cache = on
+ load_balance_mode = on
+ pcp.conf: |-
+ postgres:e8a48653851e28c69d0506508fb27fc5
+ pool_passwd: |-
+ postgres:md53175bce1d3201d16594cebf9d7eb3f9d
+ pool_hba.conf: |-
+ local all all trust
+ host all all 127.0.0.1/32 trust
+ host all all ::1/128 trust
+ host all all 0.0.0.0/0 md5
+ </programlisting>
+ <para>
+ まず、<productname>Pgpool-II</productname>のPodをデプロイする前に<literal>ConfigMap</literal>を作成する必要があります。
+ </para>
+ <programlisting>
+kubectl apply -f pgpool_configmap.yaml
+ </programlisting>
+ <para>
+ <literal>ConfigMap</literal>を作成したら、<productname>Pgpool-II</productname>をデプロイするマニフェストで
+ <literal>ConfigMap</literal>をボリュームとしてPgpool-IIのPodにマウントするように設定します。
+ </para>
+ <programlisting>
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: pgpool
+ ...
+ volumeMounts:
+ - name: pgpool-config
+ mountPath: /usr/local/pgpool-II/etc
+ ...
+ volumes:
+ - name: pgpool-config
+ configMap:
+ name: pgpool-config
+ </programlisting>
+ <para>
+ <filename>pgpool_deploy_with_mount_configmap.yaml</filename>は、作成された<literal>ConfigMap</literal>を
+ <productname>Pgpool-II</productname>のPodにマウントするサンプルマニフェストです。
+ 基本的にはそのまま利用できます。
+ </para>
+ <programlisting>
+kubectl apply -f pgpool_deploy_with_mount_configmap.yaml
+ </programlisting>
+ <para>
+ <productname>Pgpool-II</productname>をデプロイした後、<command>kubectl get pod</command>や
+ <command>kubectl get svc</command>コマンドを使用して<productname>Pgpool-II</productname>のPodとserviceを確認できます。
+ </para>
+ </sect3>
+ </sect2>
+</sect1>
diff --git a/doc.ja/src/sgml/examples.sgml b/doc.ja/src/sgml/examples.sgml
index e9bb01217..645dc7a23 100644
--- a/doc.ja/src/sgml/examples.sgml
+++ b/doc.ja/src/sgml/examples.sgml
@@ -25,5 +25,6 @@
&example-cluster;
&example-AWS;
&example-Aurora;
+ &example-Kubernetes;
</chapter>
</part>
diff --git a/doc.ja/src/sgml/filelist.sgml b/doc.ja/src/sgml/filelist.sgml
index c747cbbbc..da30a3e8a 100644
--- a/doc.ja/src/sgml/filelist.sgml
+++ b/doc.ja/src/sgml/filelist.sgml
@@ -45,6 +45,7 @@
<!ENTITY example-cluster SYSTEM "example-cluster.sgml">
<!ENTITY example-AWS SYSTEM "example-AWS.sgml">
<!ENTITY example-Aurora SYSTEM "example-Aurora.sgml">
+<!ENTITY example-Kubernetes SYSTEM "example-Kubernetes.sgml">
<!-- reference pages -->
<!ENTITY % allfiles SYSTEM "ref/allfiles.sgml">
diff --git a/doc/src/figures/pgpool_on_k8s.gif b/doc/src/figures/pgpool_on_k8s.gif
new file mode 100644
index 000000000..e78f7cc12
Binary files /dev/null and b/doc/src/figures/pgpool_on_k8s.gif differ
diff --git a/doc/src/figures/pgpool_on_k8s.pptx b/doc/src/figures/pgpool_on_k8s.pptx
new file mode 100644
index 000000000..0fea033c4
Binary files /dev/null and b/doc/src/figures/pgpool_on_k8s.pptx differ
diff --git a/doc/src/sgml/example-Kubernetes.sgml b/doc/src/sgml/example-Kubernetes.sgml
new file mode 100644
index 000000000..1274d796d
--- /dev/null
+++ b/doc/src/sgml/example-Kubernetes.sgml
@@ -0,0 +1,335 @@
+<sect1 id="example-Kubernetes">
+ <title><productname>Pgpool-II</productname> on Kubernetes</title>
+ <para>
+ This section explains how to run <productname>Pgpool-II</productname> to achieve
+ read query load balancing and connection pooling on Kubernetes.
+ </para>
+ <sect2 id="example-Kubernetes-intro">
+ <title>Introduction</title>
+ <para>
+ Because <productname>PostgreSQL</productname> is a stateful application and managing
+ <productname>PostgreSQL</productname> has very specific requirements (e.g. backup,
+ recovery, automatic failover, etc), the built-in functionality of <productname>Kubernetes</productname>
+ can't handle these tasks. Therefore, an Operator that extends the functionality of the Kubernetes to create
+ and manage PostgreSQL is required.
+ </para>
+ <para>
+ There are several PostgreSQL operators, such as
+ <ulink url="https://github.com/CrunchyData/postgres-operator">Crunchy PostgreSQL Operator</ulink>,
+ <ulink url="https://github.com/zalando/postgres-operator">Zalando PostgreSQL Operator</ulink> and
+ <ulink url="https://github.com/kubedb/operator">KubeDB</ulink>.
+ However, these operators don't provide query load balancing functionality.
+ </para>
+ <para>
+ This section explains how to combine PostgreSQL Operator with Pgpool-II to deploy a PostgreSQL cluster
+ with query load balancing and connection pooling capability on Kubernetes. Pgpool-II can be combined with
+ any of the PostgreSQL operators mentioned above.
+ </para>
+ </sect2>
+
+ <sect2 id="example-Kubernetes-architecture">
+ <title>Architecture</title>
+ <para>
+ <figure>
+ <title>Architecture</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="pgpool_on_k8s.gif">
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </para>
+ </sect2>
+
+ <sect2 id="example-Kubernetes-pre-setup">
+ <title>Prerequisites</title>
+ <para>
+ Before you start the configuration process, please check the following prerequisites.
+ <itemizedlist>
+ <listitem>
+ <para>
+ Make sure you have a <productname>Kubernetes</productname> cluster, and <command>kubectl</command> is installed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ PostgreSQL Operator and a PostgreSQL cluster are installed.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
+
+ <sect2 id="example-Kubernetes-deploy-pgpool">
+ <title>Deploy Pgpool-II</title>
+ <para>
+ Deploy Pgpool-II pod that contains a Pgpool-II container and a
+ <ulink url="https://github.com/pgpool/pgpool2_exporter">Pgpool-II Exporter</ulink> container.
+ </para>
+ <programlisting>
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: pgpool
+spec:
+ replicas: 1
+ selector:
+ matchLabels:
+ app: pgpool
+ template:
+ metadata:
+ labels:
+ app: pgpool
+ spec:
+ containers:
+ - name: pgpool
+ image: pgpool/pgpool:4.2
+ ...
+ - name: pgpool-stats
+ image: pgpool/pgpool2_exporter:1.0
+ ...
+ </programlisting>
+ <para>
+ <productname>Pgpool-II</productname>'s health check, automatic failover, Watchdog and online recovery features
+ aren't required on <productname>Kubernetes</productname>. You need to only enable load balancing and connection
+ pooling.
+ </para>
+ <para>
+ The Pgpool-II pod should work with the minimal configuration below:
+ </para>
+ <programlisting>
+backend_hostname0='primary service name'
+backend_hostname1='replica service name'
+backend_port0='5432'
+backend_port1='5432'
+backend_flag0='ALWAYS_PRIMARY|DISALLOW_TO_FAILOVER'
+backend_flag1='DISALLOW_TO_FAILOVER'
+
+sr_check_period = 10
+sr_check_user='PostgreSQL user name'
+
+load_balance_mode = on
+connection_cache = on
+listen_addresses = '*'
+ </programlisting>
+ <para>
+ There are two ways you can configure Pgpool-II.
+ <orderedlist>
+ <listitem>
+ <para>
+ Using environment variables
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Using a <ulink url="https://kubernetes.io/docs/concepts/configuration/configmap/">ConfigMap</ulink>
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ <para>
+ You may need to configure client authentication and more parameters in a production environment.
+ In a production environment, we recommend using a ConfigMap to configure Pgpool-II's
+ config files, i.e. pgpool.conf, pcp.conf, pool_passwd and pool_hba.conf.
+ </para>
+ <para>
+ The following sections explain how to configure and deploy Pgpool-II pod using environment
+ variables and ConfigMap respectively. You can download the various manifest files used for
+ deploying Pgpool-II from <ulink url="https://github.com/pgpool/pgpool2_on_k8s">here</ulink>.
+ </para>
+
+ <sect3 id="example-Kubernetes-configure-pgpool-env">
+ <title>Configure Pgpool-II using environment variables</title>
+ <para>
+ Kubernetes environment variables can be passed to a container in a pod.
+ You can define environment variables in the deployment manifest to configure Pgpool-II's parameters.
+ <filename>pgpool_deploy.yaml</filename> is an example of a Deployment manifest.
+ You can download <filename>pgpool_deploy.yaml</filename> and specify environment variables in this manifest file.
+ </para>
+ <programlisting>
+$ curl -LO https://raw.githubusercontent.com/pgpool/pgpool2_on_k8s/master/pgpool_deploy.yaml
+ </programlisting>
+ <para>
+ Environment variables starting with <literal>PGPOOL_PARAMS_</literal> can be converted to Pgpool-II's configuration
+ parameters and these values can override the default configurations.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The Pgpool-II container Docker images is build with streaming replication mode.
+ By default, load balancing, connection pooling and streaming replication check is enabled.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Specify <emphasis>only two backend nodes</emphasis>.
+ Specify the Primary Service name to <xref linkend="GUC-BACKEND-HOSTNAME">0.
+ Specify the Replica Service name to <xref linkend="GUC-BACKEND-HOSTNAME">1.
+ Because failover is managed by <productname>Kubernetes</productname>,
+ specify <literal>DISALLOW_TO_FAILOVER</literal> flag to <xref linkend="GUC-BACKEND-FLAG">
+ for both of the two nodes and <literal>ALWAYS_PRIMARY</literal> flag to <xref linkend="GUC-BACKEND-FLAG">0.
+ Configure appropriate <xref linkend="GUC-BACKEND-WEIGHT"> as usual.
+ You don't need to specify <xref linkend="GUC-BACKEND-DATA-DIRECTORY">.
+ </para>
+ <para>
+ For example, the following environment variables defined in manifest,
+ </para>
+ <programlisting>
+env:
+- name: PGPOOL_PARAMS_BACKEND_HOSTNAME0
+ value: "hippo"
+- name: PGPOOL_PARAMS_BACKEND_HOSTNAME1
+ value: "hippo-replica"
+- name: PGPOOL_PARAMS_BACKEND_FLAG0
+ value: "ALWAYS_PRIMARY|DISALLOW_TO_FAILOVER"
+- name: PGPOOL_PARAMS_BACKEND_FLAG1
+ value: "DISALLOW_TO_FAILOVER"
+ </programlisting>
+ <para>
+ will be convert to the following configuration parameters in pgpool.conf.
+ </para>
+ <programlisting>
+backend_hostname0='hippo'
+backend_hostname1='hippo-replica'
+backend_flag0='ALWAYS_PRIMARY|DISALLOW_TO_FAILOVER'
+backend_flag1='DISALLOW_TO_FAILOVER'
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>
+ Specify a PostgreSQL user name and password to perform streaming replication check.
+ For the security reasons, we recommend that you specify a encrypted password.
+ </para>
+ <programlisting>
+- name: PGPOOL_PARAMS_SR_CHECK_USER
+ value: "PostgreSQL user name"
+- name: PGPOOL_PARAMS_SR_CHECK_PASSWORD
+ value: "encrypted PostgreSQL user's password"
+ </programlisting>
+ <para>
+ Alternatively, you can create a secret and use this secret as environment variables.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Since health check is performed by <productname>Kubernetes</productname>, Pgpool-II's health check should be disabled.
+ Because the default value is off, we don't need to set this parameter.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ By default, the following environment variables will be set when Pgpool-II container is started.
+ </para>
+ <programlisting>
+export PGPOOL_PARAMS_LISTEN_ADDRESSES=*
+export PGPOOL_PARAMS_SR_CHECK_USER=${POSTGRES_USER:-"postgres"}
+export PGPOOL_PARAMS_SOCKET_DIR=/var/run/postgresql
+export PGPOOL_PARAMS_PCP_SOCKET_DIR=/var/run/postgresql
+ </programlisting>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+ <sect3 id="example-Kubernetes-configure-pgpool-configmap">
+ <title>Configure Pgpool-II using ConfigMap</title>
+ <para>
+ Alternatively, you can use a Kubernetes <literal>ConfigMap</literal> to store entire configuration files,
+ i.e. pgpool.conf, pcp.conf, pool_passwd and pool_hba.conf.
+ The <literal>ConfigMap</literal> can be mounted to Pgpool-II's container as a volume.
+ </para>
+ <para>
+ You can download the example manifest files that define the <literal>ConfigMap</literal> and <literal>Deployment</literal>
+ from <ulink url="https://github.com/pgpool/pgpool2_on_k8s">repository</ulink>.
+ </para>
+ <programlisting>
+curl -LO https://raw.githubusercontent.com/pgpool/pgpool2_on_k8s/master/pgpool_configmap.yaml
+curl -LO https://raw.githubusercontent.com/pgpool/pgpool2_on_k8s/master/pgpool_deploy_with_mount_configmap.yaml
+ </programlisting>
+ <para>
+ The manifest that defines the <literal>ConfigMap</literal> is in the following format. You can update it based
+ on your configuration preferences.
+ </para>
+ <programlisting>
+apiVersion: v1
+kind: ConfigMap
+metadata:
+ name: pgpool-config
+ labels:
+ app: pgpool-config
+data:
+ pgpool.conf: |-
+ listen_addresses = '*'
+ port = 9999
+ socket_dir = '/var/run/postgresql'
+ pcp_listen_addresses = '*'
+ pcp_port = 9898
+ pcp_socket_dir = '/var/run/postgresql'
+ backend_hostname0 = 'hippo'
+ backend_port0 = 5432
+ backend_weight0 = 1
+ backend_flag0 = 'ALWAYS_PRIMARY|DISALLOW_TO_FAILOVER'
+ backend_hostname1 = 'hippo-replica'
+ backend_port1 = 5432
+ backend_weight1 = 1
+ backend_flag1 = 'DISALLOW_TO_FAILOVER'
+ sr_check_user = 'postgres'
+ sr_check_period = 10
+ enable_pool_hba = on
+ master_slave_mode = on
+ num_init_children = 32
+ max_pool = 4
+ child_life_time = 300
+ child_max_connections = 0
+ connection_life_time = 0
+ client_idle_limit = 0
+ connection_cache = on
+ load_balance_mode = on
+ pcp.conf: |-
+ postgres:e8a48653851e28c69d0506508fb27fc5
+ pool_passwd: |-
+ postgres:md53175bce1d3201d16594cebf9d7eb3f9d
+ pool_hba.conf: |-
+ local all all trust
+ host all all 127.0.0.1/32 trust
+ host all all ::1/128 trust
+ host all all 0.0.0.0/0 md5
+ </programlisting>
+ <para>
+ First, you need to create the <literal>ConfigMap</literal> before referencing it to <productname>Pgpool-II</productname> pod.
+ </para>
+ <programlisting>
+kubectl apply -f pgpool_configmap.yaml
+ </programlisting>
+ <para>
+ Once you have created the <literal>ConfigMap</literal>, you can deploy <productname>Pgpool-II</productname> pod and
+ mount the <literal>ConfigMap</literal> to Pgpool-II pod as a volume.
+ </para>
+ <programlisting>
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: pgpool
+ ...
+ volumeMounts:
+ - name: pgpool-config
+ mountPath: /usr/local/pgpool-II/etc
+ ...
+ volumes:
+ - name: pgpool-config
+ configMap:
+ name: pgpool-config
+ </programlisting>
+ <para>
+ <filename>pgpool_deploy_with_mount_configmap.yaml</filename> is an example of a Deployment manifest that mounts the
+ created <literal>ConfigMap</literal> to the <productname>Pgpool-II</productname> pod.
+ </para>
+ <programlisting>
+kubectl apply -f pgpool_deploy_with_mount_configmap.yaml
+ </programlisting>
+ <para>
+ After deploying Pgpool-II, you can see the Pgpool-II pod and services using <command>kubectl get pod</command>
+ and <command>kubectl get svc</command> command.
+ </para>
+ </sect3>
+ </sect2>
+</sect1>
diff --git a/doc/src/sgml/examples.sgml b/doc/src/sgml/examples.sgml
index db598054e..f7f8914ed 100644
--- a/doc/src/sgml/examples.sgml
+++ b/doc/src/sgml/examples.sgml
@@ -15,5 +15,6 @@
&example-cluster;
&example-AWS;
&example-Aurora;
+ &example-Kubernetes;
</chapter>
</part>
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 0a148d701..d6f77ed74 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -45,6 +45,7 @@
<!ENTITY example-cluster SYSTEM "example-cluster.sgml">
<!ENTITY example-AWS SYSTEM "example-AWS.sgml">
<!ENTITY example-Aurora SYSTEM "example-Aurora.sgml">
+<!ENTITY example-Kubernetes SYSTEM "example-Kubernetes.sgml">
<!-- reference pages -->
<!ENTITY % allfiles SYSTEM "ref/allfiles.sgml">
[parent: dfe27f518522]