azure-oss-db-tools/pgbouncer-sidecar
Dockerized PgBouncer for use with Azure Kubernetes Serivce and Azure DB for PostgreSQL
latestThe 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.
docker pull mcr.microsoft.com/azure-oss-db-tools/pgbouncer-sidecar:latestCreate 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.
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
For more information, go to https://support.microsoft.com/
No tags have been pushed to this repository yet.