Utilizzare il pooler di connessioni PgBouncer

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

    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