Utiliser le pooleur de connexions PgBouncer

Sélectionnez une version de la documentation : 15.12.0

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

Les informations de cette page ne s'appliquent qu'à AlloyDB Omni pour Kubernetes. Elle ne s'applique pas à AlloyDB Omni pour les conteneurs.

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

De nombreuses applications, en particulier les applications Web, ouvrent et ferment fréquemment des connexions de base de données, ce qui peut exercer 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 minimise 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 regroupement de connexions.

Une définition de ressource personnalisée (CRD) dédiée permet de configurer votre service PgBouncer selon vos besoins.

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/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"

   Remplacez les éléments suivants :

   • PGBOUNCER_NAME : nom de votre ressource personnalisée PgBouncer.
   • DB_CLUSTER_NAME : nom de votre cluster de bases 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 à une 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 dans le pool après la déconnexion du client. Utilisé par défaut.
     • transaction : la connexion à la base de données est libérée et renvoyée au pool une fois la transaction terminée.
     • statement : la connexion à la base de données est libérée et renvoyée 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 pour 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 regroupement de connexions

Vous pouvez vous connecter au pool de connexions PgBouncer à 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 pooler de connexions à 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 pooler 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 qui se termine par une invite postgres=#.

Se connecter depuis l'extérieur d'un cluster Kubernetes

Pour accéder au pooler de connexion PgBouncer depuis l'extérieur 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/g-pgbouncer:1.4.0"
   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 PgBouncer

Utilisez les paramètres suivants pour configurer les paramètres PGBouncer :

Paramètre	Description	Valeur par défaut
pool_mode	Indique quand une connexion à une 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 dans le pool après la déconnexion du client. transaction : la connexion à la base de données est libérée et renvoyée au pool une fois la transaction terminée. statement : la connexion à la base de données est remise dans le 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 autorisées 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 PgBouncer dans votre 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 l'un des 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 au tag d'image PgBouncer :

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

   • schedulingconfig : incluez la section nodeaffinity pour contrôler l'emplacement de planification des pods PgBouncer :

     ...
       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 en fonction des règles définies.
       • preferredDuringSchedulingIgnoredDuringExecution : le programmateur Kubernetes tente de trouver un nœud qui répond à la règle de programmation définie. Toutefois, si aucun nœud de ce type n'est disponible, Kubernetes planifie le pod 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 répartition uniforme des pods dans le cluster (par exemple, nodetype).
     • OPERATOR_VALUE : représente la relation entre une clé et 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 répliquée 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. Affichez les journaux d'un pod spécifique :

   kubectl logs -f POD_NAME -n NAMESPACE

   Remarque : Pour diffuser en continu les journaux en temps réel, utilisez l'option -f.

   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 ne pouvez afficher les métriques du pool de connexions PgBouncer qu'à l'aide d'un statsuser dédié pour accéder à la base de données des statistiques internes de PgBouncer. statsuser est utilisé pour l'authentification lors de la connexion à la base de données PgBouncer.

1. Connectez-vous à votre AlloyDB Omni en tant que super-utilisateur ou 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 le statsuser dans votre 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 que 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)
   

Configurer l'accès réseau à votre instance AlloyDB Omni

Pour assurer la sécurité de votre déploiement AlloyDB Omni sur Kubernetes, vous pouvez limiter l'accès au réseau au pool de connexion PgBouncer en définissant des plages d'adresses IP spécifiques à l'aide de la notation CIDR (Classless Inter-Domain Routing).

La notation CIDR combine une adresse IP avec une longueur de préfixe. Par exemple, le bloc CIDR 192.168.1.0/24 spécifie 192.168.1.0 pour l'adresse et 24 pour la longueur du préfixe. La longueur du préfixe spécifie le nombre de bits de l'adresse IP utilisés pour la partie réseau et définit le masque de sous-réseau.

Dans le fichier de déclaration de votre déploiement, recherchez la section serviceOptions et ajoutez ou modifiez le paramètre loadBalancerSourceRanges :

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

Remplacez CIDR_BLOCK par une chaîne CIDR qui spécifie les plages d'adresses IP autorisées pour les connexions entrantes au service LoadBalancer. Le paramètre loadBalancerSourceRanges filtre le trafic réseau entrant et contrôle les clients qui peuvent accéder à votre instance de base de données.

Remarque : Spécifiez les plages d'adresses IP les plus restreintes possibles qui permettent à votre instance de base de données de fonctionner correctement, en lui permettant de recevoir des connexions, d'exécuter des requêtes et d'effectuer d'autres opérations de base de données requises.

Pour vérifier que votre configuration loadBalancerSourceRanges est correctement appliquée, utilisez la commande suivante pour vérifier l'adresse IP externe attribuée à votre service LoadBalancer :

kubectl get svc -n NAMESPACE -w

Remplacez NAMESPACE par l'espace de noms où se trouve votre déploiement AlloyDB Omni.

Le résultat ressemble à ce qui suit :

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

Remarque : Le port est codé en dur sur 6432 pour le pooler de connexion PgBouncer. L'attribut loadBalancerSourceRanges vous permet de choisir une adresse IP uniquement dans la plage d'adresses que vous spécifiez dans CIDR_BLOCK.

Une fois le LoadBalancer prêt, la colonne EXTERNAL_IP est renseignée avec l'adresse IP externe attribuée au service LoadBalancer. Les connexions à cette adresse IP externe sont filtrées en fonction du paramètre loadBalancerSourceRanges.

Après avoir vérifié l'adresse IP externe, testez les connexions depuis les applications dans vos plages CIDR autorisées pour vous assurer qu'elles peuvent se connecter.

Désactiver le pooler de connexion PgBouncer

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

1. Vérifiez l'état du pooler de connexion :

   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 gérer le parc 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 pooler de connexion :

   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.

Étapes suivantes

• Gérer et surveiller AlloyDB Omni