このページでは、AlloyDB Omni Kubernetes Operator を使用して AlloyDB Omni の PgBouncer 接続プールを有効にする方法と、その使用方法について説明します。
多くのアプリケーション（特にウェブ アプリケーション）はデータベース接続を頻繁に開いて閉じるため、データベース インスタンスに大きな負荷がかかります。PgBouncer を使用すると、接続をより効率的に管理してインスタンスの負荷を軽減します。接続を再利用することで、データベース インスタンスへの接続数が最小限に抑えられ、インスタンスのリソースが解放されます。
PgBouncer サービスを作成する
AlloyDB Omni Kubernetes Operator を使用すると、データベース専用の PgBouncer サービスを作成できます。それ以降は PgBouncer サービス経由でデータベースにアクセスし、接続プールのメリットを活用できます。
PgBouncer サービスを必要に応じて構成できるよう、専用のカスタム リソース定義（CRD）が用意されています。
データベース用の PgBouncer サービスを作成する手順は次のとおりです。
次のように、Kubernetes クラスタで
PgBouncerカスタム リソースを作成します。apiVersion: alloydbomni.dbadmin.goog/v1 kind: PgBouncer metadata: name: PGBOUNCER_NAME spec: dbclusterRef: DB_CLUSTER_NAME allowSuperUserAccess: true podSpec: resources: memory: 1Gi cpu: 1 image: "gcr.io/alloydb-omni/operator/g-pgbouncer:1.4.0" parameters: pool_mode: POOL_MODE ignore_startup_parameters: IGNORE_STARTUP_PARAMETERS default_pool_size: DEFAULT_POOL_SIZE max_client_conn: MAXIMUM_CLIENT_CONNECTIONS max_db_connections: MAXIMUM_DATABASE_CONNECTIONS serviceOptions: type: "ClusterIP"
次のように置き換えます。
PGBOUNCER_NAME: PgBouncer カスタム リソースの名前。DB_CLUSTER_NAME: AlloyDB Omni データベース クラスタの名前。これは、作成時に宣言したデータベース クラスタ名と同じです。POOL_MODE: データベース接続が他のクライアントで再利用可能になるタイミングを指定します。このパラメータは次のいずれかに設定します。session: データベース接続はクライアントが接続を解除した後でプールに戻されます。デフォルトで使用されます。transaction: データベース接続はトランザクションの完了後にプールに戻されます。statement: データベース接続はクエリの完了後にプールに戻されます。このモードでは、複数のステートメントにまたがるトランザクションは許可されません。
IGNORE_STARTUP_PARAMETERS: PgBouncer で許可されないパラメータを指定して、起動時に無視されるようにします（例:extra_float_digits）。詳細については、PgBouncer の構成をご覧ください。DEFAULT_POOL_SIZE: ユーザーとデータベースのペアごとに許可するデータベース接続の数（例:8）。MAXIMUM_CLIENT_CONNECTIONS: クライアント接続の最大数（例:800）。MAXIMUM_DATABASE_CONNECTIONS: データベース接続の最大数（例:160）。
次のようにマニフェストを適用します。
kubectl apply -f PATH_TO_MANIFEST -n NAMESPACEPATH_TO_MANIFEST は、マニフェスト ファイルのパスに置き換えます（例:
/fleet/config/pgbouncer.yaml）。作成した PgBouncer オブジェクトの準備ができていることを確認するため、次のクエリを実行します。
kubectl get pgbouncers.alloydbomni.dbadmin.goog PGBOUNCER_NAME -n NAMESPACE -wNAMESPACEは、PgBouncer オブジェクト用の Kubernetes Namespace の名前に置き換えます。出力は次のようになります。
NAMESPACE NAME ENDPOINT STATE dbv2 mypgbouncer dbv2 mypgbouncer dbv2 mypgbouncer dbv2 mypgbouncer WaitingForDeploymentReady dbv2 mypgbouncer Acquiring IP dbv2 mypgbouncer 10.138.15.231 Ready
接続プーラー エンドポイントに接続する
PgBouncer の接続プーラーには、Kubernetes クラスタの内部または外部から接続できます。
Kubernetes クラスタの内部から接続する
psql クライアントを使用して接続プーラー エンドポイントに接続する手順は次のとおりです。
次のように Pod を作成します。
apiVersion: v1 kind: Pod metadata: name: postgres spec: containers: - image: "docker.io/library/postgres:latest" command: - "sleep" - "604800" name: db-client次のようにマニフェストを適用します。
kubectl apply -f PATH_TO_MANIFEST -n NAMESPACEコンテナ化されたアプリケーションに接続します。
kubectl exec -it postgres -n NAMESPACE -- bashpsqlクライアントを使用して、PgBouncer エンドポイントへの SSL 接続を確認します。export PGSSLMODE="require"; psql -h HOST -d postgres -U postgres -p PORT次のように置き換えます。
HOST:kubectl get pgbouncers.alloydbomni.dbadmin.goog -n NAMESPACEコマンドを使用して取得した接続プーラー エンドポイント。PgBouncer がサービスとして公開されていない場合は、PgBouncer の IP アドレスを使用します。PORT: PgBouncer がリッスンするポート。
ターミナル ウィンドウに
psqlのログイン テキストが表示され、最後にpostgres=#のプロンプトが表示されます。
Kubernetes クラスタの外部から接続する
Kubernetes クラスタの外部から PgBouncer 接続プーラーにアクセスするには、serviceOptions 属性の type フィールドを LoadBalancer に設定します。これにより、loadbalancer サービスが作成されます。
次のように、Kubernetes クラスタで
PgBouncerカスタム リソースを作成します。apiVersion: alloydbomni.dbadmin.goog/v1 kind: PgBouncer metadata: name: PGBOUNCER_NAME spec: dbclusterRef: DB_CLUSTER_NAME allowSuperUserAccess: true replicaCount: 2 parameters: pool_mode: POOL_MODE ignore_startup_parameters: IGNORE_STARTUP_PARAMETERS default_pool_size: DEFAULT_POOL_SIZE max_client_conn: MAXIMUM_CLIENT_CONNECTIONS max_db_connections: MAXIMUM_DATABASE_CONNECTIONS podSpec: resources: memory: 1Gi cpu: 1 image: "gcr.io/alloydb-omni/operator/g-pgbouncer:1.4.0" serviceOptions: type: "LoadBalancer"
次のようにマニフェストを適用します。
kubectl apply -f PATH_TO_MANIFEST作成した PgBouncer オブジェクトの準備ができていることを確認するため、次のクエリを実行します。
kubectl get pgbouncers.alloydbomni.dbadmin.goog PGBOUNCER_NAME -n NAMESPACE -w出力は次のようになります。
NAME ENDPOINT STATE mypgbouncer 10.138.15.207 Ready
PgBouncer の設定を構成する
PGBouncer の設定を構成するには、次のパラメータを使用します。
| パラメータ | 説明 | デフォルト値 |
|---|---|---|
pool_mode |
データベース接続が他のクライアントで再利用可能になるタイミングを指定します。 使用できる値は次のとおりです。
|
session |
ignore_startup_parameters |
PgBouncer で許可されていないパラメータを指定して、起動時に無視されるようにします。 | |
default_pool_size |
ユーザーとデータベースのペアごとに許可するデータベース接続数。 | 20 |
max_client_conn |
クライアント接続の最大数。 | 100 |
max_db_connections |
データベース接続の最大数。 | 0 |
PgBouncer のデプロイをカスタマイズする
AlloyDB Omni では、カスタム リソースを使用してコンポーネントを管理します。Kubernetes 上の AlloyDB Omni 内にある PgBouncer のデプロイをカスタマイズするには、PgBouncer カスタム リソースを次のように変更します。
PgBouncerカスタム リソースを一覧表示します。kubectl get pgbouncers -n NAMESPACENAMESPACE は、AlloyDB Omni をデプロイした Namespace に置き換えます。
リソースを変更するために、
PgBouncerリソースの宣言ファイルをデフォルトのエディタで開きます。kubectl edit pgbouncers PGBOUNCER_NAME -n NAMESPACE宣言ファイルで、構成が含まれる
podSpecセクションを見つけ、次のフィールドを必要に応じて変更します。resources: コンテナ用に定義されたcpuとmemory。apiVersion: alloydbomni.dbadmin.goog/v1 kind: PgBouncer metadata: name: PGBOUNCER_NAME spec: dbclusterRef: DB_CLUSTER_NAME replicaCount: 2 parameters: pool_mode: POOL_MODE ignore_startup_parameters: IGNORE_STARTUP_PARAMETERS default_pool_size: DEFAULT_POOL_SIZE max_client_conn: MAXIMUM_CLIENT_CONNECTIONS max_db_connections: MAXIMUM_DATABASE_CONNECTIONS podSpec: resources: memory: 1Gi cpu: 1 ...image: PgBouncer イメージタグのパス。... podSpec: resources: memory: 1Gi cpu: 1 image: IMAGE ...schedulingconfig: PgBouncer Pod のスケジュール方法を制御するnodeaffinityセクションを含めます。... podSpec: resources: memory: 1Gi cpu: 1 image: IMAGE schedulingconfig: nodeaffinity: NODE_AFFINITY_TYPE: nodeSelectorTerms: - matchExpressions: - key: LABEL_KEY operator: OPERATOR_VALUE values: - pgbouncer ...次のように置き換えます。
NODE_AFFINITY_TYPE: このパラメータは次のいずれかに設定します。requiredDuringSchedulingIgnoredDuringExecution: Kubernetes は、定義されたルールに基づいて Pod をスケジュールします。preferredDuringSchedulingIgnoredDuringExecution: Kubernetes スケジューラは、定義されたスケジュール ルールを満たすノードを探します。そのようなノードがない場合、Kubernetes はクラスタ内の別のノードにスケジュールします。
LABEL_KEY: ロケーション インジケーターとして機能し、クラスタ全体に Pod を均等に分散するキーのノードラベル（例:nodetype）。OPERATOR_VALUE: キーと値のセットの関係を表します。このパラメータは次のいずれかに設定します。In: values 配列は空にできません。NotIn: values 配列は空にできません。Exists: values 配列は空にする必要があります。DoesNotExist: values 配列は空にする必要があります。Gt: values 配列には、整数として解釈される単一の要素が必要です。Lt: values 配列には、整数として解釈される単一の要素が必要です。
変更が完了したら、宣言ファイルを保存します。AlloyDB Omni Kubernetes オペレーターにより、変更内容が PgBouncer のデプロイに自動的に適用されます。
ノード アフィニティを使用してスケジュールを設定する
ノード アフィニティを使用して PgBouncer Pod のスケジュール設定場所を制御すると、通常のスケジューリングよりも正確な配置が可能になります。ノード アフィニティにより、特定の条件を満たす（たとえば、特定のラベルを持つ）ノードに PgBouncer Pod が配置されます。
PgBouncer Pod のノード アフィニティを指定するには、PgBouncer カスタム リソースを変更して、podSpec セクションに schedulingconfig セクションを追加します。
apiVersion: alloydbomni.dbadmin.goog/v1
kind: PgBouncer
metadata:
name: PGBOUNCER_NAME
spec:
# ... other PgBouncer configuration ...
podSpec:
# ... other podSpec settings ...
schedulingconfig:
nodeaffinity:
NODE_AFFINITY_TYPE:
nodeSelectorTerms:
- matchExpressions:
- key: LABEL_KEY
operator: OPERATOR_VALUE
values:
- pgbouncer
次のように置き換えます。
NODE_AFFINITY_TYPE: このパラメータは次のいずれかに設定します。requiredDuringSchedulingIgnoredDuringExecution: Kubernetes は、定義されたルールに基づいて Pod をスケジュールします。preferredDuringSchedulingIgnoredDuringExecution: Kubernetes スケジューラは、定義されたスケジューリング ルールを満たすノードを探します。そのようなノードがない場合、Kubernetes はクラスタ内の別のノードにスケジュールします。
LABEL_KEY: ノードのラベルキー。例:disktype=ssdOPERATOR_VALUE: キーと値のセットの関係を表します。このパラメータは次のいずれかに設定します。In: ノードラベルの値は、values配列の値と一致する必要があります。NotIn: ノードラベルの値は、values配列内のどの値とも一致してはなりません。Exists: ラベルLABEL_KEYがノードに存在する必要があります。values配列は空である必要があります。DoesNotExist: ラベルLABEL_KEYがノードに存在してはなりません。values配列は空である必要があります。Gt: ノードラベルの値は、values配列内の単一の値（整数として解釈される）よりも大きくなければなりません。Lt: ノードラベルの値は、values配列内の単一の値（整数として解釈される）よりも小さくなければなりません。
次の例は、nodetype=pgbouncer というラベルの付いたノードで PgBouncer Pod をスケジュールする方法を示しています。
apiVersion: alloydbomni.dbadmin.goog/v1
kind: PgBouncer
metadata:
name: mypgbouncer
spec:
# ... other PgBouncer configuration ...
podSpec:
# ... other podSpec settings ...
schedulingconfig:
nodeaffinity:
requiredDuringSchedulingIgnoredDuringExecution:
nodeSelectorTerms:
- matchExpressions:
- key: nodetype
operator: In
values:
- pgbouncer
この例では、requiredDuringSchedulingIgnoredDuringExecution 設定により、PgBouncer Pod はラベル nodetype=pgbouncer を持つノードでのみスケジュールされます。
PgBouncer リソースを削除する
PgBouncer カスタム リソースを削除するには、次のコマンドを実行します。
kubectl delete pgbouncers.alloydbomni.dbadmin.goog PGBOUNCER_NAME -n NAMESPACE出力は次のようになります。
pgbouncer.alloydbomni.dbadmin.goog "mypgbouncer" deleted
PgBouncer ログを表示する
Kubernetes 上の AlloyDB Omni デプロイ内の PgBouncer レプリカ インスタンスのログを表示して分析する手順は次のとおりです。
Namespace 内のすべての PgBouncer Pod のリストを取得します。
kubectl get pods -n NAMESPACE出力は次のようになります。
NAME READY STATUS RESTARTS AGE al-092d-dbcluster-sample-0 3/3 Running 0 3d1h mypgbouncer-pgb-deployment-659869f95c-4kbgv 1/1 Running 0 27m特定の Pod のログを表示します。
kubectl logs -f POD_NAME -n NAMESPACE出力は次のようになります。
2025-01-21 06:57:39.549 UTC [7] LOG kernel file descriptor limit: 1048576 (hard: 1048576); max_client_conn: 800, max expected fd use: 812 2025-01-21 06:57:39.550 UTC [7] LOG listening on 0.0.0.0:6432 2025-01-21 06:57:39.550 UTC [7] LOG listening on [::]:6432 2025-01-21 06:57:39.550 UTC [7] LOG listening on unix:/tmp/.s.PGSQL.6432 2025-01-21 06:57:39.550 UTC [7] LOG process up: PgBouncer 1.23.0, libevent 2.1.12-stable (epoll), adns: evdns2, tls: OpenSSL 3.0.13 30 Jan 2024 2025-01-21 06:58:17.012 UTC [7] LOG C-0x55f2b1b322a0: (nodb)/(nouser)@10.138.15.215:48682 registered new auto-database: alloydbadmin 2025-01-21 06:58:17.012 UTC [7] LOG S-0x55f2b1b4ecb0: alloydbadmin/alloydbpgbouncer@10.138.0.48:5432 new connection to server (from 10.12.1.113:53156) 2025-01-21 06:58:17.042 UTC [7] LOG S-0x55f2b1b4ecb0: alloydbadmin/alloydbpgbouncer@10.138.0.48:5432 SSL established: TLSv1.3/TLS_AES_256_GCM_SHA384/ECDH=prime256v1 2025-01-21 06:58:17.052 UTC [7] LOG C-0x55f2b1b322a0: pgbouncer/statsuser@10.138.15.215:48682 login attempt: db=pgbouncer user=statsuser tls=TLSv1.3/TLS_AES_256_GCM_SHA384 replication=no 2025-01-21 06:58:19.526 UTC [7] LOG C-0x55f2b1b322a0: pgbouncer/statsuser@10.138.15.215:48682 closing because: client close request (age=2s) 2025-01-21 06:58:20.344 UTC [7] LOG C-0x55f2b1b322a0: pgbouncer/statsuser@10.138.15.215:46796 login attempt: db=pgbouncer user=statsuser tls=TLSv1.3/TLS_AES_256_GCM_SHA384 replication=no
PgBouncer のパフォーマンスとアクティビティをモニタリングする
PgBouncer 接続プールの指標を表示するには、専用の statsuser のみを使用して PgBouncer 内部統計データベースにアクセスします。statsuser は、PgBouncer データベースに接続する際の認証に使用されます。
psqlクライアントを使用して、スーパーユーザーまたはCREATE ROLE権限を持つユーザーとして AlloyDB Omni に接続します。export PGPASSWORD="ChangeMe123"; export PGSSLMODE="require"; psql -h HOST -d postgres -U postgres -p PORT出力は次のようになります。
psql (16.6 (Ubuntu 16.6-0ubuntu0.24.04.1), server 15.7) SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off) Type "help" for help.AlloyDB Omni に
statsuserを作成します。postgres=# CREATE USER "statsuser" WITH PASSWORD 'tester';出力は次のようになります。
CREATE ROLE postgres=#statsuserとして PgBouncer データベースに接続します。export PGPASSWORD="ChangeMe123"; export PGSSLMODE="require"; psql -h HOST -d pgbouncer -U statsuser -p PORT出力は次のようになります。
psql (16.6 (Ubuntu 16.6-0ubuntu0.24.04.1), server 1.23.0/bouncer) WARNING: psql major version 16, server major version 1.23. Some psql features might not work. SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off) Type "help" for help.SHOW STATSコマンドを実行して PgBouncer のパフォーマンスを表示し、潜在的な問題を特定します。pgbouncer=# SHOW STATS;出力は次のようになります。
database | total_server_assignment_count | total_xact_count | total_query_count | total_received | total_sent | total_xact_time | total_query_time | total_wait_time | avg_server_assignment_count | avg_xact_count | avg_query_count | avg_recv | avg_sent | avg_xact_time | avg_query_time | avg_wait_time -------------+-------------------------------+------------------+-------------------+----------------+------------+-----------------+------------------+-----------------+-----------------------------+----------------+-----------------+----------+----------+---------------+----------------+--------------- alloydbadmin | 1 | 0 | 0 | 0 | 330 | 0 | 0 | 41730 | 0 | 0 | 0 | 0 | 2 | 0 | 0 | 41730 pgbouncer | 0 | 5 | 5 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 (2 rows)
AlloyDB Omni インスタンスへのネットワーク アクセスを構成する
Kubernetes 上の AlloyDB Omni デプロイのセキュリティを確保するため、CIDR（クラスレス ドメイン間ルーティング）表記を使用して特定の IP アドレス範囲を定義し、PgBouncer 接続プーラーへのネットワーク アクセスを制限できます。
CIDR 表記は、IP アドレスとプレフィックス長を組み合わせたものです。たとえば、CIDR ブロック 192.168.1.0/24 はアドレス 192.168.1.0 とプレフィックス長 24 を指定します。プレフィックス長は IP アドレスでネットワーク部に使用するビット数を指定し、サブネット マスクを定義します。
デプロイの宣言ファイルで serviceOptions セクションを見つけて、loadBalancerSourceRanges 設定を追加または変更します。
serviceOptions:
type: "LoadBalancer"
loadBalancerSourceRanges:
- "CIDR_BLOCK"
CIDR_BLOCK は、LoadBalancer サービスへの受信接続で許可される IP アドレス範囲を指定する CIDR 文字列に置き換えます。loadBalancerSourceRanges 設定は、受信ネットワーク トラフィックをフィルタし、データベース インスタンスにアクセスできるクライアントを制御します。
loadBalancerSourceRanges 構成が正しく適用されたことを確認するため、次のコマンドを使用して、LoadBalancer サービスに割り当てられた外部 IP アドレスを確認します。
kubectl get svc -n NAMESPACE -w
NAMESPACE は、AlloyDB Omni のデプロイが配置されている Namespace に置き換えます。
出力は次のようになります。
NAME TYPE CLUSTER_IP EXTERNAL_IP PORT(S) AGE
al-mypgbouncer-pgb-svc LoadBalancer 34.118.230.149 10.138.0.26 6432:31367/TCP 3m39s
LoadBalancer の準備が整うと、LoadBalancer サービスに割り当てられた外部 IP アドレスが EXTERNAL_IP 列に表示されます。この外部 IP への接続は、loadBalancerSourceRanges の設定に基づいてフィルタされます。
外部 IP を確認したら、許可される CIDR 範囲内のアプリケーションから接続をテストし、接続できることを確認します。
PgBouncer 接続プーラーを無効にする
PgBouncer 接続プーラーを無効にするかロールバックする必要がある場合は、次の操作を行います。
接続プーラーのステータスを確認します。
kubectl get deployment fleet-controller-manager --namespace alloydb-omni-system -o json | jq '.spec.template.spec.containers[0].args'このコマンドは、AlloyDB Omni フリートの管理に使用するプライマリ コントローラのデプロイ マニフェストを表示します。
containers配列のargsセクションで--enable-pgbouncerオプションを見つけます。... spec: containers: - name: fleet-controller-manager image:... args: --health-probe-bind-address=:8081", --metrics-bind-address=127.0.0.1:8080", --leader-elect", --image-registry=gcr.io", --data-plane-image-repository=alloydb-omni-staging", --control-plane-agents-image-repository=aedi-gbox", --control-plane-agents-tag=jan19v3", --additional-db-versions-for-test-only=latest", --enable-multiple-backup-solutions=true", --enable-pgbouncer=true接続プーラーを無効にするため、コントローラのデプロイの構成を編集します。
kubectl edit deployment fleet-controller-manager --namespace alloydb-omni-systemデプロイ マニフェストで、
--enable-pgbouncerオプションの値をtrueからfalseに変更します。... --enable-pgbouncer=falseファイルを保存して、エディタを終了します。
kubectlによって変更が自動的に適用されます。