Utilizzare il pooler di connessioni PgBouncer

Seleziona una versione della documentazione: 15.7.0

• Attuale (16.8.0)
• 16.8.0
• 16.3.0
• 15.12.0
• 15.7.1
• 15.7.0

Anteprima — AlloyDB Omni

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. Puoi accedere ai dati personali per questa funzionalità, come indicato nell'Addendum per il trattamento dei dati Cloud, fatti salvi gli obblighi e le restrizioni all'interno dell'accordo che regola l'accesso 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 riportate in questa pagina si applicano solo ad AlloyDB Omni per Kubernetes. Non si applica ad AlloyDB Omni per i container.

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

Molte applicazioni, in particolare quelle web, aprono e chiudono spesso le connessioni al database, il che può sovraccaricare notevolmente l'istanza di database. PgBouncer aiuta a ridurre il carico dell'istanza gestendo le connessioni in modo più efficiente. Riutilizzando le connessioni, PgBouncer riduce al minimo il numero di connessioni all'istanza di database, liberando risorse sull'istanza.

Crea un servizio PgBouncer

L'operatore AlloyDB Omni Kubernetes consente di creare un servizio PgBouncer dedicato per il tuo database. A questo punto, puoi accedere al database tramite il servizio PgBouncer per usufruire del pool di 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 tuo cluster Kubernetes nel seguente modo:

   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. È lo stesso nome del cluster di database che hai dichiarato quando l'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 di nuovo nel pool dopo la disconnessione del client. Utilizzato per impostazione predefinita.
     • transaction: la connessione al database viene rilasciata di nuovo nel pool al termine della transazione.
     • statement: la connessione al database viene rilasciata di nuovo nel pool al termine della query. In questa modalità non sono consentite le transazioni che si estendono su più estratti conto.
   • IGNORE_STARTUP_PARAMETERS: specifica i parametri non consentiti da PgBouncer in modo che vengano ignorati all'avvio, ad esempio extra_float_digits. Per saperne di più, consulta la sezione Configurazione di PgBouncer.
   • DEFAULT_POOL_SIZE: il numero di connessioni al database da consentire per ogni 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 questa 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 pool di connessioni

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

Connessione dall'interno di un cluster Kubernetes

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

1. Crea un pod nel seguente modo:

   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 suo indirizzo IP.
   • PORT: la porta su cui PgBouncer è in ascolto.

   La finestra del terminale mostra il testo di accesso psql che termina con un prompt postgres=#.

Connessione dall'esterno di un cluster Kubernetes

Per accedere al pool di 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 tuo cluster Kubernetes nel seguente modo:

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

Configurare 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 di nuovo nel pool dopo la disconnessione del client. transaction: la connessione al database viene rilasciata di nuovo nel pool al termine della transazione. statement: la connessione al database viene rilasciata di nuovo nel pool al termine della query. In questa modalità non sono consentite transazioni che interessano 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 ogni 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 nel seguente modo:

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 per la risorsa PgBouncer nell'editor predefinito:

   kubectl edit pgbouncers PGBOUNCER_NAME -n NAMESPACE

3. Nel file di dichiarazione, individua la sezione podSpec che contiene la configurazione e modifica uno dei seguenti campi in base alle esigenze:

   • resources: il cpu e il memory definiti per il container:

     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 dell'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 nodo diverso nel 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 solo elemento, che viene interpretato come un numero intero.
       • Lt: l'array di valori deve avere un solo elemento, che viene interpretato come un numero intero.

4. Dopo aver apportato le modifiche, salva il file di 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 questo 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 deployment di AlloyDB Omni su Kubernetes nel seguente modo:

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 PgBouncer utilizzando solo un statsuser dedicato per accedere al database delle statistiche interne di PgBouncer. statsuser viene utilizzato per l'autenticazione durante la connessione al database PgBouncer.

1. Connettiti ad AlloyDB Omni come superuser o come 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 di connessioni PgBouncer

Se devi disattivare o eseguire il rollback del pool di connessioni PgBouncer:

1. Controlla lo stato del pool di 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 della flotta 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 di connessioni:

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

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