Halaman ini diterjemahkan oleh Cloud Translation API.

Menggunakan penggabungan koneksi PgBouncer

Pilih versi dokumentasi:

Halaman ini menjelaskan cara mengaktifkan dan menggunakan penggabung koneksi PgBouncer untuk AlloyDB Omni menggunakan operator AlloyDB Omni Kubernetes.

Banyak aplikasi, terutama aplikasi web, sering membuka dan menutup koneksi database, yang dapat memberikan beban signifikan pada instance database. PgBouncer membantu mengurangi beban instance dengan mengelola koneksi secara lebih efisien. Dengan menggunakan kembali koneksi, PgBouncer meminimalkan jumlah koneksi ke instance database, sehingga membebaskan resource pada instance.

Membuat layanan PgBouncer

Operator Kubernetes AlloyDB Omni memungkinkan Anda membuat layanan PgBouncer khusus untuk database Anda. Kemudian, Anda dapat mengakses database melalui layanan PgBouncer untuk memanfaatkan penggabungan koneksi.

Ada definisi resource kustom (CRD) khusus untuk mengonfigurasi layanan PgBouncer sesuai kebutuhan.

Untuk membuat layanan PgBouncer bagi database Anda, ikuti langkah-langkah berikut:

Buat resource kustom PgBouncer di cluster Kubernetes Anda sebagai berikut:
```
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"
```
Ganti kode berikut:
- PGBOUNCER_NAME: nama resource kustom PgBouncer Anda.
- DB_CLUSTER_NAME: nama cluster database AlloyDB Omni Anda. Nama cluster database ini sama dengan yang Anda deklarasikan saat membuatnya.
- POOL_MODE: menentukan kapan koneksi database dapat digunakan kembali oleh klien lain. Tetapkan parameter ke salah satu opsi berikut:
  - session: koneksi database dilepaskan kembali ke pool setelah klien terputus. Digunakan secara default.
  - transaction: koneksi database dilepaskan kembali ke pool setelah transaksi selesai.
  - statement: koneksi database dilepaskan kembali ke pool setelah kueri selesai. Transaksi yang mencakup beberapa pernyataan tidak diizinkan dalam mode ini.
- IGNORE_STARTUP_PARAMETERS: menentukan parameter yang tidak diizinkan oleh PgBouncer sehingga diabaikan selama startup—misalnya, extra_float_digits. Untuk mengetahui informasi selengkapnya, lihat Konfigurasi PgBouncer.
- DEFAULT_POOL_SIZE: jumlah koneksi database yang diizinkan per pasangan database pengguna—misalnya, 8.
- MAXIMUM_CLIENT_CONNECTIONS: jumlah maksimum koneksi klien—misalnya, 800.
- MAXIMUM_DATABASE_CONNECTIONS: jumlah maksimum koneksi database—misalnya, 160.
Terapkan manifes:
```
kubectl apply -f PATH_TO_MANIFEST -n NAMESPACE
```
Ganti PATH_TO_MANIFEST dengan jalur ke file manifes Anda—misalnya, /fleet/config/pgbouncer.yaml.

Untuk memverifikasi bahwa objek PgBouncer yang Anda buat sudah siap, jalankan kueri berikut:

kubectl get pgbouncers.alloydbomni.dbadmin.goog PGBOUNCER_NAME  -n NAMESPACE -w

Ganti NAMESPACE dengan nama namespace Kubernetes untuk objek PgBouncer Anda.

Outputnya mirip dengan hal berikut ini:

NAMESPACE   NAME          ENDPOINT        STATE
dbv2        mypgbouncer
dbv2        mypgbouncer
dbv2        mypgbouncer
dbv2        mypgbouncer                   WaitingForDeploymentReady
dbv2        mypgbouncer                   Acquiring IP
dbv2        mypgbouncer   10.138.15.231   Ready

Terhubung ke endpoint penggabung koneksi

Anda dapat terhubung ke pengumpul koneksi PgBouncer dari dalam atau luar cluster Kubernetes.

Menghubungkan dari dalam cluster Kubernetes

