Utiliser le pooleur de connexions PgBouncer

Cette page explique comment activer et utiliser le pooleur de connexions PgBouncer pour AlloyDB Omni à l'aide de l'opérateur Kubernetes AlloyDB Omni.

De nombreuses applications, en particulier les applications Web, ouvrent et ferment fréquemment des connexions de base de données, ce qui peut entraîner une charge importante sur l'instance de base de données. PgBouncer permet de réduire la charge des instances en gérant les connexions plus efficacement. En réutilisant les connexions, PgBouncer réduit le nombre de connexions à l'instance de base de données, ce qui libère des ressources sur l'instance.

Créer un service PgBouncer

L'opérateur Kubernetes AlloyDB Omni vous permet de créer un service PgBouncer dédié pour votre base de données. Vous pouvez ensuite accéder à la base de données via le service PgBouncer pour bénéficier du pool de connexions.

Une définition de ressource personnalisée (CRD) dédiée permet de configurer votre service PgBouncer si nécessaire.

Pour créer un service PgBouncer pour votre base de données, procédez comme suit:

  1. Créez une ressource personnalisée PgBouncer dans votre cluster Kubernetes comme suit:

    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"

    Remplacez les éléments suivants :

    • PGBOUNCER_NAME: nom de votre ressource personnalisée PgBouncer.
    • DB_CLUSTER_NAME: nom de votre cluster de base de données AlloyDB Omni. Il s'agit du même nom de cluster de base de données que vous avez déclaré lors de sa création.
    • POOL_MODE: indique quand une connexion de base de données peut être réutilisée par d'autres clients. Définissez le paramètre sur l'une des valeurs suivantes :
      • session: la connexion à la base de données est remise au pool une fois que le client se déconnecte. Utilisé par défaut.
      • transaction: la connexion à la base de données est remise au pool une fois la transaction terminée.
      • statement: la connexion à la base de données est remise au pool une fois la requête terminée. Les transactions s'étendant sur plusieurs instructions ne sont pas autorisées dans ce mode.
    • IGNORE_STARTUP_PARAMETERS: spécifie les paramètres que PgBouncer n'autorise pas afin qu'ils soient ignorés au démarrage (par exemple, extra_float_digits). Pour en savoir plus, consultez la section Configuration de PgBouncer.
    • DEFAULT_POOL_SIZE: nombre de connexions à la base de données à autoriser par paire utilisateur-base de données (par exemple, 8).
    • MAXIMUM_CLIENT_CONNECTIONS: nombre maximal de connexions client (par exemple, 800).
    • MAXIMUM_DATABASE_CONNECTIONS: nombre maximal de connexions à la base de données (par exemple, 160).

  2. Appliquez le fichier manifeste :

    kubectl apply -f PATH_TO_MANIFEST -n NAMESPACE

    Remplacez PATH_TO_MANIFEST par le chemin d'accès à votre fichier manifeste, par exemple /fleet/config/pgbouncer.yaml.

  3. Pour vérifier que l'objet PgBouncer que vous avez créé est prêt, exécutez la requête suivante:

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

    Remplacez NAMESPACE par le nom de l'espace de noms Kubernetes de votre objet PgBouncer.

    Le résultat ressemble à ce qui suit :

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

Se connecter au point de terminaison du pooleur de connexions

Vous pouvez vous connecter au pooleur de connexions PgBouncer depuis l'intérieur ou l'extérieur d'un cluster Kubernetes.

Se connecter depuis un cluster Kubernetes

Pour vous connecter au point de terminaison du pooleur de connexion à l'aide du client psql, procédez comme suit:

  1. Créez un pod comme suit:

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

  2. Appliquez le fichier manifeste :

    kubectl apply -f PATH_TO_MANIFEST -n NAMESPACE

  3. Connectez-vous à l'application conteneurisée:

    kubectl exec -it postgres -n NAMESPACE -- bash

  4. Vérifiez la connexion SSL au point de terminaison PgBouncer à l'aide du client psql:

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

    Remplacez les éléments suivants :

    • HOST: point de terminaison du pooleur de connexion que vous obtenez à l'aide de la commande kubectl get pgbouncers.alloydbomni.dbadmin.goog -n NAMESPACE. Si PgBouncer n'est pas exposé en tant que service, utilisez son adresse IP.
    • PORT: port sur lequel PgBouncer écoute.

    La fenêtre du terminal affiche le texte de connexion psql se terminant par une invite postgres=#.

Se connecter en dehors d'un cluster Kubernetes

Pour accéder au pooleur de connexions PgBouncer en dehors d'un cluster Kubernetes, définissez le champ type de l'attribut serviceOptions sur LoadBalancer, ce qui crée un service loadbalancer.

  1. Créez une ressource personnalisée PgBouncer dans votre cluster Kubernetes comme suit:

    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. Appliquez le fichier manifeste :

    kubectl apply -f PATH_TO_MANIFEST

  3. Pour vérifier que l'objet PgBouncer que vous avez créé est prêt, exécutez la requête suivante:

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

    Le résultat ressemble à ce qui suit :

    NAME          ENDPOINT       STATE
mypgbouncer   10.138.15.207   Ready

Configurer les paramètres de PgBouncer

Utilisez les paramètres suivants pour configurer PGBouncer:

Paramètre Description Valeur par défaut
pool_mode Indique quand une connexion de base de données peut être réutilisée par d'autres clients.
Les valeurs autorisées sont les suivantes:
  • session: la connexion à la base de données est remise au pool une fois que le client se déconnecte.
  • transaction: la connexion à la base de données est remise au pool une fois la transaction terminée.
  • statement: la connexion à la base de données est renvoyée au pool une fois la requête terminée.
    Les transactions couvrant plusieurs instructions ne sont pas autorisées dans ce mode.
 session
