PgBouncer-Verbindungspooler verwenden

Wählen Sie eine Dokumentenversion aus:

Auf dieser Seite wird beschrieben, wie Sie den PgBouncer-Verbindungs-Pooler für AlloyDB Omni mit dem AlloyDB Omni Kubernetes-Operator aktivieren und verwenden.

Viele Anwendungen, insbesondere Webanwendungen, öffnen und schließen häufig Datenbankverbindungen, was die Datenbankinstanz erheblich belasten kann. PgBouncer trägt dazu bei, die Instanzlast zu reduzieren, indem Verbindungen effizienter verwaltet werden. Durch die Wiederverwendung von Verbindungen minimiert PgBouncer die Anzahl der Verbindungen zur Datenbankinstanz und gibt so Ressourcen auf der Instanz frei.

PgBouncer-Dienst erstellen

Mit dem AlloyDB Omni Kubernetes-Operator können Sie einen dedizierten PgBouncer-Dienst für Ihre Datenbank erstellen. Anschließend können Sie über den PgBouncer-Dienst auf die Datenbank zugreifen und vom Verbindungs-Pooling profitieren.

Es gibt eine spezielle benutzerdefinierte Ressourcendefinition (Custom Resource Definition, CRD) zum Konfigurieren des PgBouncer-Dienstes nach Bedarf.

So erstellen Sie einen PgBouncer-Dienst für Ihre Datenbank:

  1. Erstellen Sie eine benutzerdefinierte PgBouncer-Ressource in Ihrem Kubernetes-Cluster:

    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"

    Ersetzen Sie Folgendes:

    • PGBOUNCER_NAME: der Name Ihrer benutzerdefinierten PgBouncer-Ressource.
    • DB_CLUSTER_NAME: der Name Ihres AlloyDB Omni-Datenbankclusters. Das ist derselbe Datenbankclustername, den Sie bei der Erstellung angegeben haben.
    • POOL_MODE: gibt an, wann eine Datenbankverbindung von anderen Clients wiederverwendet werden kann. Legen Sie für den Parameter einen der folgenden Werte fest:
      • session: Die Datenbankverbindung wird nach dem Trennen des Clients an den Pool zurückgegeben. Standardmäßig verwendet.
      • transaction: Die Datenbankverbindung wird nach Abschluss der Transaktion an den Pool zurückgegeben.
      • statement: Die Datenbankverbindung wird nach Abschluss der Abfrage an den Pool zurückgegeben. Transaktionen, die mehrere Anweisungen umfassen, sind in diesem Modus nicht zulässig.
    • IGNORE_STARTUP_PARAMETERS: gibt Parameter an, die von PgBouncer nicht zugelassen werden, damit sie beim Start ignoriert werden, z. B. extra_float_digits. Weitere Informationen finden Sie unter PgBouncer-Konfiguration.
    • DEFAULT_POOL_SIZE: die Anzahl der zulässigen Datenbankverbindungen pro Nutzer-Datenbank-Paar, z. B. 8.
    • MAXIMUM_CLIENT_CONNECTIONS: die maximale Anzahl von Clientverbindungen, z. B. 800.
    • MAXIMUM_DATABASE_CONNECTIONS: die maximale Anzahl von Datenbankverbindungen, z. B. 160.
  2. Wenden Sie das Manifest an:

    kubectl apply -f PATH_TO_MANIFEST -n NAMESPACE

    Ersetzen Sie PATH_TO_MANIFEST durch den Pfad zu Ihrer Manifestdatei, z. B. /fleet/config/pgbouncer.yaml.

  3. Führen Sie die folgende Abfrage aus, um zu prüfen, ob das erstellte PgBouncer-Objekt bereit ist:

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

    Ersetzen Sie NAMESPACE durch den Namen des Kubernetes-Namespace für Ihr PgBouncer-Objekt.

    Die Ausgabe sieht etwa so aus:

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

Verbindung zum Endpunkt des Verbindungs-Poolers herstellen

