rds-proxy-password-rotation

:warning: Work in progress :warning:

add Terraform module

Python script for multi-user password rotation using RDS and RDS proxy. It supports credentials for the application and the RDS proxy.

We implemented this logic again, because current implementations

have no tests
have no release process
are not published to PyPI
have no Docker image available
have no Terraform module available

Pre-requisites

Python 3.10 or later
For each db user:
1. Clone the user in the database and grant the necessary permissions. We suggest to add a -clone suffix to the username.
2. Create a secret in AWS Secrets Manager with the following key-value pairs (for every user and its clone):
  - rotation_type: "AWS RDS"
  - rotation_usernames: Optional. The list of usernames that a part of the rotation, e.g. ["app_user", "app_user-clone"]. If not provided, username is used only.
  - proxy_secret_ids: Optional. The list of ARNs of the secrets that are attached to the RDS Proxy, e.g. ["arn:aws:secretsmanager:region:account-id:secret:secret-name"]. If not provided, the proxy credentials are not adjusted.
  - database_host: The hostname of the database
  - database_port: The port of the database
  - database_name: The name of the database
  - username: The username for the user
  - password: The password for the user
  This credential will be used by the application to connect to the proxy. You may add additional key-value pairs as needed.
If you are using RDS Proxy:
1. Create a secret in AWS Secrets Manager with the following key-value pairs:
  - username: The username for the user that the proxy will use to connect to the database
  - password: The password for the user that the proxy will use to connect to the database
2. Attach the secret to the RDS Proxy.
The docker image can be pulled from GHCR:
```
docker pull ghcr.io/Hapag-Lloyd/rds-proxy-password-rotation:edge
```
:warning: The edge tag is used for the latest build. You SHOULD use a specific version tag in production.

Architecture

Challenges with RDS and RDS Proxy

RDS Proxy is a fully managed, highly available database proxy for Amazon Relational Database Service (RDS) that makes applications more scalable, more resilient to database failures, and more secure. It allows applications to pool and share database connections to improve efficiency and reduce the load on your database instances.

However, RDS Proxy does not support multi-user password rotation out of the box. This script provides a solution to this problem.

Using an RDS Proxy requires a secret in AWS Secrets Manager with the credentials to connect to the database. This secret is used by the proxy to connect to the database. The proxy allows the application to connect to the database using the same credentials and then forwards the requests to the database with the same credentials. This means that the credentials in the secret must be valid in the database at all times. But what if you want to rotate the password for the user that the proxy uses to connect to the database? You can’t just update the secret in SecretsManager because the proxy will stop working as soon as the secret is updated. And you can’t just update the password in the database because the proxy will stop working as soon as the password is updated.

Why password rotation is a good practice

Password rotation is a good idea for several reasons:

Enhanced Security: Regularly changing passwords reduces the risk of unauthorized access due to compromised credentials.
Mitigates Risk: Limits the time window an attacker has to exploit a stolen password.
Compliance: Many regulatory standards and security policies require periodic password changes.
Reduces Impact of Breaches: If a password is compromised, rotating it ensures that the compromised password is no longer valid.
Encourages Good Practices: Promotes the use of strong, unique passwords and discourages password reuse.

Release files for rds-proxy-password-rotation 0.6.534

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rds-proxy-password-rotation 0.6.534
File	Size	Uploaded
rds_proxy_password_rotation-0.6.534.tar.gz	9.9 kB	Sep 8, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for rds-proxy-password-rotation 0.6.534
File	Interpreter	ABI	Platform	Reset
rds_proxy_password_rotation-0.6.534-py3-none-any.whl 11.0 kB Sep 8, 2026	Python 3	none	any	Details

Total release size: 20.9 kB

Release files / rds_proxy_password_rotation-0.6.534.tar.gz

Download URL	rds_proxy_password_rotation-0.6.534.tar.gz
Size	9.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`32e80a86b317a6cb9de897167af00cd6190b86c2856c4b6148b0729276e7545d`
BLAKE2b-256 checksum How to use checksums	`2e76dadd082a0ed19da18a4fd8bb074b6561547c643453a07bcd1622f9cc7ce9`
Upload date	Sep 8, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Hapag-Lloyd/rds-proxy-password-rotation
Publishing commit: github.com/Hapag-Lloyd/rds-proxy-password-rotation/tree/189452aa90a81624aa4adb67a05098c7e6a4aa9a

Workflow

Publishing configuration: github.com/Hapag-Lloyd/rds-proxy-password-rotation/blob/189452aa90a81624aa4adb67a05098c7e6a4aa9a/.github/workflows/pypi_publish.yml
Publishing logs: github.com/Hapag-Lloyd/rds-proxy-password-rotation/actions/runs/34240144201/attempts/1

Artifact

Subject: rds_proxy_password_rotation-0.6.534.tar.gz
SHA-256 checksum: 32e80a86b317a6cb9de897167af00cd6190b86c2856c4b6148b0729276e7545d Verifying attestations

Release files / rds_proxy_password_rotation-0.6.534-py3-none-any.whl

Download URL	rds_proxy_password_rotation-0.6.534-py3-none-any.whl
Size	11.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f4b889c147ec25c996615d5b60fa79778cccc41d8d0241404966a85cf46314e3`
BLAKE2b-256 checksum How to use checksums	`1c04450d295ba790f306c41ce57dda1d5d6e126098461ac3a5aec93cf20618f8`
Upload date	Sep 8, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Hapag-Lloyd/rds-proxy-password-rotation
Publishing commit: github.com/Hapag-Lloyd/rds-proxy-password-rotation/tree/189452aa90a81624aa4adb67a05098c7e6a4aa9a

Workflow

Publishing configuration: github.com/Hapag-Lloyd/rds-proxy-password-rotation/blob/189452aa90a81624aa4adb67a05098c7e6a4aa9a/.github/workflows/pypi_publish.yml
Publishing logs: github.com/Hapag-Lloyd/rds-proxy-password-rotation/actions/runs/34240144201/attempts/1

Artifact

Subject: rds_proxy_password_rotation-0.6.534-py3-none-any.whl
SHA-256 checksum: f4b889c147ec25c996615d5b60fa79778cccc41d8d0241404966a85cf46314e3 Verifying attestations