Untuk terhubung ke endpoint penggabung koneksi menggunakan klien psql, ikuti langkah-langkah berikut:

Buat Pod sebagai berikut:

apiVersion: v1
kind: Pod
metadata:
  name: postgres
spec:
  containers:
  - image: "docker.io/library/postgres:latest"
    command:
     - "sleep"
     - "604800"
    name: db-client

Terapkan manifes:

kubectl apply -f PATH_TO_MANIFEST -n NAMESPACE

Hubungkan ke aplikasi dalam container:

kubectl exec -it postgres -n NAMESPACE -- bash

Verifikasi koneksi SSL ke endpoint PgBouncer menggunakan klien psql:
```
export PGSSLMODE="require"; psql -h HOST -d postgres -U postgres -p PORT
```
Ganti kode berikut:
- HOST: endpoint penggabungan koneksi yang Anda dapatkan menggunakan perintah kubectl get pgbouncers.alloydbomni.dbadmin.goog -n NAMESPACE. Jika PgBouncer tidak diekspos sebagai layanan, gunakan alamat IP-nya.
- PORT: port yang diproses PgBouncer.
Jendela terminal menampilkan teks login psql yang diakhiri dengan perintah postgres=#.

Menghubungkan dari luar cluster Kubernetes

Untuk mengakses penggabung koneksi PgBouncer dari luar cluster Kubernetes, tetapkan kolom type dalam atribut serviceOptions ke LoadBalancer, yang akan membuat layanan loadbalancer.

Buat resource kustom PgBouncer di cluster Kubernetes Anda sebagai berikut:

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"

Terapkan manifes:
```
kubectl apply -f PATH_TO_MANIFEST
```

Untuk memverifikasi bahwa objek PgBouncer yang Anda buat sudah siap, jalankan kueri berikut:

kubectl get pgbouncers.alloydbomni.dbadmin.goog PGBOUNCER_NAME  -n NAMESPACE -w

Outputnya mirip dengan hal berikut ini:

NAME          ENDPOINT       STATE
mypgbouncer   10.138.15.207   Ready

Mengonfigurasi setelan PgBouncer

Gunakan parameter berikut untuk mengonfigurasi setelan PGBouncer:

Parameter	Deskripsi	Nilai default
`pool_mode`	Menentukan kapan koneksi database dapat digunakan kembali oleh klien lain. Nilai yang diizinkan adalah sebagai berikut: `session`: koneksi database dilepaskan kembali ke pool setelah klien terputus. `transaction`: koneksi database dilepaskan kembali ke pool setelah transaksi selesai. `statement`: koneksi database dilepaskan kembali ke kumpulan setelah kueri selesai. Transaksi yang mencakup beberapa pernyataan tidak diizinkan dalam mode ini.	`session`
`ignore_startup_parameters`	Menentukan parameter yang tidak diizinkan oleh PgBouncer sehingga diabaikan selama startup.
`default_pool_size`	Jumlah koneksi database yang diizinkan per pasangan pengguna-database.	`20`
`max_client_conn`	Jumlah maksimum koneksi klien.	`100`
`max_db_connections`	Jumlah maksimum koneksi database.	`0`

Menyesuaikan deployment PgBouncer

AlloyDB Omni menggunakan resource kustom untuk mengelola komponennya. Untuk menyesuaikan deployment PgBouncer dalam AlloyDB Omni di Kubernetes, Anda mengubah resource kustom PgBouncer sebagai berikut:

Mencantumkan resource kustom PgBouncer:
```
kubectl get pgbouncers -n NAMESPACE
```
Ganti NAMESPACE dengan namespace tempat Anda men-deploy AlloyDB Omni.
Untuk mengubah resource, buka file deklarasi untuk resource PgBouncer di editor default Anda:
```
kubectl edit pgbouncers PGBOUNCER_NAME -n NAMESPACE
```
Dalam file deklarasi, temukan bagian podSpec yang berisi konfigurasi dan ubah salah satu kolom berikut sesuai kebutuhan:
- resources: cpu dan memory yang ditentukan untuk container Anda:
```
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: jalur ke tag image PgBouncer:
```
...
  podSpec:
    resources:
      memory: 1Gi
      cpu: 1
    image: IMAGE