Sie können eine Verbindung zum PgBouncer-Verbindungs-Pooler von innerhalb oder außerhalb eines Kubernetes-Clusters herstellen.

Verbindung innerhalb eines Kubernetes-Clusters herstellen

So stellen Sie mit dem psql-Client eine Verbindung zum Endpunkt des Verbindungs-Poolers her:

  1. Erstellen Sie einen Pod:

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

    kubectl apply -f PATH_TO_MANIFEST -n NAMESPACE
    
  3. Stellen Sie eine Verbindung zur containerisierten Anwendung her:

    kubectl exec -it postgres -n NAMESPACE -- bash
    
  4. Prüfen Sie die SSL-Verbindung zum PgBouncer-Endpunkt mit dem psql-Client:

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

    Ersetzen Sie Folgendes:

    • HOST: der Endpunkt des Verbindungs-Poolers, den Sie mit dem Befehl kubectl get pgbouncers.alloydbomni.dbadmin.goog -n NAMESPACE abrufen. Wenn PgBouncer nicht als Dienst verfügbar gemacht wird, verwenden Sie die IP-Adresse.
    • PORT: der Port, auf dem PgBouncer wartet.

    Im Terminalfenster wird der psql-Anmeldetext angezeigt, der mit dem Prompt postgres=# endet.

Verbindung von außerhalb eines Kubernetes-Clusters herstellen

Wenn Sie von außerhalb eines Kubernetes-Clusters auf den PgBouncer-Verbindungs-Pooler zugreifen möchten, legen Sie das Feld type im Attribut serviceOptions auf LoadBalancer fest. Dadurch wird ein loadbalancer-Dienst erstellt.

  1. Erstellen Sie eine benutzerdefinierte PgBouncer-Ressource in Ihrem Kubernetes-Cluster:

    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. Wenden Sie das Manifest an:

    kubectl apply -f PATH_TO_MANIFEST
  3. Führen Sie die folgende Abfrage aus, um zu prüfen, ob das erstellte PgBouncer-Objekt bereit ist:

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

    Die Ausgabe sieht etwa so aus:

    NAME          ENDPOINT       STATE
    mypgbouncer   10.138.15.207   Ready
    

PgBouncer-Einstellungen konfigurieren

Verwenden Sie die folgenden Parameter, um die PgBouncer-Einstellungen zu konfigurieren:

Parameter Beschreibung Standardwert
pool_mode Gibt an, wann eine Datenbankverbindung von anderen Clients wiederverwendet werden kann.
Zulässige Werte:
  • session: Die Datenbankverbindung wird nach dem Trennen des Clients an den Pool zurückgegeben.
  • transaction: Die Datenbankverbindung wird nach Abschluss der Transaktion an den Pool zurückgegeben.
  • statement: Die Datenbankverbindung wird nach Abschluss der Abfrage an den Pool zurückgegeben.
    Transaktionen, die mehrere Anweisungen umfassen, sind in diesem Modus nicht zulässig.
session
ignore_startup_parameters Gibt Parameter an, die von PgBouncer nicht zugelassen werden, damit sie beim Start ignoriert werden.
default_pool_size Die Anzahl der zulässigen Datenbankverbindungen pro Nutzer-Datenbank-Paar. 20
max_client_conn Die maximale Anzahl von Clientverbindungen. 100
max_db_connections Die maximale Anzahl von Datenbankverbindungen. 0

PgBouncer-Bereitstellung anpassen