ignore_startup_parameters Spécifie les paramètres que PgBouncer n'autorise pas afin qu'ils soient ignorés au démarrage.
default_pool_size Nombre de connexions à la base de données à autoriser par paire utilisateur-base de données. 20
max_client_conn Nombre maximal de connexions client. 100
max_db_connections Nombre maximal de connexions à la base de données. 0

Personnaliser le déploiement de PgBouncer

AlloyDB Omni utilise des ressources personnalisées pour gérer ses composants. Pour personnaliser le déploiement de PgBouncer dans AlloyDB Omni sur Kubernetes, modifiez la ressource personnalisée PgBouncer comme suit:

  1. Répertoriez les ressources personnalisées PgBouncer:

    kubectl get pgbouncers -n NAMESPACE

    Remplacez NAMESPACE par l'espace de noms dans lequel vous avez déployé AlloyDB Omni.

  2. Pour modifier la ressource, ouvrez le fichier de déclaration de la ressource PgBouncer dans votre éditeur par défaut:

    kubectl edit pgbouncers PGBOUNCER_NAME -n NAMESPACE

  3. Dans le fichier de déclaration, recherchez la section podSpec contenant la configuration et modifiez les champs suivants si nécessaire:

    • resources: cpu et memory définis pour votre conteneur:

      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: chemin d'accès à la balise d'image PgBouncer:

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

    • schedulingconfig: incluez la section nodeaffinity pour contrôler l'emplacement où les pods PgBouncer sont planifiés:

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

      Remplacez les éléments suivants :

      • NODE_AFFINITY_TYPE: définissez le paramètre sur l'une des valeurs suivantes :
        • requiredDuringSchedulingIgnoredDuringExecution: Kubernetes planifie le pod exactement en fonction des règles définies.
        • preferredDuringSchedulingIgnoredDuringExecution: le planificateur Kubernetes tente de trouver un nœud qui répond à la règle définie pour la planification. Toutefois, si aucun nœud de ce type n'est disponible, Kubernetes planifie l'exécution sur un autre nœud du cluster.
      • LABEL_KEY: libellé du nœud pour la clé qui sert d'indicateur d'emplacement et facilite la distribution uniforme des pods dans le cluster (par exemple, nodetype).
      • OPERATOR_VALUE: représente la relation d'une clé avec un ensemble de valeurs. Définissez le paramètre sur l'une des valeurs suivantes :
        • In: le tableau des valeurs ne doit pas être vide.
        • NotIn: le tableau des valeurs ne doit pas être vide.
        • Exists: le tableau des valeurs doit être vide.
        • DoesNotExist: le tableau des valeurs doit être vide.
        • Gt: le tableau de valeurs doit comporter un seul élément, qui est interprété comme un entier.
        • Lt: le tableau de valeurs doit comporter un seul élément, qui est interprété comme un entier.

  4. Une fois les modifications effectuées, enregistrez le fichier de déclaration. L'opérateur Kubernetes AlloyDB Omni applique automatiquement les modifications à votre déploiement PgBouncer.

Supprimer la ressource PgBouncer

Pour supprimer une ressource personnalisée PgBouncer, exécutez la commande suivante:

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

Le résultat ressemble à ce qui suit :

pgbouncer.alloydbomni.dbadmin.goog "mypgbouncer" deleted

Afficher les journaux PgBouncer

Vous pouvez afficher et analyser les journaux de n'importe quelle instance de réplication PgBouncer dans votre déploiement AlloyDB Omni sur Kubernetes comme suit:

  1. Obtenez la liste de tous les pods PgBouncer de votre espace de noms:

    kubectl get pods -n NAMESPACE

    Le résultat ressemble à ce qui suit :

    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. Afficher les journaux d'un pod spécifique:

    kubectl logs -f POD_NAME -n NAMESPACE

    Le résultat ressemble à ce qui suit :

    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

Surveiller les performances et l'activité de PgBouncer

Vous pouvez afficher les métriques de la pool de connexions PgBouncer à l'aide d'un statsuser dédié uniquement pour accéder à la base de données de statistiques internes de PgBouncer. statsuser est utilisé pour l'authentification lors de la connexion à la base de données PgBouncer.

  1. Connectez-vous à AlloyDB Omni en tant que super-utilisateur ou en tant qu'utilisateur disposant du privilège CREATE ROLE à l'aide du client psql:

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

    Le résultat ressemble à ce qui suit :

    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. Créez l'statsuser dans AlloyDB Omni:

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

    Le résultat ressemble à ce qui suit :

    CREATE ROLE
postgres=#

  3. Connectez-vous à la base de données PgBouncer en tant qu'statsuser:

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

    Le résultat ressemble à ce qui suit :

    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. Exécutez la commande SHOW STATS pour afficher les performances de PgBouncer et identifier les problèmes potentiels:

    pgbouncer=# SHOW STATS;

    Le résultat ressemble à ce qui suit :

         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)

Désactiver le pooleur de connexions PgBouncer

Si vous devez désactiver ou annuler le pooleur de connexions PgBouncer, procédez comme suit:

  1. Vérifiez l'état du pooleur de connexions:

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

    Cette commande affiche le fichier manifeste de déploiement du contrôleur principal pour la gestion de la flotte AlloyDB Omni. Recherchez l'option --enable-pgbouncer dans la section args du tableau 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. Modifiez la configuration du déploiement du contrôleur pour désactiver le pooleur de connexions:

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

  3. Dans le fichier manifeste de déploiement, remplacez la valeur de l'option --enable-pgbouncer de true par false:

    ...
--enable-pgbouncer=false

  4. Enregistrez le fichier et quittez l'éditeur. kubectl applique automatiquement la modification.

Étape suivante