...
```
- schedulingconfig: sertakan bagian nodeaffinity untuk mengontrol tempat Pod PgBouncer dijadwalkan:
```
...
  podSpec:
    resources:
      memory: 1Gi
      cpu: 1
    image: IMAGE
    schedulingconfig:
      nodeaffinity:
        NODE_AFFINITY_TYPE:
          nodeSelectorTerms:
          - matchExpressions:
            - key: LABEL_KEY
              operator: OPERATOR_VALUE
              values:
              - pgbouncer
...
```
  Ganti kode berikut:
  - NODE_AFFINITY_TYPE: tetapkan parameter ke salah satu opsi berikut:
    - requiredDuringSchedulingIgnoredDuringExecution: Kubernetes menjadwalkan Pod berdasarkan aturan yang ditentukan.
    - preferredDuringSchedulingIgnoredDuringExecution: scheduler Kubernetes mencoba menemukan node yang memenuhi aturan yang ditentukan untuk penjadwalan. Namun, jika tidak ada node seperti itu, Kubernetes akan menjadwalkan ke node lain dalam cluster.
  - LABEL_KEY: label node untuk kunci yang berfungsi sebagai indikator lokasi dan memfasilitasi distribusi Pod yang merata di seluruh cluster—misalnya, nodetype.
  - OPERATOR_VALUE: merepresentasikan hubungan kunci dengan sekumpulan nilai. Tetapkan parameter ke salah satu opsi berikut:
    - In: array nilai tidak boleh kosong.
    - NotIn: array nilai tidak boleh kosong.
    - Exists: array nilai harus kosong.
    - DoesNotExist: array nilai harus kosong.
    - Gt: array nilai harus memiliki satu elemen, yang ditafsirkan sebagai bilangan bulat.
    - Lt: array nilai harus memiliki satu elemen, yang ditafsirkan sebagai bilangan bulat.
Setelah melakukan perubahan, simpan file pernyataan. Operator AlloyDB Omni Kubernetes akan otomatis menerapkan perubahan pada deployment PgBouncer Anda.

Hapus resource PgBouncer

Untuk menghapus resource kustom PgBouncer, jalankan perintah berikut:

kubectl delete pgbouncers.alloydbomni.dbadmin.goog PGBOUNCER_NAME -n NAMESPACE

Outputnya mirip dengan hal berikut ini:

pgbouncer.alloydbomni.dbadmin.goog "mypgbouncer" deleted

Melihat log PgBouncer

Anda dapat melihat dan menganalisis log instance replika PgBouncer di deployment AlloyDB Omni di Kubernetes sebagai berikut:

Dapatkan daftar semua Pod PgBouncer di namespace Anda:

kubectl get pods -n NAMESPACE

Outputnya mirip dengan hal berikut ini:

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

Melihat log untuk Pod tertentu:

kubectl logs -f POD_NAME -n NAMESPACE

Outputnya mirip dengan hal berikut ini:

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

Memantau performa dan aktivitas PgBouncer

Anda dapat melihat metrik kumpulan koneksi PgBouncer hanya menggunakan statsuser khusus untuk mengakses database statistik internal PgBouncer. statsuser digunakan untuk autentikasi saat terhubung ke database PgBouncer.

Hubungkan ke AlloyDB Omni sebagai superuser atau pengguna dengan hak istimewa CREATE ROLE menggunakan klien psql:

export PGPASSWORD="ChangeMe123"; export PGSSLMODE="require"; psql -h HOST -d postgres -U postgres -p PORT

Outputnya mirip dengan hal berikut ini:

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.

Buat statsuser di AlloyDB Omni Anda:

postgres=# CREATE USER "statsuser" WITH PASSWORD 'tester';

Outputnya mirip dengan hal berikut ini:

CREATE ROLE
postgres=#

Hubungkan ke database PgBouncer sebagai statsuser:

export PGPASSWORD="ChangeMe123"; export PGSSLMODE="require"; psql -h HOST -d pgbouncer -U statsuser -p PORT

Outputnya mirip dengan hal berikut ini:

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.

Jalankan perintah SHOW STATS untuk melihat performa PgBouncer dan mengidentifikasi potensi masalah:

pgbouncer=# SHOW STATS;

Outputnya mirip dengan hal berikut ini:

     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)

Mengonfigurasi akses jaringan ke instance AlloyDB Omni

Untuk memastikan keamanan deployment AlloyDB Omni Anda di Kubernetes, Anda dapat membatasi akses jaringan ke penggabung koneksi PgBouncer dengan menentukan rentang alamat IP tertentu menggunakan notasi CIDR (Classless Inter-Domain Routing).

Notasi CIDR menggabungkan alamat IP dengan panjang awalan, misalnya, blok CIDR 192.168.1.0/24 menentukan 192.168.1.0 untuk alamat dan 24 untuk panjang awalan. Panjang awalan menentukan jumlah bit dalam alamat IP yang digunakan untuk bagian jaringan dan menentukan subnet mask.

Dalam file deklarasi deployment, temukan bagian serviceOptions dan tambahkan atau ubah setelan loadBalancerSourceRanges:

  serviceOptions:
    type: "LoadBalancer"
    loadBalancerSourceRanges:
    - "CIDR_BLOCK"

Ganti CIDR_BLOCK dengan string CIDR yang menentukan rentang alamat IP yang diizinkan untuk koneksi masuk ke layanan LoadBalancer. Setelan loadBalancerSourceRanges memfilter traffic jaringan yang masuk dan mengontrol klien mana yang dapat mengakses instance database Anda.

Untuk memverifikasi bahwa konfigurasi loadBalancerSourceRanges Anda diterapkan dengan benar, gunakan perintah berikut untuk memeriksa alamat IP eksternal yang ditetapkan ke layanan LoadBalancer Anda:

kubectl get svc -n NAMESPACE -w

Ganti NAMESPACE dengan namespace tempat deployment AlloyDB Omni Anda berada.

Outputnya mirip dengan hal berikut ini:

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

Setelah LoadBalancer siap, kolom EXTERNAL_IP akan diisi dengan alamat IP eksternal yang ditetapkan ke layanan LoadBalancer. Koneksi ke IP eksternal ini difilter berdasarkan setelan loadBalancerSourceRanges.

Setelah memverifikasi IP eksternal, uji koneksi dari aplikasi dalam rentang CIDR yang diizinkan untuk memastikan aplikasi tersebut dapat terhubung.

Menonaktifkan penggabung koneksi PgBouncer

Jika Anda perlu menonaktifkan atau mengembalikan PgBouncer connection pooler, ikuti langkah-langkah berikut:

Periksa status penggabung koneksi:

kubectl get deployment fleet-controller-manager --namespace alloydb-omni-system  -o json | jq '.spec.template.spec.containers[0].args'

Perintah ini menampilkan manifes deployment pengontrol utama untuk mengelola fleet AlloyDB Omni. Temukan opsi --enable-pgbouncer di bagian args array containers:

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

Edit konfigurasi deployment pengontrol untuk menonaktifkan penggabung koneksi:

kubectl edit deployment fleet-controller-manager --namespace alloydb-omni-system

Dalam manifes deployment, ubah nilai opsi --enable-pgbouncer dari true menjadi false:
```
...
--enable-pgbouncer=false
```
Simpan file dan keluar dari editor. kubectl akan otomatis menerapkan perubahan.

Langkah berikutnya

Mengelola dan memantau AlloyDB Omni

Menggunakan penggabungan koneksi PgBouncer Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Membuat layanan PgBouncer

Terhubung ke endpoint penggabung koneksi

Menghubungkan dari dalam cluster Kubernetes

Menghubungkan dari luar cluster Kubernetes

Mengonfigurasi setelan PgBouncer

Menyesuaikan deployment PgBouncer

Hapus resource PgBouncer

Melihat log PgBouncer

Memantau performa dan aktivitas PgBouncer

Mengonfigurasi akses jaringan ke instance AlloyDB Omni

Menonaktifkan penggabung koneksi PgBouncer

Langkah berikutnya

Menggunakan penggabungan koneksi PgBouncer