Sign inSign up

Azure Oss Db Tools Pgbouncer Sidecar

Verified Publisher

azure-oss-db-tools/pgbouncer-sidecar

By Microsoft

•Updated over 2 years ago

Dockerized PgBouncer for use with Azure Kubernetes Serivce and Azure DB for PostgreSQL

0

microsoft/azure-oss-db-tools-pgbouncer-sidecar repository overview

  • latest

⁠About this Image

⁠What is PgBouncer Sidecar?

The PgBouncer Sidecar is a lightweight (~15MB) containerization of PgBouncer⁠, preconfigured for connection pooling when connecting to Azure Database for PostgreSQL. The primary use of this image is as a Kubernetes Sidecar in Azure Kubernetes Service (AKS), but can be used in any environment which supports Docker Containers.

⁠How to Use this Image

⁠Docker pull command

  • docker pull mcr.microsoft.com/azure-oss-db-tools/pgbouncer-sidecar:latest

⁠How to use this image with Azure Kubernetes Service?

  • Create two empty files pgbouncer.ini and userlist.txt. These files are needed to configure the container to target your Azure Database for PostgreSQL instance.

  • In pgbouncer.ini, please copy the following. The only required change is editing the line host=mypgserver.postgres.database.azure.com port=5432 to reflect your server details. If you would like to change other settings, please do so in this file:

      [databases]
      # Please change "host=postgres.default port=5432"
      # to reflect your PostgreSQL target:
      * = host=mypgserver.postgres.database.azure.com port=5432
      [pgbouncer]
      # Do not change these settings:
      listen_addr = 0.0.0.0
      auth_file = /etc/pgbouncer/userlist.txt
      auth_type = trust
      server_tls_sslmode = verify-ca
      server_tls_ca_file = /etc/root.crt.pem
      # These are defaults and can be configured
      # please leave them as defaults if you are
      # uncertain.
      listen_port = 5432
      unix_socket_dir =
      user = postgres
      pool_mode = transaction
      max_client_conn = 100
      ignore_startup_parameters = extra_float_digits
      admin_users = postgres
      # Please add any additional settings below this line
    

    Warning! Do not change listen_addr, auth_file, auth_type, server_tls_sslmode or server_tls_ca_file. Changing any of these settings will prevent successful connections to the server.

    Note: if you need to change the listen_port to prevent conflicts in your AKS Cluster, please ensure that you update the deployment YAML container reference to expose the correct port.

  • In userlist.txt, please add your username/password combinations in plaintext (Azure PG does not support md5 encoded passwords). Each line should be in the format:

      "username@hostname" "password"
    

    each entry is simply new line separated. Example:

      "sa@mypgserver" "P@ssword1234"
      "test@mypgserver" "Test@#1234"
    

    Note: Azure Database for PostgreSQL usernames are always in the format username@hostname

    Note: Applications accessing PostgresSQL via this PgBouncer Sidecar must use credentials with a password. If you are using passwordless auth, please set a password using: ALTER USER {user} WITH PASSWORD '{password}';

  • After you are finished editing the two files, create a secret in your AKS Instance using the following command. This will allow all instances of the sidecar to access your target PostgreSQL instance:

      kubectl create secret generic azure-pgbouncer-config --from-file=pgbouncer.ini --from-file=userlist.txt
    
  • Add a reference to the container in the deployment YAML for any pods which you want to load this sidecar:

      containers:
        - name: azure-pgbouncer-sidecar
          image: mcr.microsoft.com/azure-oss-db-tools/pgbouncer-sidecar:latest
          # Uncomment below if you always want the latest version
          # imagePullPolicy: Always
          ports:
            - containerPort: 5432
          volumeMounts:
            - name: configfiles
              mountPath: "/etc/pgbouncer"
              # writes update the secret, we do not want to do this
              readOnly: true  
          livenessProbe:
            tcpSocket:
              # This must match the port your applications use to talk to postgres
              port: 5432
            periodSeconds: 60
          lifecycle:
            preStop:
              exec:
                command: ["/bin/sh", "-c", "killall -INT pgbouncer && sleep 120"]
          securityContext:
            allowPrivilegeEscalation: false
            capabilities:
              drop: ['all']
      volumes:
        - name: configfiles
          secret:
              # This must match the name of your secret above
              secretName: azure-pgbouncer-config
    
  • Provide 127.0.0.1:5432 (or whichever listen_port you selected) as the PostgreSQL Host Address your containers/applications use to access Azure Database for PostgreSQL.

    Note: Because the sidecar runs in a container in the same pod as your application, it appears to your application as localhost, so you use 127.0.0.1 to connect to it.

⁠Full Tag Listing

You can retrieve a list of all available tags for azure-oss-db-tools/pgbouncer-sidecar at https://mcr.microsoft.com/v2/azure-oss-db-tools/pgbouncer-sidecar/tags/list⁠

⁠Support

For more information, go to https://support.microsoft.com/⁠

⁠License

Tag Summary

No tags have been pushed to this repository yet.