Golang Logo

Go/Golang Training

Unser Hands-On-Einstieg in die Entwicklung mit Go. Nächster Termin: 14.- 15.05. in Köln – jetzt buchen!
Zum Training 
the postgres elephant logo on a padlock
IT Engineering

Securely Managing Postgres Connections with pgbouncer-vault-sidecar

5 ​​min

inovex has released a sidecar container image to ease the use of short-lived Postgres database credentials – pgbouncer-vault-sidecar. With the use of Vault, this makes injecting database credentials into pods obsolete.

In today’s age, security is of utmost importance, especially for organizations handling sensitive data. One common way to increase security is to use short-lived credentials, which help limit the time attackers have to exploit a vulnerability. This approach reduces the risk of credentials being stolen or misused, making it a highly effective security measure.

HashiCorp Vault is a popular solution for securely managing short-lived credentials. It provides a centralized management system for secrets, such as database credentials. Access to secrets can be managed via policies and audit logs help to identify intrusions. However, integrating Vault with your application can be complex and time-consuming. Applications have to deal with:

  • Authenticating against Vault
  • Obtaining secrets from Vault
  • Renewing the leased credentials
  • Coping with rotating credentials

HashiCorp has created Vault Agent to deal with most of the problems. However, coping with rotating credentials is challenging. Applications should adopt the new credentials while continuing to run to avoid downtime.

Let’s take database credentials as an example. Many applications depend on a database, such as Postgres, and use credentials to authenticate against it over the network. If the credentials were to change frequently, the application has to detect the change and update the database connections gracefully without interrupting service. This requires code changes in every application that wants to make use of Vault. In the worst-case scenario, an application cannot be changed.

This is where pgbouncer-vault-sidecar comes in. It is a project developed by inovex that simplifies the integration process, making it easier for developers to use Vault to manage their Postgres credentials.

How it works

pgbouncer-vault-sidecar is a sidecar that can be deployed with your application. It serves as a connection pooler and takes care of authentication. It exposes the database to the main application via localhost where the pod serves as a security boundary. The sidecar is easy to configure and works with every application that uses Postgres – legacy or cloud-native.

The sidecar authenticates against Vault, obtains and renews leases for database credentials, connects to the database, and switches to new credentials once the lease can no longer be renewed.

Aside from authentication, being a connection pooler, the sidecar also helps to reduce resource consumption on the database server and can provide metrics on database connections.

Let’s see it in action

To show the benefit of the sidecar, we need Vault, a Postgres database cluster, and a demo application running inside Kubernetes.

We choose Minikube to provision a developer cluster:

Once our cluster is ready, we deploy Vault and a Postgres database. kubectl should be configured to use the “default“ namespace.

Vault allows applications to authenticate via Kubernetes service accounts. We have to enable this in Vault.

Furthermore, we have to add the Postgres cluster to Vault and define a database role. This role is used to create short-lived roles in Postgres (HashiCorp and Postgres use the term role differently). We purposefully set the TTL and max TTL to a low value to demonstrate that leases are automatically renewed and PGBouncer switches to new credentials seamlessly. In production, those values should be higher.

In order to use the role “readonly“ we have to bind the application service account to yet another role (in the context of the Kubernetes authentication method) and assign a policy in order to obtain a lease for “readonly“.

Now we have everything set up to start our application. For demonstration purposes, we continuously query the current user (from the perspective of Postgres).

The main application can now connect to Postgres with minimal configuration! Looking at the logs, we can see that the user changes once the maximum lease time has been reached (3 minutes). PGBouncer automatically adapted the new credentials.

PGBouncer is configured for transaction pooling. That is, a connection to Postgres is blocked by the application until the transaction is committed (or aborted). PGBouncer switches to the new credentials gracefully (see RELOAD). That means that long-running transactions keep using the old role, while new transactions use the new role.


pgbouncer-vault-sidecar is a simple and secure way to introduce short-lived credentials into your application. By leveraging the sidecar pattern, you can easily integrate Vault into any application that uses Postgres without adding unnecessary complexity.

We encourage you to try out pgbouncer-vault-sidecar. It is available on GitHub. Contributions are welcome 🙂

One thought on “Securely Managing Postgres Connections with pgbouncer-vault-sidecar

  1. How would the setup look like in a multi-tenant scenario? Like a shared PostgreSQL-Server running multiple DBs? Assuming Java, the app would have dedicated DataSource (like Hikari) with dedicated credentials and permissions per tenant. How would the sidecar handle that?

Hat dir der Beitrag gefallen?

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert