Utilizzare il pooler di connessioni PgBouncer

Anteprima - AlloyDB Omni

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici dei servizi. L'utente può trattare i dati personali relativi a questa funzionalità come descritto nell'Addendum per il trattamento dei dati Cloud, in conformità agli obblighi e alle limitazioni descritti nel contratto in base al quale accede a Google Cloud. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Le informazioni in questa pagina si applicano solo ai deployment di AlloyDB Omni basati su Kubernetes. Non si applica ai deployment su un singolo server di AlloyDB Omni.

Questa pagina descrive come attivare e utilizzare il pooler di connessione PgBouncer per AlloyDB Omni utilizzando l'operatore AlloyDB Omni Kubernetes.

Molte applicazioni, in particolare quelle web, aprono e chiudono di frequente le connessioni al database, il che può comportare un carico significativo sull'istanza di database. PgBouncer contribuisce a ridurre il carico delle istanze gestendo le connessioni in modo più efficiente. Riutilizzando le connessioni, PgBouncer riduce al minimo il numero di connessioni all'istanza di database, liberando risorse nell'istanza.

Crea un servizio PgBouncer

L'operatore AlloyDB Omni Kubernetes ti consente di creare un servizio PgBouncer dedicato per il tuo database. Puoi quindi accedere al database tramite il servizio PgBouncer per usufruire del pooling delle connessioni.

Esiste una definizione di risorsa personalizzata (CRD) dedicata per configurare il servizio PgBouncer in base alle esigenze.

Per creare un servizio PgBouncer per il tuo database:

1. Crea una risorsa personalizzata PgBouncer nel cluster Kubernetes come segue:

   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/pgbouncer:1.23.1"
     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"

   Sostituisci quanto segue:

   • PGBOUNCER_NAME: il nome della risorsa personalizzata PgBouncer.
   • DB_CLUSTER_NAME: il nome del cluster di database AlloyDB Omni. Si tratta dello stesso nome del cluster di database che hai dichiarato quando lo hai creato.
   • POOL_MODE: specifica quando una connessione al database può essere riutilizzata da altri client. Imposta il parametro su uno dei seguenti valori:
     • session: la connessione al database viene rilasciata nuovamente al pool dopo la disconnessione del client. Utilizzato per impostazione predefinita.
     • transaction: la connessione al database viene rilasciata nuovamente al pool al termine della transazione.
     • statement: la connessione al database viene rilasciata nuovamente al pool al termine della query. Le transazioni che abbracciano più istruzioni non sono consentite in questa modalità.
   • IGNORE_STARTUP_PARAMETERS: specifica i parametri non consentiti da PgBouncer in modo che vengano ignorati durante l'avvio, ad esempio extra_float_digits. Per ulteriori informazioni, consulta la configurazione di PgBouncer.
   • DEFAULT_POOL_SIZE: il numero di connessioni al database da consentire per coppia utente-database, ad esempio 8.
   • MAXIMUM_CLIENT_CONNECTIONS: il numero massimo di connessioni client, ad esempio 800.
   • MAXIMUM_DATABASE_CONNECTIONS: il numero massimo di connessioni al database, ad esempio 160.

2. Applica il manifest:

   kubectl apply -f PATH_TO_MANIFEST -n NAMESPACE

   Sostituisci PATH_TO_MANIFEST con il percorso del file manifest, ad esempio /fleet/config/pgbouncer.yaml.

3. Per verificare che l'oggetto PgBouncer che hai creato sia pronto, esegui la seguente query:

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

   Sostituisci NAMESPACE con il nome dello spazio dei nomi Kubernetes per l'oggetto PgBouncer.

   L'output è simile al seguente:

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

Connettiti all'endpoint del pooler di connessioni

Puoi connetterti al pooler di connessioni PgBouncer dall'interno o dall'esterno di un cluster Kubernetes.

Connettiti da un cluster Kubernetes

Per connetterti all'endpoint del pooler delle connessioni utilizzando il client psql:

1. Crea un pod come segue:

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

2. Applica il manifest:

   kubectl apply -f PATH_TO_MANIFEST -n NAMESPACE
   

