Usar el gestor de conexiones PgBouncer

Selecciona una versión de la documentación: 15.7.1

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

La información de esta página solo se aplica a AlloyDB Omni para Kubernetes. No se aplica a AlloyDB Omni para contenedores.

En esta página se describe cómo habilitar y usar el agrupador de conexiones PgBouncer para AlloyDB Omni mediante el operador AlloyDB Omni Kubernetes.

Muchas aplicaciones, especialmente las aplicaciones web, abren y cierran conexiones de bases de datos con frecuencia, lo que puede suponer una carga significativa para la instancia de la base de datos. PgBouncer ayuda a reducir la carga de las instancias gestionando las conexiones de forma más eficiente. Al reutilizar las conexiones, PgBouncer minimiza el número de conexiones a la instancia de base de datos, lo que libera recursos en la instancia.

Crear un servicio PgBouncer

El operador AlloyDB Omni Kubernetes te permite crear un servicio PgBouncer específico para tu base de datos. Después, puedes acceder a la base de datos a través del servicio PgBouncer para aprovechar las ventajas de la agrupación de conexiones.

Hay una definición de recurso personalizado (CRD) específica para configurar el servicio PgBouncer según sea necesario.

Para crear un servicio PgBouncer para tu base de datos, sigue estos pasos:

1. Crea un PgBouncer recurso personalizado en tu clúster de Kubernetes de la siguiente manera:

   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"

   Haz los cambios siguientes:

   • PGBOUNCER_NAME: el nombre de tu recurso personalizado de PgBouncer.
   • DB_CLUSTER_NAME: el nombre de tu clúster de base de datos AlloyDB Omni. Es el mismo nombre de clúster de base de datos que declaraste cuando lo creaste.
   • POOL_MODE: especifica cuándo pueden reutilizar otros clientes una conexión de base de datos. Asigne al parámetro uno de los siguientes valores:
     • session: la conexión de la base de datos se devuelve al grupo después de que el cliente se desconecte. Se usa de forma predeterminada.
     • transaction: la conexión de la base de datos se devuelve al grupo después de que finalice la transacción.
     • statement: la conexión de la base de datos se devuelve al grupo después de que finalice la consulta. En este modo no se permiten las transacciones que abarcan varias instrucciones.
   • IGNORE_STARTUP_PARAMETERS: especifica los parámetros que PgBouncer no permite para que se ignoren durante el inicio. Por ejemplo, extra_float_digits. Para obtener más información, consulta Configuración de PgBouncer.
   • DEFAULT_POOL_SIZE: el número de conexiones de base de datos que se permiten por cada par de usuario y base de datos. Por ejemplo, 8.
   • MAXIMUM_CLIENT_CONNECTIONS: el número máximo de conexiones de cliente, por ejemplo, 800.
   • MAXIMUM_DATABASE_CONNECTIONS: el número máximo de conexiones de base de datos (por ejemplo, 160).

2. Aplica el archivo de manifiesto:

   kubectl apply -f PATH_TO_MANIFEST -n NAMESPACE

   Sustituye PATH_TO_MANIFEST por la ruta a tu archivo de manifiesto (por ejemplo, /fleet/config/pgbouncer.yaml).

3. Para verificar que el objeto PgBouncer que has creado está listo, ejecuta la siguiente consulta:

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

   Sustituye NAMESPACE por el nombre del espacio de nombres de Kubernetes de tu objeto PgBouncer.

   El resultado debería ser similar al siguiente:

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

Conectarse al endpoint del gestor de conexiones

Puedes conectarte al gestor de conexiones PgBouncer dentro o fuera de un clúster de Kubernetes.

Conectarse desde un clúster de Kubernetes

Para conectarte al endpoint del gestor de conexiones mediante el cliente psql, sigue estos pasos:

1. Crea un pod de la siguiente manera:

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

2. Aplica el archivo de manifiesto:

   kubectl apply -f PATH_TO_MANIFEST -n NAMESPACE
   

3. Conéctate a la aplicación en contenedor:

   kubectl exec -it postgres -n NAMESPACE -- bash
   

4. Verifica la conexión SSL con el endpoint de PgBouncer mediante el cliente psql:

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

   Haz los cambios siguientes:

   • HOST: el endpoint del agrupador de conexiones que obtienes con el comando kubectl get pgbouncers.alloydbomni.dbadmin.goog -n NAMESPACE. Si PgBouncer no se expone como servicio, usa su dirección IP.
   • PORT: puerto en el que escucha PgBouncer.

   En la ventana de la terminal se muestra el texto de inicio de sesión psql, que termina con un mensaje postgres=#.

