En esta página, se describe cómo habilitar y usar el agrupador de conexiones PgBouncer para AlloyDB Omni con el operador de Kubernetes de AlloyDB Omni.
Muchas aplicaciones, en especial las aplicaciones web, abren y cierran conexiones de bases de datos con frecuencia, lo que puede generar una carga significativa en la instancia de la base de datos. PgBouncer ayuda a reducir la carga de la instancia, ya que administra las conexiones de manera más eficiente. Al reutilizar las conexiones, PgBouncer minimiza la cantidad de conexiones a la instancia de base de datos, lo que libera recursos en la instancia.
Crea un servicio de PgBouncer
El operador de Kubernetes de AlloyDB Omni te permite crear un servicio de PgBouncer dedicado para tu base de datos. Luego, puedes acceder a la base de datos a través del servicio de PgBouncer para aprovechar el agrupamiento de conexiones.
Existe una definición de recurso personalizado (CRD) dedicada para configurar tu servicio de PgBouncer según sea necesario.
Para crear un servicio de PgBouncer para tu base de datos, sigue estos pasos:
Crea un recurso personalizado
PgBouncer
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"
Reemplaza lo siguiente:
PGBOUNCER_NAME
: Es el nombre de tu recurso personalizado de PgBouncer.DB_CLUSTER_NAME
: Es el nombre de tu clúster de base de datos de AlloyDB Omni. Es el mismo nombre del clúster de la base de datos que declaraste cuando lo creaste.POOL_MODE
: Especifica cuándo otros clientes pueden reutilizar una conexión de base de datos. Establece el parámetro en uno de los siguientes valores:session
: La conexión de la base de datos se libera al grupo después de que se desconecta el cliente. Se usa de forma predeterminada.transaction
: La conexión de la base de datos se libera y vuelve al grupo después de que finaliza la transacción.statement
: La conexión de la base de datos se libera y vuelve al grupo después de que finaliza la consulta. En este modo, no se permiten las transacciones que abarcan varias declaraciones.
IGNORE_STARTUP_PARAMETERS
: Especifica 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
: Es la cantidad de conexiones de bases de datos que se permiten por par usuario-base de datos; por ejemplo,8
.MAXIMUM_CLIENT_CONNECTIONS
: Es la cantidad máxima de conexiones de clientes, por ejemplo,800
.MAXIMUM_DATABASE_CONNECTIONS
: Es la cantidad máxima de conexiones de base de datos, por ejemplo,160
.
Aplica el manifiesto
kubectl apply -f PATH_TO_MANIFEST -n NAMESPACE
Reemplaza PATH_TO_MANIFEST por la ruta de acceso a tu archivo de manifiesto, por ejemplo,
/fleet/config/pgbouncer.yaml
.Para verificar que el objeto PgBouncer que creaste esté listo, ejecuta la siguiente consulta:
kubectl get pgbouncers.alloydbomni.dbadmin.goog PGBOUNCER_NAME -n NAMESPACE -w
Reemplaza
NAMESPACE
por el nombre del espacio de nombres de Kubernetes para tu objeto PgBouncer.El resultado es similar a este:
NAMESPACE NAME ENDPOINT STATE dbv2 mypgbouncer dbv2 mypgbouncer dbv2 mypgbouncer dbv2 mypgbouncer WaitingForDeploymentReady dbv2 mypgbouncer Acquiring IP dbv2 mypgbouncer 10.138.15.231 Ready
Conéctate al extremo del agrupador de conexiones
Puedes conectarte al agrupador de conexiones de PgBouncer desde dentro o fuera de un clúster de Kubernetes.
Conéctate desde un clúster de Kubernetes
Para conectarte al extremo del agrupador de conexiones con el cliente psql
, sigue estos pasos:
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
Aplica el manifiesto
kubectl apply -f PATH_TO_MANIFEST -n NAMESPACE
Conéctate a la aplicación alojada en el contenedor:
kubectl exec -it postgres -n NAMESPACE -- bash
Verifica la conexión SSL al extremo de PgBouncer con el cliente
psql
:export PGSSLMODE="require"; psql -h HOST -d postgres -U postgres -p PORT
Reemplaza lo siguiente:
HOST
: Es el extremo del agrupador de conexiones que obtienes con el comandokubectl get pgbouncers.alloydbomni.dbadmin.goog -n NAMESPACE
. Si PgBouncer no se expone como un servicio, usa su dirección IP.PORT
: Es el puerto en el que escucha PgBouncer.
En la ventana de la terminal, se muestra el texto de acceso
psql
que termina con un mensajepostgres=#
.
Conéctate desde fuera de un clúster de Kubernetes
Para acceder al agrupador de conexiones de PgBouncer desde fuera de un clúster de Kubernetes, configura el campo type
en el atributo serviceOptions
como LoadBalancer
, lo que crea un servicio loadbalancer
.
Crea un recurso personalizado
PgBouncer
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"
Aplica el manifiesto
kubectl apply -f PATH_TO_MANIFEST
Para verificar que el objeto PgBouncer que creaste esté listo, ejecuta la siguiente consulta:
kubectl get pgbouncers.alloydbomni.dbadmin.goog PGBOUNCER_NAME -n NAMESPACE -w
El resultado es similar a este:
NAME ENDPOINT STATE mypgbouncer 10.138.15.207 Ready
Configura los parámetros de PgBouncer
Usa los siguientes parámetros para configurar PGBouncer:
Parámetro | Descripción | Valor predeterminado |
---|---|---|
pool_mode |
Especifica cuándo otros clientes pueden reutilizar una conexión de base de datos. Los valores permitidos son los siguientes:
|
session |
ignore_startup_parameters |
Especifica los parámetros que PgBouncer no permite para que se ignoren durante el inicio. | |
default_pool_size |
Es la cantidad de conexiones de base de datos que se permiten por par usuario-base de datos. | 20 |
max_client_conn |
Es la cantidad máxima de conexiones de cliente. | 100 |
max_db_connections |
Es la cantidad máxima de conexiones de base de datos. | 0 |
Personaliza la implementación de PgBouncer
AlloyDB Omni usa recursos personalizados para administrar sus componentes. Para personalizar la implementación de PgBouncer en tu AlloyDB Omni en Kubernetes, modifica el recurso personalizado PgBouncer
de la siguiente manera:
Haz una lista de los recursos personalizados de
PgBouncer
:kubectl get pgbouncers -n NAMESPACE
Reemplaza NAMESPACE por el espacio de nombres en el que implementaste AlloyDB Omni.
Para modificar el recurso, abre el archivo de declaración del recurso
PgBouncer
en tu editor predeterminado:kubectl edit pgbouncers PGBOUNCER_NAME -n NAMESPACE
En el archivo de declaración, busca la sección
podSpec
que contiene la configuración y modifica cualquiera de los siguientes campos según sea necesario:resources
: Elcpu
y elmemory
definidos para tu 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
: Es la ruta de acceso a la etiqueta de imagen de PgBouncer:... podSpec: resources: memory: 1Gi cpu: 1 image: IMAGE ...
schedulingconfig
: Incluye la secciónnodeaffinity
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 ...
Reemplaza lo siguiente:
NODE_AFFINITY_TYPE
: Establece el parámetro en 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 con la regla definida para la programación. Sin embargo, si no hay un nodo de ese tipo, Kubernetes programa la carga en un nodo diferente del clúster.
LABEL_KEY
: Es la etiqueta del nodo para la clave que funciona 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. Establece el parámetro en uno de los siguientes valores:In
: El array de valores no debe estar vacío.NotIn
: El array de valores no debe estar vacío.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.
Después de realizar los cambios, guarda el archivo de declaración. El operador de Kubernetes de AlloyDB Omni aplica automáticamente los cambios a tu implementación de PgBouncer.
Programa tareas con afinidad de nodo
Puedes usar la afinidad de nodos para controlar dónde se programan los Pods de PgBouncer, lo que proporciona una ubicación más precisa que la programación normal. La afinidad de nodos garantiza que los Pods de PgBouncer se coloquen en nodos que cumplan con criterios específicos, como tener etiquetas particulares.
Para especificar la afinidad de nodos para los Pods de PgBouncer, modifica el recurso personalizado PgBouncer
para agregar la sección schedulingconfig
a la sección podSpec
:
apiVersion: alloydbomni.dbadmin.goog/v1
kind: PgBouncer
metadata:
name: PGBOUNCER_NAME
spec:
# ... other PgBouncer configuration ...
podSpec:
# ... other podSpec settings ...
schedulingconfig:
nodeaffinity:
NODE_AFFINITY_TYPE:
nodeSelectorTerms:
- matchExpressions:
- key: LABEL_KEY
operator: OPERATOR_VALUE
values:
- pgbouncer
Reemplaza lo siguiente:
NODE_AFFINITY_TYPE
: Establece el parámetro en 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 con la regla definida para la programación. Sin embargo, si no hay un nodo de ese tipo, Kubernetes programa la carga en un nodo diferente del clúster.
LABEL_KEY
: Es la clave de la etiqueta del nodo. Por ejemplo,disktype=ssd
OPERATOR_VALUE
: Representa la relación de una clave con un conjunto de valores. Establece el parámetro en uno de los siguientes valores:In
: El valor de la etiqueta del nodo debe coincidir con un valor del arrayvalues
.NotIn
: El valor de la etiqueta del nodo no debe coincidir con ningún valor del arrayvalues
.Exists
: La etiquetaLABEL_KEY
debe existir en el nodo. El arrayvalues
debe estar vacío.DoesNotExist
: La etiquetaLABEL_KEY
no debe existir en el nodo. El arrayvalues
debe estar vacío.Gt
: El valor de la etiqueta del nodo debe ser mayor que el valor único del arrayvalues
, que se interpreta como un número entero.Lt
: El valor de la etiqueta del nodo debe ser menor que el valor único del arrayvalues
, que se interpreta como un número entero.
En el siguiente ejemplo, se ilustra la programación de Pods de PgBouncer en nodos etiquetados como nodetype=pgbouncer
:
apiVersion: alloydbomni.dbadmin.goog/v1
kind: PgBouncer
metadata:
name: mypgbouncer
spec:
# ... other PgBouncer configuration ...
podSpec:
# ... other podSpec settings ...
schedulingconfig:
nodeaffinity:
requiredDuringSchedulingIgnoredDuringExecution:
nodeSelectorTerms:
- matchExpressions:
- key: nodetype
operator: In
values:
- pgbouncer
En este ejemplo, el parámetro de configuración requiredDuringSchedulingIgnoredDuringExecution
garantiza que los pods de PgBouncer solo se programen en nodos con la etiqueta nodetype=pgbouncer
.
Borra el recurso de PgBouncer
Para borrar un recurso personalizado de PgBouncer, ejecuta el siguiente comando:
kubectl delete pgbouncers.alloydbomni.dbadmin.goog PGBOUNCER_NAME -n NAMESPACE
El resultado es similar a este:
pgbouncer.alloydbomni.dbadmin.goog "mypgbouncer" deleted
Cómo 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:
Obtén una lista de todos los Pods de PgBouncer en tu espacio de nombres:
kubectl get pods -n NAMESPACE
El resultado es similar a este:
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
Visualiza los registros de un Pod en particular:
kubectl logs -f POD_NAME -n NAMESPACE
El resultado es similar a este:
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
Supervisa el rendimiento y la actividad de PgBouncer
Solo puedes ver las métricas del grupo de conexiones de PgBouncer con un statsuser
dedicado para acceder a la base de datos de estadísticas internas de PgBouncer. El statsuser
se usa para la autenticación cuando se conecta a la base de datos de PgBouncer.
Conéctate a tu instancia de AlloyDB Omni como superusuario o como usuario con el privilegio
CREATE ROLE
usando el clientepsql
:export PGPASSWORD="ChangeMe123"; export PGSSLMODE="require"; psql -h HOST -d postgres -U postgres -p PORT
El resultado es similar a este:
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.
Crea el
statsuser
en tu AlloyDB Omni:postgres=# CREATE USER "statsuser" WITH PASSWORD 'tester';
El resultado es similar a este:
CREATE ROLE postgres=#
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 es similar a este:
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.
Ejecuta el comando
SHOW STATS
para ver el rendimiento de PgBouncer y detectar posibles problemas:pgbouncer=# SHOW STATS;
El resultado es similar a este:
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)
Configura el acceso a la red de 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 agrupador de conexiones de PgBouncer definiendo rangos de direcciones IP específicos con 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 de prefijo. La longitud del prefijo especifica la cantidad de bits de la dirección IP que se usan 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 agrega o modifica el parámetro de configuración loadBalancerSourceRanges
:
serviceOptions:
type: "LoadBalancer"
loadBalancerSourceRanges:
- "CIDR_BLOCK"
Reemplaza CIDR_BLOCK
por una cadena de CIDR que especifique los rangos de direcciones IP permitidos para las conexiones entrantes al servicio LoadBalancer
. El parámetro de configuración loadBalancerSourceRanges
filtra el tráfico de red entrante y controla qué clientes pueden acceder a tu instancia de base de datos.
Para verificar que la configuración de loadBalancerSourceRanges
se haya aplicado correctamente, usa el siguiente comando para verificar la dirección IP externa asignada a tu servicio LoadBalancer
:
kubectl get svc -n NAMESPACE -w
Reemplaza NAMESPACE
por el espacio de nombres en el que se encuentra tu implementación de AlloyDB Omni.
El resultado es similar a este:
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
Una vez que LoadBalancer
esté listo, la columna EXTERNAL_IP
se completará con la dirección IP externa asignada al servicio LoadBalancer
.
Las conexiones a esta IP externa se filtran según el parámetro de configuración loadBalancerSourceRanges
.
Después de verificar la IP externa, prueba las conexiones desde las aplicaciones dentro de tus rangos de CIDR permitidos para asegurarte de que se puedan conectar.
Inhabilita el agrupador de conexiones de PgBouncer
Si necesitas desactivar o revertir el PgBouncer Connection Pooler, sigue estos pasos:
Verifica 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 administrar la flota de AlloyDB Omni. Busca la opción
--enable-pgbouncer
en la secciónargs
del arraycontainers
:... 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
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
En el manifiesto de implementación, cambia el valor de la opción
--enable-pgbouncer
detrue
afalse
:... --enable-pgbouncer=false
Guarda el archivo y sal del editor.
kubectl
aplica el cambio automáticamente.