3. Connettiti all'applicazione containerizzata:

   kubectl exec -it postgres -n NAMESPACE -- bash
   

4. Verifica la connessione SSL all'endpoint PgBouncer utilizzando il client psql:

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

   Sostituisci quanto segue:

   • HOST: l'endpoint del pooler di connessioni che ottieni utilizzando il comando kubectl get pgbouncers.alloydbomni.dbadmin.goog -n NAMESPACE. Se PgBouncer non è esposto come servizio, utilizza il relativo indirizzo IP.
   • PORT: la porta su cui PgBouncer è in ascolto.

   Nella finestra del terminale viene visualizzato il testo di accesso psql che termina con un prompt postgres=#.

Connettiti dall'esterno di un cluster Kubernetes

Per accedere al pooler delle connessioni PgBouncer dall'esterno di un cluster Kubernetes, imposta il campo type nell'attributo serviceOptions su LoadBalancer, che crea un servizio loadbalancer.

1. Crea una risorsa personalizzata PgBouncer nel cluster Kubernetes come segue:

   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/pgbouncer:1.23.1"
   serviceOptions:
     type: "LoadBalancer"

2. Applica il manifest:

   kubectl apply -f PATH_TO_MANIFEST

3. Per verificare che l'oggetto PgBouncer che hai creato sia pronto, esegui la seguente query:

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

   L'output è simile al seguente:

   NAME          ENDPOINT       STATE
   mypgbouncer   10.138.15.207   Ready
   

Configura le impostazioni di PgBouncer

Utilizza i seguenti parametri per configurare le impostazioni di PGBouncer:

Parametro	Descrizione	Valore predefinito
pool_mode	Specifica quando una connessione al database può essere riutilizzata da altri client. I valori consentiti sono i seguenti: session: la connessione al database viene rilasciata nuovamente al pool dopo la disconnessione del client. transaction: la connessione al database viene rilasciata nuovamente al pool al termine della transazione. statement: la connessione al database viene rilasciata nuovamente al pool al termine della query. In questa modalità non sono consentite transazioni che abbracciano più istruzioni.	session
ignore_startup_parameters	Specifica i parametri non consentiti da PgBouncer in modo che vengano ignorati durante l'avvio.
default_pool_size	Il numero di connessioni al database da consentire per coppia utente-database.	20
max_client_conn	Il numero massimo di connessioni client.	100
max_db_connections	Il numero massimo di connessioni al database.	0

Personalizzare il deployment di PgBouncer

AlloyDB Omni utilizza risorse personalizzate per gestire i suoi componenti. Per personalizzare il deployment di PgBouncer in AlloyDB Omni su Kubernetes, modifica la risorsa personalizzata PgBouncer come segue:

1. Elenca le risorse personalizzate PgBouncer:

   kubectl get pgbouncers -n NAMESPACE

   Sostituisci NAMESPACE con lo spazio dei nomi in cui hai eseguito il deployment di AlloyDB Omni.

2. Per modificare la risorsa, apri il file di dichiarazione della risorsa PgBouncer nel tuo editor predefinito:

   kubectl edit pgbouncers PGBOUNCER_NAME -n NAMESPACE