Conectarse desde fuera de un clúster de Kubernetes

Para acceder al gestor de conexiones PgBouncer desde fuera de un clúster de Kubernetes, asigna el valor type al campo type del atributo serviceOptions, lo que crea un servicio loadbalancer.LoadBalancer

1. Crea un PgBouncer recurso personalizado en tu clúster de Kubernetes de la siguiente manera:

   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. Aplica el archivo de manifiesto:

   kubectl apply -f PATH_TO_MANIFEST

3. Para verificar que el objeto PgBouncer que has creado está listo, ejecuta la siguiente consulta:

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

   El resultado debería ser similar al siguiente:

   NAME          ENDPOINT       STATE
   mypgbouncer   10.138.15.207   Ready
   

Configurar los ajustes de PgBouncer

Usa los siguientes parámetros para configurar los ajustes de PGBouncer:

Parámetro	Descripción	Valor predeterminado
pool_mode	Especifica cuándo pueden reutilizar otros clientes una conexión de base de datos. Los valores permitidos son los siguientes: session: la conexión de la base de datos se devuelve al grupo después de que el cliente se desconecte. transaction: la conexión de la base de datos se devuelve al grupo después de que finalice la transacción. statement: la conexión de la base de datos se devuelve al grupo después de que finalice la consulta. En este modo, no se permiten las transacciones que abarcan varias instrucciones.	session
ignore_startup_parameters	Especifica los parámetros que no permite PgBouncer para que se ignoren durante el inicio.
default_pool_size	Número de conexiones de base de datos que se permiten por cada par de usuario y base de datos.	20
max_client_conn	Número máximo de conexiones de cliente.	100
max_db_connections	Número máximo de conexiones de base de datos.	0

Personalizar la implementación de PgBouncer

AlloyDB Omni usa recursos personalizados para gestionar sus componentes. Para personalizar la implementación de PgBouncer en tu AlloyDB Omni en Kubernetes, modifica el recurso personalizado PgBouncer de la siguiente manera:

1. Lista los PgBouncerrecursos personalizados:

   kubectl get pgbouncers -n NAMESPACE

   Sustituye NAMESPACE por el espacio de nombres en el que has desplegado AlloyDB Omni.

2. Para modificar el recurso, abre el archivo de declaración del recurso PgBouncer en tu editor predeterminado:

   kubectl edit pgbouncers PGBOUNCER_NAME -n NAMESPACE

3. En el archivo de declaración, busque la sección podSpec que contiene la configuración y modifique cualquiera de los siguientes campos según sea necesario:

   • resources: el cpu y el memory definidos en el contenedor:

     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: la ruta a la etiqueta de imagen de PgBouncer:

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

   • schedulingconfig: incluye la sección nodeaffinity para controlar dónde se programan los pods de PgBouncer:

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

     Haz los cambios siguientes:

     • NODE_AFFINITY_TYPE: asigna al parámetro uno de los siguientes valores:
       • requiredDuringSchedulingIgnoredDuringExecution: Kubernetes programa el pod exactamente según las reglas definidas.
       • preferredDuringSchedulingIgnoredDuringExecution: el programador de Kubernetes intenta encontrar un nodo que cumpla la regla definida para la programación. Sin embargo, si no hay ningún nodo de este tipo, Kubernetes programa el pod en otro nodo del clúster.
     • LABEL_KEY: etiqueta del nodo para la clave que sirve como indicador de ubicación y facilita la distribución uniforme de los pods en el clúster. Por ejemplo, nodetype.
     • OPERATOR_VALUE: representa la relación de una clave con un conjunto de valores. Asigne al parámetro uno de los siguientes valores:
       • In: la matriz de valores no puede estar vacía.
       • NotIn: la matriz de valores no puede estar vacía.
       • Exists: el array de valores debe estar vacío.
       • DoesNotExist: el array de valores debe estar vacío.
       • Gt: el array de valores debe tener un solo elemento, que se interpreta como un número entero.
       • Lt: el array de valores debe tener un solo elemento, que se interpreta como un número entero.

4. Después de hacer los cambios, guarde el archivo de declaración. El operador de AlloyDB Omni de Kubernetes aplica automáticamente los cambios a tu despliegue de PgBouncer.

Elimina el recurso PgBouncer.

Para eliminar un recurso personalizado de PgBouncer, ejecuta el siguiente comando:

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

El resultado debería ser similar al siguiente:

pgbouncer.alloydbomni.dbadmin.goog "mypgbouncer" deleted

Ver los registros de PgBouncer

Puedes ver y analizar los registros de cualquier instancia de réplica de PgBouncer en tu implementación de AlloyDB Omni en Kubernetes de la siguiente manera:

