pgpool2.git / summary / log / commit / refs
commit 9e2c005f66c469a8582fc3258d94e595c536d2e9
Author: Bo Peng <pengbo@sraoss.co.jp>
Date: Mon Aug 02 16:58:31 2021 +0000
Doc: Update configuration example "Pgpool-II on Kubernetes".
doc.ja/src/sgml/example-Kubernetes.sgml | 551 +++++++++++++++++++++-----------
doc/src/sgml/example-Kubernetes.sgml | 534 ++++++++++++++++++++-----------
2 files changed, 716 insertions(+), 369 deletions(-)
diff --git a/doc.ja/src/sgml/example-Kubernetes.sgml b/doc.ja/src/sgml/example-Kubernetes.sgml
index 47204cd33..cd4340fe5 100644
--- a/doc.ja/src/sgml/example-Kubernetes.sgml
+++ b/doc.ja/src/sgml/example-Kubernetes.sgml
@@ -1,25 +1,30 @@
<sect1 id="example-Kubernetes">
<title>Kubernetesの設定例</title>
<para>
- この章では、<productname>Kubernetes</productname>上で<productname>Pgpool-II</productname>を利用し、読み取りクエリの負荷分散とコネクションプーリングを実現する方法について説明します。
+ この章では、<productname>Kubernetes</productname>上で<productname>Pgpool-II</productname>をデプロイし、
+ 読み取りクエリの負荷分散とコネクションプーリングを実現する方法について説明します。
</para>
<sect2 id="example-Kubernetes-intro">
<title>はじめに</title>
<para>
- <productname>PostgreSQL</productname>はステートフルなアプリケーションであり、また<productname>PostgreSQL</productname>の運用ではバックアップ、リカバリ、障害対策などの管理が必要になります。
+ <productname>PostgreSQL</productname>はステートフルなアプリケーションであり、
+ また<productname>PostgreSQL</productname>の運用ではバックアップ、リカバリ、
+ 障害対策などの管理が必要になります。
<productname>Kubernetes</productname>の標準的な機能ではこれらの機能を実現できません。
そのために、<productname>Kubernetes</productname>を使って<productname>PostgreSQL</productname>を運用するには、
- <productname>Kubernetes</productname>の本来の機能を拡張するためのOperatorが必要になります。
+ <productname>Kubernetes</productname>の本来の機能を拡張するための<literal>Operator</literal>が必要になります。
</para>
<para>
- 代表的なPostgreSQL Operatorとしては、
+ 代表的な<literal>PostgreSQL Operator</literal>としては、
<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のいずれかと組み合わせることができます。
+ この章では、PostgreSQL OperatorをPgpool-IIと組み合わせて、
+ <productname>Kubernetes</productname>上で読み取りクエリの負荷分散とコネクションプーリング機能を備えた<productname>PostgreSQL</productname>クラスタの構築方法について説明します。
+ <productname>Pgpool-II</productname>は、上記PostgreSQL Operatorのいずれかと組み合わせることができます。
</para>
</sect2>
@@ -40,7 +45,7 @@
<sect2 id="example-Kubernetes-pre-setup">
<title>前提条件</title>
<para>
- Pgpool-IIの設定の前に、以下の設定を行ってください。
+ Pgpool-IIをデプロイする前に、以下の設定を行ってください。
<itemizedlist>
<listitem>
<para>
@@ -59,49 +64,26 @@
<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>環境では必要ありません。
+ <productname>Kubernetes</productname>を利用する場合は、PostgreSQLおよびPgpool-IIの状態はKubernetesによって管理されますので、
+ <productname>Pgpool-II</productname>のヘルスチェック、自動フェイルオーバ、
+ Watchdogおよびオンラインリカバリ機能は<productname>Kubernetes</productname>環境では必要ありません。
読み取りクエリの負荷分散とコネクションプーリング機能のみを有効にすれば良いです。
</para>
<para>
- Kubernetes上でpgpool を動かすために、以下の設定が必要最低限の設定です。
+ Kubernetes上で<productname>Pgpool-II</productname>を動かすために、以下の設定が必要最低限の設定です。
</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'
+backend_hostname0 = '<プライマリService名>'
+backend_hostname1 = '<レプリカService名>'
+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'
+failover_on_backend_error = off
+
+sr_check_period = 10 (ストリーミングレプリケーションチェック機能を利用する場合のみ)
+sr_check_user='username of PostgreSQL user' (ストリーミングレプリケーションチェック機能を利用する場合のみ)
load_balance_mode = on
connection_cache = on
@@ -112,7 +94,7 @@ listen_addresses = '*'
<orderedlist>
<listitem>
<para>
- 環境変数を利用する
+ <ulink url="https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/">環境変数</ulink>を利用する
</para>
</listitem>
<listitem>
@@ -124,12 +106,15 @@ listen_addresses = '*'
</para>
<para>
プロダクション環境では、クライアント認証、または多くのパラメーターを設定する必要があります。
- プロダクション環境の場合は、<literal>ConfigMap</literal>を使用して<literal>Pgpool-II</literal>の設定ファイル、
- 例えば、pgpool.conf、pcp.conf、pool_passwd、pool_hba.confなどを設定することをお勧めします。
+ 設定パラメータごとにそれぞれの環境変数を設定すると、マニフェストが冗長な記述になってしまうデメリットがあります。
+ プロダクション環境の場合は、<emphasis>ConfigMap</emphasis>を使用したPgpool-IIのインストール方法（<xref linkend="example-Kubernetes-configure-pgpool-configmap">）をお勧めします。
</para>
<para>
- 次のセクションでは、環境変数と<literal>ConfigMap</literal>をそれぞれ使用して<productname>Pgpool-II</productname>
- を設定およびデプロイする方法について説明します。
+ ここからは、環境変数と<literal>ConfigMap</literal>をそれぞれ使用して<productname>Pgpool-II</productname>
+ を設定およびデプロイする方法を説明します。
+ この設定例では、<emphasis>必要最低限</emphasis>のパラメータを設定しています。
+ <productname>Pgpool-II</productname>の各機能の詳細設定については、
+ <xref linkend="example-Kubernetes-advanced-configuration">をご参照ください。
<productname>Pgpool-II</productname>のデプロイに使用される各種マニフェストファイルは、
<ulink url="https://github.com/pgpool/pgpool2_on_k8s">ここ</ulink>からダウンロードできます。
</para>
@@ -137,113 +122,97 @@ listen_addresses = '*'
<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>をダウンロードして、このマニフェストにて必要な環境変数を指定します。
+ <productname>Kubernetes</productname>の環境変数は、Pod内のコンテナに渡すことができるので、
+ Pgpool-IIのデプロイマニフェストで環境変数を定義することで、
+ <productname>Pgpool-II</productname>のパラメータを設定することができます。
+ <filename>pgpool-deploy-minimal.yaml</filename>は<productname>Pgpool-II</productname>
+ を<productname>Kubernetes</productname>上で動かすための最小限の環境変数を定義している
+ サンプルYAMLファイルです。このファイルをダウンロードし、<productname>PostgreSQL</productname>
+ クラスタの情報に合わせて各環境変数の<literal>value</literal>を設定します。
</para>
<programlisting>
-$ curl -LO https://raw.githubusercontent.com/pgpool/pgpool2_on_k8s/master/pgpool_deploy.yaml
+$ curl -LO https://raw.githubusercontent.com/pgpool/pgpool2_on_k8s/master/pgpool-deploy-minimal.yaml
</programlisting>
<para>
- <literal>PGPOOL_PARAMS_</literal>で始まる環境変数は、Pgpool-IIの設定パラメーターに変換され、
+ <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>
+ <para>
+ Kubernetes環境では、<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-DATA-DIRECTORY">を設定する必要はありません。
+ </para>
+ <para>
+ 例えば、マニフェストで定義されている以下の環境変数は、
+ </para>
+ <programlisting>
env:
- name: PGPOOL_PARAMS_BACKEND_HOSTNAME0
- value: "hippo"
+ value: "mypostgres"
- name: PGPOOL_PARAMS_BACKEND_HOSTNAME1
- value: "hippo-replica"
+ value: "mypostgres-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>
+ </programlisting>
+ <para>
+ これらの設定パラメータに変換され、<filename>pgpool.conf</filename>に追記されます。
+ </para>
+ <programlisting>
+backend_hostname0 = 'mypostgres'
+backend_hostname1 = 'mypostgres-replica'
+backend_flag0 = 'ALWAYS_PRIMARY|DISALLOW_TO_FAILOVER'
+backend_flag1 = 'DISALLOW_TO_FAILOVER'
+ </programlisting>
+ <para>
+ クライアント認証を行うために、PostgreSQLのユーザ名とパスワードを表す環境変数を設定します。
+ 詳細については<xref linkend="pool-passwd-configuration">をご参照ください。
+ </para>
+ <programlisting>
+env:
+- name: <任意の文字列>_USERNAME
+ valueFrom:
+ secretKeyRef:
+ ...
+- name: <任意の文字列>_PASSWORD
+ valueFrom:
+ secretKeyRef:
+ ...
+ </programlisting>
+ <para>
+ 上記設定完了後、<productname>Pgpool-II</productname>をデプロイします。
+ </para>
+ <programlisting>
+kubectl apply -f pgpool-deploy-minimal.yaml
+ </programlisting>
</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のコンテナにマウントすることができます。
+ Kubernetesの<literal>ConfigMap</literal>を使用し、
+ <filename>pgpool.conf</filename>や<filename>pool_hba.conf</filename>ファイル全体を保存することができます。
+ また、<literal>ConfigMap</literal>は、ボリュームとしては<productname>Pgpool-II</productname>のコンテナにマウントすることができます。
</para>
<para>
- <literal>ConfigMap</literal>とDeploymentを定義するサンプルマニフェストファイルは
- <ulink url="https://github.com/pgpool/pgpool2_on_k8s">リポジトリ</ulink>からダウンロードできます。
+ <literal>ConfigMap</literal>とPgpool-IIをデプロイするためのサンプルYAMLファイルは
+ <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
+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.yaml
</programlisting>
<para>
- サンプルのConfigMapは以下のような形式で定義されています。必要に応じて更新してください。
+ サンプルのConfigMapは以下のような形式で定義されています。必要に応じてパラメータの設定値を更新してください。
+ <productname>Pgpool-II</productname>はクライアント認証に
+ <filename>pool_hba.conf</filename>を使用するために、
+ <xref linkend="GUC-ENABLE-POOL-HBA">を<varname>on</varname>にする必要があります。
+ デフォルトでは、offとなります。
</para>
<programlisting>
apiVersion: v1
@@ -251,82 +220,294 @@ kind: ConfigMap
metadata:
name: pgpool-config
labels:
- app: pgpool-config
+ name: pgpool-config
data:
pgpool.conf: |-
listen_addresses = '*'
port = 9999
- socket_dir = '/var/run/postgresql'
+ socket_dir = '/var/run/pgpool'
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
+ pcp_socket_dir = '/var/run/pgpool'
+ backend_hostname0 = 'mypostgres'
+...
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
+ hostssl all all 0.0.0.0/0 md5
</programlisting>
<para>
- まず、<productname>Pgpool-II</productname>のPodをデプロイする前に<literal>ConfigMap</literal>を作成する必要があります。
+ クライアント認証を行うために、PostgreSQLの各ユーザのユーザ名とパスワードを表す環境変数を設定します。
+ PostgreSQLユーザのユーザ名とパスワードを表す環境変数のフォーマットや設定方法については
+ <xref linkend="pool-passwd-configuration">をご参照ください。
</para>
<programlisting>
-kubectl apply -f pgpool_configmap.yaml
+env:
+- name: <任意の文字列>_USERNAME
+ valueFrom:
+ secretKeyRef:
+ ...
+- name: <任意の文字列>_PASSWORD
+ valueFrom:
+ secretKeyRef:
+ ...
</programlisting>
<para>
- <literal>ConfigMap</literal>を作成したら、<productname>Pgpool-II</productname>をデプロイするマニフェストで
- <literal>ConfigMap</literal>をボリュームとしてPgpool-IIのPodにマウントするように設定します。
+ 設定後、Pgpool-IIをデプロイします。
</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
+kubectl apply -f pgpool-configmap.yaml
+kubectl apply -f pgpool-deploy.yaml
</programlisting>
<para>
- <filename>pgpool_deploy_with_mount_configmap.yaml</filename>は、作成された<literal>ConfigMap</literal>を
- <productname>Pgpool-II</productname>のPodにマウントするサンプルマニフェストです。
- 基本的にはそのまま利用できます。
+ <productname>Pgpool-II</productname>をデプロイした後、<command>kubectl get pod</command>や
+ <command>kubectl get svc</command>コマンドを使用して<productname>Pgpool-II</productname>のPodとServiceを確認できます。
+ </para>
+ </sect3>
+ </sect2>
+
+ <sect2 id="example-Kubernetes-advanced-configuration">
+ <title>Pgpool-IIの詳細設定</title>
+ <sect3 id="backend-configuration">
+ <title>バックエンド接続</title>
+ <para>
+ Kubernetes環境では、<emphasis>2つのバックエンドノードのみ</emphasis>を指定すれば良いです。
+ KubernetesではServiceを経由してアプリケーションに接続するのが一般的です。
+ そのため、<xref linkend="GUC-BACKEND-HOSTNAME">0にプライマリService名、
+ <xref linkend="GUC-BACKEND-HOSTNAME">1にレプリカService名を指定します。
</para>
<programlisting>
-kubectl apply -f pgpool_deploy_with_mount_configmap.yaml
+backend_hostname0 = '<プライマリService名>'
+backend_hostname1 = '<レプリカService名>'
+backend_port0 = '5432'
+backend_port1 = '5432'
</programlisting>
- <para>
- <productname>Pgpool-II</productname>をデプロイした後、<command>kubectl get pod</command>や
- <command>kubectl get svc</command>コマンドを使用して<productname>Pgpool-II</productname>のPodとserviceを確認できます。
- </para>
</sect3>
+
+ <sect3 id="disable-failover-configuration">
+ <title>PostgreSQLの自動フェイルオーバ</title>
+ <para>
+ Pgpool-IIには定期的にPostgreSQLを状態をチェックし、
+ 障害を検知するとフェイルオーバさせる機能はありますが、Kubernetesでは、
+ PostgreSQLの状態はKubernetesによって管理されるので、
+ Pgpoo-IIの自動フェイルオーバ機能を無効にします。
+ </para>
+ <para>
+ また、<productname>PostgreSQL</productname> Podが再作成されたり、
+ <productname>Kubernetes</productname>によってフェイルオーバしても、
+ プライマリService名とレプリカService名が変更されないので、
+ <productname>PostgreSQL</productname>ノード0をプライマリとして固定するために、
+ <varname>backend_flag0</varname>に<varname>ALWAYS_PRIMARY</varname>を指定します。
+ </para>
+ <programlisting>
+backend_flag0 ='ALWAYS_PRIMARY|DISALLOW_TO_FAILOVER'
+backend_flag1 ='DISALLOW_TO_FAILOVER'
+failover_on_backend_error = off
+ </programlisting>
+ </sect3>
+
+ <sect3 id="pool-passwd-configuration">
+ <title>パスワードファイルの生成</title>
+ <para>
+ <productname>Pgpool-II</productname>では、パスワードファイル<xref linkend="GUC-POOL-PASSWD">を用いて、
+ 認証を行います。
+ </para>
+ <para>
+ <productname>Pgpool-II</productname> Pod起動時に、自動的に<xref linkend="PG-MD5">コマンドを実行し、
+ <varname><任意の文字列>_USERNAME</varname>や<varname><任意の文字列>_PASSWORD</varname>
+ フォーマットで定義した環境変数を元に、
+ パスワードファイル<filename>pool_passwd</filename>を生成しています。
+ </para>
+ <para>
+ <productname>PostgreSQL</productname>のユーザ名とパスワードを表す環境変数のフォーマットは以下の通りです。
+ 同一ユーザのユーザ名とパスワードの<varname><任意の文字列></varname>部分は一致する必要があります。
+ </para>
+ <programlisting>
+ユーザ名 : <任意の文字列>_USERNAME
+パスワード : <任意の文字列>_PASSWORD
+ </programlisting>
+ <para>
+ セキュリティ上の理由で、パスワードは平文で記述せず、Secretを利用した方法をお勧めします。
+ ほとんどのPostgreSQL Operatorでは、<productname>PostgreSQL</productname>クラスタを作成するときに、
+ <productname>PostgreSQL</productname>ユーザの<varname>username</varname>および
+ <varname>password</varname>を保存しているいくつかのSecretが自動的に作成されます。
+ <command>kubectl get secret</command>コマンドを実行し、既存のSecretを確認します。
+ 例えば、<varname>mypostgres-postgres-secret</varname>に<literal>postgres</literal>
+ ユーザの<varname>username</varname>と<varname>password</varname>を保存しています。
+ 環境変数の設定方法は以下の通りです。
+ </para>
+ <programlisting>
+env:
+- name: POSTGRES_USERNAME
+ valueFrom:
+ secretKeyRef:
+ name: mypostgres-postgres-secret
+ key: username
+- name: POSTGRES_PASSWORD
+ valueFrom:
+ secretKeyRef:
+ name: mypostgres-postgres-secret
+ key: password
+ </programlisting>
+ <para>
+ <productname>Pgpool-II</productname> Podが起動すると、
+ <filename>pool_passwd</filename>および<filename>pcp.conf</filename>が自動的に
+ <filename>/opt/pgpool-II/etc</filename>配下に生成されます。
+ </para>
+ <programlisting>
+$ kubectl exec <pgpool pod> -it -- cat /opt/pgpool-II/etc/pool_passwd
+postgres:md53175bce1d3201d16594cebf9d7eb3f9d
+
+$ kubectl exec <pgpool pod> -it -- cat /opt/pgpool-II/etc/pcp.conf
+postgres:e8a48653851e28c69d0506508fb27fc5
+ </programlisting>
+ </sect3>
+
+ <sect3 id="sr-check-configuration">
+ <title>ストリーミングレプリケーションチェック</title>
+ <para>
+ <productname>Pgpool-II</productname>が定期的に各<productname>PostgreSQL</productname>に接続し、
+ レプリケーション遅延をチェックすることができます。
+ この機能を利用するには、<xref linkend="GUC-SR-CHECK-USER">と<xref linkend="GUC-SR-CHECK-PASSWORD">
+ に<productname>PostgreSQL</productname>ユーザのユーザ名とそのパスワードを設定する必要があります。
+ <productname>Pgpool-II</productname>では、<varname>sr_check_password</varname>が空文字の場合、
+ pool_passwdファイルからsr_check_userに指定したユーザのパスワードを取得します。
+ </para>
+ <para>
+ ここでは、sr_check_passwordを設定せず、pod起動時に自動的に生成されるpool_passwdから取得する方法を説明します。
+ 例えば、postgresユーザを利用し、
+ 10秒間隔でストリーミングレプリケーションチェックを行う場合、
+ 以下のように設定します。
+ </para>
+ <programlisting>
+sr_check_period = 10
+sr_check_user = 'postgres'
+ </programlisting>
+ <para>
+ <productname>Pgpool-II</productname>をデプロイするためのYAMLファイルで、
+ ストリーミングレプリケーションチェックで利用するユーザ名とパスワードを表す環境変数を設定します。
+ <varname>sr_check_user</varname>に指定したユーザの情報を格納しているSecretを事前に作成しておき、
+ 環境変数として参照するように設定します。
+ ほとんどのPostgreSQL Operatorでは、<productname>PostgreSQL</productname>クラスタを作成するときに、
+ <productname>PostgreSQL</productname>ユーザの<varname>username</varname>および
+ <varname>password</varname>を保存しているいくつかのSecretが自動的に作成されます。
+ <command>kubectl get secret</command>コマンドを実行し、既存のSecretを確認します。
+ </para>
+ <para>
+ 以下の環境変数では、mypostgres-postgres-secretというSecretを参照しています。
+ </para>
+ <programlisting>
+env:
+- name: POSTGRES_USERNAME
+ valueFrom:
+ secretKeyRef:
+ name: mypostgres-postgres-secret
+ key: username
+- name: POSTGRES_PASSWORD
+ valueFrom:
+ secretKeyRef:
+ name: mypostgres-postgres-secret
+ key: password
+ </programlisting>
+ <para>
+ しかし、Kubernetes環境では、Pgpool-IIはすべてのレプリカに接続するのではなく、
+ レプリカSerivceを経由して、いずれかのレプリカに接続します。
+ レプリカが複数存在しても、Pgpool-IIが1台のレプリカとして管理しています。
+ そのため、レプリカServiceにぶら下がっている複数のレプリカのうち、
+ どのレプリカが遅延しているのかはPgpool-IIが正確に判断できません。
+ この機能を無効にするには、以下のパラメータを設定します。
+ </para>
+ <programlisting>
+sr_check_period = 0
+ </programlisting>
+ </sect3>
+
+ <sect3 id="ssl-configuration">
+ <title>SSL接続</title>
+ <para>
+ クライアントとPgpool-IIの間のSSL接続を有効にするために、
+ sslをonに設定する必要があります。
+ </para>
+ <programlisting>
+ssl = on
+ </programlisting>
+ <para>
+ <varname>ssl = on</varname>を設定すると、Pgpool-II Pod起動時に、
+ 秘密鍵および証明書ファイルが自動的に<filename>/opt/pgpool-II/certs/</filename>配下に作成されます。
+ また、Pgpool-IIのパラメータ<varname>ssl_key</varname>や<varname>ssl_cert</varname>
+ も秘密鍵および証明書ファイルのパスに合わせて自動的に設定されます。
+ </para>
+ <para>
+ さらに、クライアントがPgpool-IIに接続する際に、SSL接続のみを許可するには、
+ pool_hba.confにてTCP/IPを使用した接続に対応するレコードを以下のように設定します。
+ pool_hba.confの設定方法については、
+ <xref linkend="example-Kubernetes-configure-pgpool-configmap">をご参照ください。
+ </para>
+ <programlisting>
+hostssl all all 0.0.0.0/0 md5
+ </programlisting>
+ </sect3>
+ </sect2>
+
+ <sect2 id="example-Kubernetes-monitoring">
+ <title>Pgpool-II Exporterによる監視</title>
+ <para>
+ <ulink url="https://github.com/pgpool/pgpool2_exporter">Pgpool-II Exporter</ulink>
+ は<productname>Pgpool-II</productname>の各種メトリクスを収集し、
+ <productname>Prometheus</productname>フォーマットで出力するツールです。
+ </para>
+ <para>
+ Pgpool-II Exporterを利用する場合は、サンプルのYAMLファイル
+ <filename>pgpool-deploy-monitor.yaml</filename>を利用します。
+ <filename>pgpool-deploy-monitor.yaml</filename>では、
+ <productname>Pgpool-II</productname>のPodに<productname>Pgpool-II</productname>のコンテナと
+ Pgpool-II Exporterのコンテナを作成しています。
+ </para>
+ <programlisting>
+spec:
+ containers:
+ - name: pgpool
+ image: pgpool/pgpool
+ ...
+ - name: pgpool-stats
+ image: pgpool/pgpool2_exporter
+ ...
+ </programlisting>
+ <para>
+ サンプルのYAMLファイル<filename>pgpool-deploy-monitor.yaml</filename>をダウンロードします。
+ </para>
+ <programlisting>
+$ curl -LO https://raw.githubusercontent.com/pgpool/pgpool2_on_k8s/master/pgpool-deploy-monitor.yaml
+ </programlisting>
+ <para>
+ Pgpool-IIおよびPgpool-II Exporterの設定を行います。
+ Pgpool-IIの設定は前述の<xref linkend="example-Kubernetes-deploy-pgpool">をご参照ください。
+ Pgpool-II ExporterからPgpool-IIに接続するための環境変数の設定は以下の通りです。
+ </para>
+ <programlisting>
+env:
+- name: POSTGRES_USERNAME
+ valueFrom:
+ secretKeyRef:
+ name: mypostgres-postgres-secret
+ key: username
+- name: POSTGRES_PASSWORD
+ valueFrom:
+ secretKeyRef:
+ name: mypostgres-postgres-secret
+ key: password
+- name: PGPOOL_SERVICE
+ value: "localhost"
+- name: PGPOOL_SERVICE_PORT
+ value: "9999"
+ </programlisting>
+ <para>
+ Pgpool-IIおよびPgpool-II Exporterの設定が完了したら、Pgpool-IIのPodをデプロイします。
+ </para>
+ <programlisting>
+kubectl apply -f pgpool-configmap.yaml
+kubectl apply -f pgpool-deploy-monitor.yaml
+ </programlisting>
</sect2>
</sect1>
diff --git a/doc/src/sgml/example-Kubernetes.sgml b/doc/src/sgml/example-Kubernetes.sgml
index 1274d796d..b2e0fa44d 100644
--- a/doc/src/sgml/example-Kubernetes.sgml
+++ b/doc/src/sgml/example-Kubernetes.sgml
@@ -1,15 +1,15 @@
<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.
+ This section describes 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>
+ recovery, automated 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>
@@ -21,7 +21,7 @@
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
+ This section describes 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>
@@ -63,61 +63,37 @@
<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.
+ <productname>Pgpool-II</productname>'s health check, automated 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'
+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'
+failover_on_backend_error = off
+
+sr_check_period = 10 (when using streaming replication check)
+sr_check_user='username of PostgreSQL user' (when using streaming replication check)
load_balance_mode = on
connection_cache = on
listen_addresses = '*'
</programlisting>
<para>
- There are two ways you can configure Pgpool-II.
+ There are two ways to configure Pgpool-II.
<orderedlist>
<listitem>
<para>
- Using environment variables
+ Using <ulink url="https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/">environment variables</ulink>
</para>
</listitem>
<listitem>
@@ -129,125 +105,109 @@ listen_addresses = '*'
</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.
+ In a production environment, we recommend using a ConfigMap to configure pgpool.conf 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>.
+ The following sections <xref linkend="example-Kubernetes-configure-pgpool-env">
+ and <xref linkend="example-Kubernetes-configure-pgpool-configmap"> describe
+ how to configure and deploy Pgpool-II pod using environment variables and
+ ConfigMap respectively. These sections are using a minimal setting for
+ demonstration purposes. We recommend that you read
+ <xref linkend="example-Kubernetes-advanced-configuration"> to see how to
+ properly configure Pgpool-II.
+ You can download the example 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.
+ You can define environment variables in the deployment manifest to configure
+ Pgpool-II's parameters.
+ <filename>pgpool-deploy-minimal.yaml</filename> is an example
+ manifest including the minimal settings of environment variables.
+ You can download <filename>pgpool-deploy-minimal.yaml</filename> and modify
+ the environment variables in this manifest.
</para>
<programlisting>
-$ curl -LO https://raw.githubusercontent.com/pgpool/pgpool2_on_k8s/master/pgpool_deploy.yaml
+$ curl -LO https://raw.githubusercontent.com/pgpool/pgpool2_on_k8s/master/pgpool-deploy-minimal.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.
+ Environment variables starting with <literal>PGPOOL_PARAMS_</literal> can be
+ converted to Pgpool-II's configuration parameters and these values can
+ override the default settings.
</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>
+ <para>
+ On kubernetes, you need to specify <emphasis>only two backend nodes</emphasis>.
+ Update <filename>pgpool-deploy-minimal.yaml</filename> based on your
+ PostgreSQL cluster information.
+ 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.
+ The setiing of <xref linkend="GUC-BACKEND-DATA-DIRECTORY"> is not required.
+ </para>
+ <para>
+ For example, the following environment variables defined in manifest,
+ </para>
+ <programlisting>
env:
- name: PGPOOL_PARAMS_BACKEND_HOSTNAME0
- value: "hippo"
+ value: "mypostgres"
- name: PGPOOL_PARAMS_BACKEND_HOSTNAME1
- value: "hippo-replica"
+ value: "mypostgres-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>
+ </programlisting>
+ <para>
+ will be convert to the following configuration parameters in pgpool.conf.
+ </para>
+ <programlisting>
+backend_hostname0 = 'mypostgres'
+backend_hostname1 = 'mypostgres-replica'
+backend_flag0 = 'ALWAYS_PRIMARY|DISALLOW_TO_FAILOVER'
+backend_flag1 = 'DISALLOW_TO_FAILOVER'
+ </programlisting>
+ <para>
+ Then, you need to define environment variables that contain the username and
+ password of <productname>PostgreSQL</productname> users for client authentication.
+ For more details see <xref linkend="pool-passwd-configuration">.
+ </para>
+ <para>
+ After configuring the manifest, run the following command to deploy
+ <productname>Pgpool-II</productname>.
+ </para>
+ <programlisting>
+kubectl apply -f pgpool-deploy-minimal.yaml
+ </programlisting>
</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.
+ Alternatively, you can use a Kubernetes <literal>ConfigMap</literal> to store
+ entire pgpool.conf 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>
+ 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
+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.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.
+ The manifest that defines the <literal>ConfigMap</literal> is in the
+ following format. You can update it based on your configuration preferences.
+ To use the <filename>pool_hba.conf</filename> for the client authentication,
+ you need to turn on <xref linkend="GUC-ENABLE-POOL-HBA">. Default is <varname>off</varname>.
</para>
<programlisting>
apiVersion: v1
@@ -255,81 +215,287 @@ kind: ConfigMap
metadata:
name: pgpool-config
labels:
- app: pgpool-config
+ name: pgpool-config
data:
pgpool.conf: |-
listen_addresses = '*'
port = 9999
- socket_dir = '/var/run/postgresql'
+ socket_dir = '/var/run/pgpool'
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
+ pcp_socket_dir = '/var/run/pgpool'
+ backend_hostname0 = 'postgres'
+...
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
+ hostssl 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.
+ Then, you need to define environment variables that contain the username and
+ password of PostgreSQL users for client authentication.
+ For more details see <xref linkend="pool-passwd-configuration">.
+ </para>
+ <para>
+ Run the following commands to create a ConfigMap and deploy the Pgpool-II pod
+ that references this ConfigMap.
</para>
<programlisting>
-kubectl apply -f pgpool_configmap.yaml
+kubectl apply -f pgpool-configmap.yaml
+kubectl apply -f pgpool-deploy.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>
+
+ <sect2 id="example-Kubernetes-advanced-configuration">
+ <title>Pgpool-II configuration</title>
+ <sect3 id="backend-configuration">
+ <title>Backend settings</title>
<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.
+ On kubernetes, you need to specify <emphasis>only two backend nodes</emphasis>.
+ Specify the primary service name to <xref linkend="GUC-BACKEND-HOSTNAME">0,
+ replica service name to <xref linkend="GUC-BACKEND-HOSTNAME">1.
</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
+backend_hostname0 = '<primary service name>'
+backend_hostname1 = '<replica service name>'
+backend_port0 = '5432'
+backend_port1 = '5432'
</programlisting>
+ </sect3>
+
+ <sect3 id="disable-failover-configuration">
+ <title>Automated failover</title>
+ <para>
+ Pgpool-II has the ability to periodically connect to the configured PostgreSQL
+ backends and check the state of PostgreSQL. If an error is detected, Pgpool-II
+ will trigger the failover.
+ On Kubernetes, Kubernetes monitors the PostgreSQL pods,
+ if a pod goes down, Kubernetes will restart a new one.
+ You need to disable Pgpool-II's automated failover,
+ becuase Pgpool-II's automated failover is not required on Kubernetes.
+ </para>
<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.
+ Specify PostgreSQL node 0 as primary (<literal>ALWAYS_PRIMARY</literal>),
+ because Service name doesn't change even if the primary or replica pod
+ is sacled, restarted or failover occurred.
</para>
<programlisting>
-kubectl apply -f pgpool_deploy_with_mount_configmap.yaml
+backend_flag0 ='ALWAYS_PRIMARY|DISALLOW_TO_FAILOVER'
+backend_flag1 ='DISALLOW_TO_FAILOVER'
+failover_on_backend_error = off
</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>
+
+ <sect3 id="pool-passwd-configuration">
+ <title>Register password to pool_passwd</title>
+ <para>
+ <productname>Pgpool-II</productname> performs authentication using
+ <xref linkend="GUC-POOL-PASSWD"> file which contains the passwords
+ of PostgreSQL users.
+ </para>
+ <para>
+ At <productname>Pgpool-II</productname> pod startup,
+ <productname>Pgpool-II</productname> automatically executes
+ <xref linkend="PG-MD5"> command to generate <filename>pool_passwd</filename>
+ based on the environment variables defined in the format
+ <literal><some string>_USERNAME</literal> and
+ <literal><some string>_PASSWORD</literal>.
+ </para>
+ <para>
+ The environment variables that represent the username and password of
+ <productname>PostgreSQL</productname> user must be defined in the following format:
+ </para>
+ <programlisting>
+username: <some string>_USERNAME
+password: <some string>_PASSWORD
+ </programlisting>
+ <para>
+ Define the environment variables using Secret is the recommended way to keep user credentials secure.
+ In most PostgreSQL Operators, several Secrets which define the
+ <productname>PostgreSQL</productname> user's redentials will be automaticlly
+ created when creating a PostgreSQL cluster.
+ Use <command>kubectl get secret</command> command to check the existing Secrets.
+ </para>
+ <para>
+ For example, <varname>mypostgres-postgres-secret</varname> is created to
+ store the username and password of <literal>postgres</literal> user.
+ To reference this secret, you can define the environment variables as below:
+ </para>
+ <programlisting>
+env:
+- name: POSTGRES_USERNAME
+ valueFrom:
+ secretKeyRef:
+ name: mypostgres-postgres-secret
+ key: username
+- name: POSTGRES_PASSWORD
+ valueFrom:
+ secretKeyRef:
+ name: mypostgres-postgres-secret
+ key: password
+ </programlisting>
+ <para>
+ When the <productname>Pgpool-II</productname> pod is started,
+ <filename>pool_passwd</filename> and <filename>pcp.conf</filename> are
+ automatically generated under <filename>/opt/pgpool-II/etc</filename>.
+ </para>
+ <programlisting>
+$ kubectl exec <pgpool pod> -it -- cat /opt/pgpool-II/etc/pool_passwd
+postgres:md53175bce1d3201d16594cebf9d7eb3f9d
+
+$ kubectl exec <pgpool pod> -it -- cat /opt/pgpool-II/etc/pcp.conf
+postgres:e8a48653851e28c69d0506508fb27fc5
+ </programlisting>
+ </sect3>
+
+ <sect3 id="sr-check-configuration">
+ <title>Streaming replication check</title>
+ <para>
+ <productname>Pgpool-II</productname> has the ability to periodically connect to the
+ configured PostgreSQL backends and check the replication delay.
+ To use this feature, <xref linkend="GUC-SR-CHECK-USER"> and <xref linkend="GUC-SR-CHECK-PASSWORD">
+ are required. If <varname>sr_check_password</varname> is left blank,
+ <productname>Pgpool-II</productname> will try to get the password for
+ <xref linkend="GUC-SR-CHECK-USER"> from <filename>pool_passwd</filename>.
+ </para>
+ <para>
+ Below is an example that connects to PostgreSQL using <literal>postgres</literal> user
+ every 10s to perform streaming replication check.
+ Because <varname>sr_check_password</varname> is left blank,
+ <productname>Pgpool-II</productname> will get the password of
+ <literal>postgres</literal> user from <filename>pool_passwd</filename>.
+ </para>
+ <programlisting>
+sr_check_period = 10
+sr_check_user='postgres'
+ </programlisting>
+ <para>
+ Create the secret to store the username and password of PostgreSQL user
+ specified in <varname>sr_check_user</varname> and configure the
+ environment variables to reference the created Secret.
+ In most PostgreSQL Operators, several secrets which define the
+ <productname>PostgreSQL</productname> user's redentials will be automaticlly
+ created when creating a PostgreSQL cluster.
+ Use <command>kubectl get secret</command> command to check the existing secrets.
+ </para>
+ <para>
+ For example, the environment variables below reference the
+ Secret <literal>mypostgres-postgres-secret</literal>.
+ </para>
+ <programlisting>
+env:
+- name: POSTGRES_USERNAME
+ valueFrom:
+ secretKeyRef:
+ name: mypostgres-postgres-secret
+ key: username
+- name: POSTGRES_PASSWORD
+ valueFrom:
+ secretKeyRef:
+ name: mypostgres-postgres-secret
+ key: password
+ </programlisting>
+ <para>
+ However, on Kubernetes Pgpool-II connects to any of the replicas
+ rather than connecting to all the replicas.
+ Even if there are multiple replicas, Pgpool-II manages them as one replica.
+ Therefore, Pgpool-II may not be able to properly determine the replication delay.
+ To disable this feature, configure the following parameter:
+ </para>
+ <programlisting>
+sr_check_period = 0
+ </programlisting>
+ </sect3>
+
+ <sect3 id="ssl-configuration">
+ <title>SSL settings</title>
+ <para>
+ Turn on <varname>ssl</varname> to enable the SSL connections.
+ </para>
+ <programlisting>
+ssl = on
+ </programlisting>
+ <para>
+ When <varname>ssl = on</varname>, at <productname>Pgpool-II</productname>
+ startup, private key file and certificate file will be automatically generated
+ under <filename>/opt/pgpool-II/certs/</filename>.
+ <varname>ssl_key</varname> and <varname>ssl_cert</varname>
+ will be automatically configured with the path of private key file and
+ certificate file.
+ </para>
+ <para>
+ In addition, to allow only SSL connections, add the following record
+ into the <filename>pool_hba.conf</filename>.
+ For more details on configuring <filename>pool_hba.conf</filename>
+ see <xref linkend="example-Kubernetes-configure-pgpool-configmap">.
+ </para>
+ <programlisting>
+hostssl all all 0.0.0.0/0 md5
+ </programlisting>
+ </sect3>
+ </sect2>
+
+ <sect2 id="example-Kubernetes-monitoring">
+ <title>Pgpool-II with monitoring</title>
+ <para>
+ <ulink url="https://github.com/pgpool/pgpool2_exporter">Pgpool-II Exporter</ulink>
+ is a Prometheus exporter for Pgpool-II metrics.
+ </para>
+ <para>
+ Sample manifest <filename>pgpool-deploy-monitor.yaml</filename> is used to deploy
+ Pgpool-II container and Pgpool-II Exporter container in the Pgpool-II Pod.
+ </para>
+ <programlisting>
+spec:
+ containers:
+ - name: pgpool
+ image: pgpool/pgpool
+ ...
+ - name: pgpool-stats
+ image: pgpool/pgpool2_exporter
+ ...
+ </programlisting>
+ <para>
+ Download the sample manifest <filename>pgpool-deploy-monitor.yaml</filename>.
+ </para>
+ <programlisting>
+$ curl -LO https://raw.githubusercontent.com/pgpool/pgpool2_on_k8s/master/pgpool-deploy-monitor.yaml
+ </programlisting>
+ <para>
+ Then, Configure Pgpool-II and Pgpool-II Exporter.
+ For more details on configuring Pgpool-II see the previous section <xref linkend="example-Kubernetes-deploy-pgpool">.
+ Below is the settings of the environment variables used in Pgpool-II exporter container
+ to connect to Pgpool-II.
+ </para>
+ <programlisting>
+env:
+- name: POSTGRES_USERNAME
+ valueFrom:
+ secretKeyRef:
+ name: mypostgres-postgres-secret
+ key: username
+- name: POSTGRES_PASSWORD
+ valueFrom:
+ secretKeyRef:
+ name: mypostgres-postgres-secret
+ key: password
+- name: PGPOOL_SERVICE
+ value: "localhost"
+- name: PGPOOL_SERVICE_PORT
+ value: "9999"
+ </programlisting>
+ <para>
+ After configuring Pgpool-II and Pgpool-II Exporter, deploy Pgpool-II Pod.
+ </para>
+ <programlisting>
+kubectl apply -f pgpool-configmap.yaml
+kubectl apply -f pgpool-deploy-monitor.yaml
+ </programlisting>
</sect2>
</sect1>
[parent: b49642453c07]