AlloyDB Omni verwendet benutzerdefinierte Ressourcen, um seine Komponenten zu verwalten. Wenn Sie die PgBouncer-Bereitstellung in AlloyDB Omni für Kubernetes anpassen möchten, ändern Sie die benutzerdefinierte PgBouncer-Ressource so:

  1. Listen Sie die benutzerdefinierten PgBouncer-Ressourcen auf:

    kubectl get pgbouncers -n NAMESPACE

    Ersetzen Sie NAMESPACE durch den Namespace, in dem Sie AlloyDB Omni bereitgestellt haben.

  2. Öffnen Sie die Deklarationsdatei für die PgBouncer-Ressource in Ihrem Standardeditor, um die Ressource zu ändern:

    kubectl edit pgbouncers PGBOUNCER_NAME -n NAMESPACE
  3. Suchen Sie in der Deklarationsdatei den Abschnitt podSpec mit der Konfiguration und ändern Sie bei Bedarf eines der folgenden Felder:

    • resources: die für Ihren Container definierten cpu und memory:

      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: der Pfad zum PgBouncer-Image-Tag:

      ...
        podSpec:
          resources:
            memory: 1Gi
            cpu: 1
          image: IMAGE
      ...
      
    • schedulingconfig: Fügen Sie den Abschnitt nodeaffinity ein, um zu steuern, wo die PgBouncer-Pods geplant werden:

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

      Ersetzen Sie Folgendes:

      • NODE_AFFINITY_TYPE: Legen Sie für den Parameter einen der folgenden Werte fest:
        • requiredDuringSchedulingIgnoredDuringExecution: Kubernetes plant den Pod genau nach den definierten Regeln.
        • preferredDuringSchedulingIgnoredDuringExecution: Der Kubernetes-Planer versucht, einen Knoten zu finden, der die definierte Regel für die Planung erfüllt. Wenn es keinen solchen Knoten gibt, plant Kubernetes den Pod auf einem anderen Knoten im Cluster.
      • LABEL_KEY: das Knotenlabel für den Schlüssel, der als Standortindikator dient und eine gleichmäßige Pod-Verteilung im Cluster ermöglicht, z. B. nodetype.
      • OPERATOR_VALUE: stellt die Beziehung eines Schlüssels zu einer Reihe von Werten dar. Legen Sie für den Parameter einen der folgenden Werte fest:
        • In: Das Array „values“ darf nicht leer sein.
        • NotIn: Das Array „values“ darf nicht leer sein.
        • Exists: Das Array „values“ muss leer sein.
        • DoesNotExist: Das Array „values“ muss leer sein.
        • Gt: Das Array „values“ muss ein einzelnes Element enthalten, das als Ganzzahl interpretiert wird.
        • Lt: Das Array „values“ muss ein einzelnes Element enthalten, das als Ganzzahl interpretiert wird.
  4. Speichern Sie nach den Änderungen die Deklarationsdatei. Der AlloyDB Omni Kubernetes-Operator wendet die Änderungen automatisch auf Ihre PgBouncer-Bereitstellung an.

PgBouncer-Ressource löschen

Führen Sie den folgenden Befehl aus, um eine benutzerdefinierte PgBouncer-Ressource zu löschen:

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

Die Ausgabe sieht etwa so aus:

pgbouncer.alloydbomni.dbadmin.goog "mypgbouncer" deleted

PgBouncer-Logs ansehen

Sie können die Logs einer beliebigen PgBouncer-Replikatinstanz in Ihrer AlloyDB Omni-Bereitstellung in Kubernetes so ansehen und analysieren:

  1. Rufen Sie eine Liste aller PgBouncer-Pods in Ihrem Namespace ab:

    kubectl get pods -n NAMESPACE

    Die Ausgabe sieht etwa so aus:

    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. Logs für einen bestimmten Pod ansehen:

    kubectl logs -f POD_NAME -n NAMESPACE

    Die Ausgabe sieht etwa so aus:

    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
    

PgBouncer-Leistung und -Aktivität überwachen

Sie können Messwerte für den PgBouncer-Verbindungspool nur mit einem dedizierten statsuser aufrufen, um auf die interne Statistikdatenbank von PgBouncer zuzugreifen. Der statsuser wird für die Authentifizierung verwendet, wenn eine Verbindung zur PgBouncer-Datenbank hergestellt wird.

  1. Stellen Sie mit dem psql-Client als Superuser oder als Nutzer mit der Berechtigung CREATE ROLE eine Verbindung zu AlloyDB Omni her:

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

    Die Ausgabe sieht etwa so aus:

    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. Erstellen Sie den statsuser in AlloyDB Omni:

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

    Die Ausgabe sieht etwa so aus:

    CREATE ROLE
    postgres=#
    
  3. Stellen Sie als statsuser eine Verbindung zur PgBouncer-Datenbank her:

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

    Die Ausgabe sieht etwa so aus:

    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. Führen Sie den SHOW STATS Befehl aus, um die PgBouncer-Leistung zu sehen und potenzielle Probleme zu erkennen:

    pgbouncer=# SHOW STATS;
    

    Die Ausgabe sieht etwa so aus:

         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)
    