1. Obtén una lista de todos los pods de PgBouncer de tu espacio de nombres:

   kubectl get pods -n NAMESPACE

   El resultado debería ser similar al siguiente:

   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. Ver los registros de un pod concreto:

   kubectl logs -f POD_NAME -n NAMESPACE

   Nota: Para transmitir registros de forma continua en tiempo real, usa la opción -f.

   El resultado debería ser similar al siguiente:

   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
   

Monitorizar el rendimiento y la actividad de PgBouncer

Solo puedes ver las métricas del grupo de conexiones de PgBouncer usando un statsuser específico para acceder a la base de datos de estadísticas internas de PgBouncer. El statsuser se usa para la autenticación al conectarse a la base de datos PgBouncer.

1. Conéctate a tu instancia de AlloyDB Omni como superusuario o como usuario con el privilegio CREATE ROLE mediante el cliente psql:

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

   El resultado debería ser similar al siguiente:

   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 el statsuser en tu AlloyDB Omni:

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

   El resultado debería ser similar al siguiente:

   CREATE ROLE
   postgres=#
   

3. Conéctate a la base de datos de PgBouncer como statsuser:

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

   El resultado debería ser similar al siguiente:

   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. Ejecuta el comando SHOW STATS para ver el rendimiento de PgBouncer e identificar posibles problemas:

   pgbouncer=# SHOW STATS;
   

   El resultado debería ser similar al siguiente:

        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)
   

Configurar el acceso de red a tu instancia de AlloyDB Omni

Para garantizar la seguridad de tu implementación de AlloyDB Omni en Kubernetes, puedes limitar el acceso a la red del gestor de conexiones PgBouncer definiendo intervalos de direcciones IP específicos mediante la notación CIDR (enrutamiento entre dominios sin clases).

La notación CIDR combina una dirección IP con una longitud de prefijo. Por ejemplo, el bloque CIDR 192.168.1.0/24 especifica 192.168.1.0 para la dirección y 24 para la longitud del prefijo. La longitud del prefijo especifica el número de bits de la dirección IP que se utilizan para la parte de la red y define la máscara de subred.

En el archivo de declaración de tu implementación, busca la sección serviceOptions y añade o modifica el ajuste loadBalancerSourceRanges:

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

Sustituye CIDR_BLOCK por una cadena CIDR que especifique los intervalos de direcciones IP permitidos para las conexiones entrantes al servicio LoadBalancer. El ajuste loadBalancerSourceRanges filtra el tráfico de red entrante y controla qué clientes pueden acceder a tu instancia de base de datos.

Nota: Especifica los intervalos de IP más acotados posibles que permitan que tu instancia de base de datos funcione correctamente, de modo que pueda recibir conexiones, ejecutar consultas y realizar otras operaciones de base de datos necesarias.

Para verificar que la configuración de loadBalancerSourceRanges se ha aplicado correctamente, usa el siguiente comando para comprobar la dirección IP externa asignada a tu servicio LoadBalancer:

kubectl get svc -n NAMESPACE -w

Sustituye NAMESPACE por el espacio de nombres en el que se encuentra tu implementación de AlloyDB Omni.

El resultado debería ser similar al siguiente:

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

Nota: El puerto se ha codificado como 6432 para el gestor de conexiones PgBouncer. El atributo loadBalancerSourceRanges te permite elegir una dirección IP solo del intervalo de direcciones que especifiques en CIDR_BLOCK.

Cuando el LoadBalancer esté listo, la columna EXTERNAL_IP se rellenará con la dirección IP externa asignada al servicio LoadBalancer. Las conexiones a esta IP externa se filtran según el ajuste loadBalancerSourceRanges.

Después de verificar la IP externa, prueba las conexiones de las aplicaciones que estén dentro de los intervalos CIDR permitidos para asegurarte de que se pueden conectar.

Inhabilitar el agrupador de conexiones PgBouncer

Si necesitas desactivar o revertir el PgBouncer, sigue estos pasos:

1. Comprueba el estado del agrupador de conexiones:

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

   Este comando muestra el manifiesto de implementación del controlador principal para gestionar la flota de AlloyDB Omni. Busca la opción --enable-pgbouncer en la sección args de la matriz 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. Edita la configuración de la implementación del controlador para inhabilitar el agrupador de conexiones:

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

3. En el archivo de manifiesto de la implementación, cambia el valor de la opción --enable-pgbouncer de true a false:

   ...
   --enable-pgbouncer=false
   

4. Guarda el archivo y cierra el editor. kubectl aplica el cambio automáticamente.

Siguientes pasos

• Gestionar y monitorizar AlloyDB Omni