3. Nel file di dichiarazione, individua la sezione podSpec contenente la configurazione e modifica uno dei seguenti campi, se necessario:

   • resources: cpu e memory definiti per il contenitore:

     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: il percorso del tag immagine PgBouncer:

     ...
       podSpec:
         resources:
           memory: 1Gi
           cpu: 1
         image: IMAGE
     ...
     

   • schedulingconfig: includi la sezione nodeaffinity per controllare dove sono pianificati i pod PgBouncer:

     ...
       podSpec:
         resources:
           memory: 1Gi
           cpu: 1
         image: IMAGE
         schedulingconfig:
           nodeaffinity:
             NODE_AFFINITY_TYPE:
               nodeSelectorTerms:
               - matchExpressions:
                 - key: LABEL_KEY
                   operator: OPERATOR_VALUE
                   values:
                   - pgbouncer
     ...
     

     Sostituisci quanto segue:

     • NODE_AFFINITY_TYPE: imposta il parametro su uno dei seguenti valori:
       • requiredDuringSchedulingIgnoredDuringExecution: Kubernetes pianifica il pod in base esattamente alle regole definite.
       • preferredDuringSchedulingIgnoredDuringExecution: lo scheduler Kubernetes tenta di trovare un nodo che soddisfi la regola definita per la pianificazione. Tuttavia, se non esiste un nodo di questo tipo, Kubernetes esegue la pianificazione su un altro nodo del cluster.
     • LABEL_KEY: l'etichetta del nodo per la chiave che funge da indicatore di posizione e facilita la distribuzione uniforme dei pod nel cluster, ad esempio nodetype.
     • OPERATOR_VALUE: rappresenta la relazione di una chiave con un insieme di valori. Imposta il parametro su uno dei seguenti valori:
       • In: l'array di valori non deve essere vuoto.
       • NotIn: l'array di valori non deve essere vuoto.
       • Exists: l'array di valori deve essere vuoto.
       • DoesNotExist: l'array di valori deve essere vuoto.
       • Gt: l'array di valori deve avere un singolo elemento, che viene interpretato come un numero intero.
       • Lt: l'array di valori deve avere un singolo elemento, che viene interpretato come un numero intero.

4. Dopo aver apportato le modifiche, salva il file della dichiarazione. L'operatore AlloyDB Omni Kubernetes applica automaticamente le modifiche al deployment di PgBouncer.

Elimina la risorsa PgBouncer

Per eliminare una risorsa personalizzata PgBouncer, esegui il seguente comando:

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

L'output è simile al seguente:

pgbouncer.alloydbomni.dbadmin.goog "mypgbouncer" deleted

Visualizzare i log di PgBouncer

Puoi visualizzare e analizzare i log di qualsiasi istanza di replica PgBouncer nel tuo deployment di AlloyDB Omni su Kubernetes come segue:

1. Recupera un elenco di tutti i pod PgBouncer nel tuo spazio dei nomi:

   kubectl get pods -n NAMESPACE

   L'output è simile al seguente:

   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
   

2. Visualizza i log di un pod specifico:

   kubectl logs -f POD_NAME -n NAMESPACE

   Nota: per eseguire lo streaming continuo dei log in tempo reale, utilizza l'opzione -f.

   L'output è simile al seguente:

   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
   

Monitorare il rendimento e l'attività di PgBouncer

Puoi visualizzare le metriche del pool di connessioni di PgBouncer utilizzando solo un statsuser dedicato per accedere al database delle statistiche interne di PgBouncer. statsuser viene utilizzato per l'autenticazione quando ci si connette al database PgBouncer.

1. Connettiti ad AlloyDB Omni come superutente o utente con il privilegio CREATE ROLE utilizzando il client psql:

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

   L'output è simile al seguente:

   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.
   

2. Crea il statsuser in AlloyDB Omni:

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

   L'output è simile al seguente:

   CREATE ROLE
   postgres=#
   

3. Connettiti al database PgBouncer come statsuser:

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

   L'output è simile al seguente:

   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.
   

4. Esegui il comando SHOW STATS per visualizzare il rendimento di PgBouncer e identificare potenziali problemi:

   pgbouncer=# SHOW STATS;
   

   L'output è simile al seguente:

        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)
   

Disattiva il pooler delle connessioni PgBouncer

Se devi disattivare o eseguire il rollback del pooler delle connessioni PgBouncer:

1. Controlla lo stato del pooler delle connessioni:

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

   Questo comando mostra il manifest di deployment del controller principale per la gestione del parco AlloyDB Omni. Trova l'opzione --enable-pgbouncer nella sezione args dell'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
   

2. Modifica la configurazione del deployment del controller per disattivare il pooler delle connessioni:

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

3. Nel file manifest di deployment, modifica il valore dell'opzione --enable-pgbouncer da true a false:

   ...
   --enable-pgbouncer=false
   

4. Salva il file ed esci dall'editor. kubectl applica automaticamente la modifica.

Passaggi successivi

• Gestire e monitorare AlloyDB Omni