Netzwerkzugriff auf Ihre AlloyDB Omni-Instanz konfigurieren

Um die Sicherheit Ihrer AlloyDB Omni-Bereitstellung in Kubernetes zu gewährleisten, können Sie den Netzwerkzugriff auf den PgBouncer-Verbindungs-Pooler beschränken, indem Sie bestimmte IP-Adressbereiche mit der CIDR-Notation (Classless Inter-Domain Routing) definieren.

Die CIDR-Notation kombiniert eine IP-Adresse mit einer Präfixlänge. Der CIDR-Block 192.168.1.0/24 gibt beispielsweise 192.168.1.0 für die Adresse und 24 für die Präfixlänge an. Die Präfixlänge gibt die Anzahl der Bits in der IP-Adresse an, die für den Netzwerkanteil verwendet werden, und definiert die Subnetzmaske.

Suchen Sie in der Deklarationsdatei Ihrer Bereitstellung den Abschnitt serviceOptions und fügen Sie die Einstellung loadBalancerSourceRanges hinzu oder ändern Sie sie:

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

Ersetzen Sie CIDR_BLOCK durch einen CIDR-String, der die IP-Adressbereiche angibt, die für eingehende Verbindungen zum LoadBalancer-Dienst zulässig sind. Die Einstellung loadBalancerSourceRanges filtert eingehenden Netzwerkverkehr und steuert, welche Clients auf Ihre Datenbankinstanz zugreifen können.

Verwenden Sie den folgenden Befehl, um zu prüfen, ob Ihre loadBalancerSourceRanges-Konfiguration korrekt angewendet wurde. Prüfen Sie dazu die externe IP-Adresse, die Ihrem LoadBalancer-Dienst zugewiesen ist:

kubectl get svc -n NAMESPACE -w

Ersetzen Sie NAMESPACE durch den Namespace, in dem sich Ihre AlloyDB Omni-Bereitstellung befindet.

Die Ausgabe sieht etwa so aus:

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

Sobald der LoadBalancer bereit ist, wird die Spalte EXTERNAL_IP mit der externen IP-Adresse gefüllt, die dem LoadBalancer-Dienst zugewiesen ist. Verbindungen zu dieser externen IP werden basierend auf der Einstellung loadBalancerSourceRanges gefiltert.

Nachdem Sie die externe IP-Adresse geprüft haben, testen Sie die Verbindungen von Anwendungen innerhalb Ihrer zulässigen CIDR-Bereiche, um sicherzustellen, dass sie eine Verbindung herstellen können.

PgBouncer-Verbindungs-Pooler deaktivieren

Wenn Sie den PgBouncer-Verbindungs-Pooler deaktivieren oder ein Rollback durchführen müssen, gehen Sie so vor:

  1. Prüfen Sie den Status des Verbindungs-Poolers:

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

    Dieser Befehl zeigt das Bereitstellungsmanifest des primären Controllers für die Verwaltung der AlloyDB Omni-Flotte. Suchen Sie im Abschnitt args des Arrays containers nach der Option --enable-pgbouncer:

    ...
     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. Bearbeiten Sie die Konfiguration der Controller-Bereitstellung, um den Verbindungs-Pooler zu deaktivieren:

    kubectl edit deployment fleet-controller-manager --namespace alloydb-omni-system
  3. Ändern Sie im Bereitstellungsmanifest den Wert der Option --enable-pgbouncer von true in false:

    ...
    --enable-pgbouncer=false
    
  4. Speichern Sie die Datei und beenden Sie den Editor. kubectl wendet die Änderung automatisch an.

Nächste Schritte