AWS RDS IAM Authentication for PostgreSQL

Harbor supports AWS RDS IAM authentication for all PostgreSQL database connections. When enabled, Harbor’s backend services obtain short-lived IAM-issued tokens instead of using a static database password, integrating with AWS Identity and Access Management for database-level access control.

This is an infrastructure-level configuration — it affects how Harbor’s services connect to the database, not how end users authenticate to Harbor itself.

How It Works

When IAM authentication is enabled, each new database connection is authenticated using a token generated from the IAM credentials available to the service (for example, via an IRSA-attached service account). The connection lifetime is capped at 14 minutes to stay within IAM token validity windows. SSL mode is automatically forced to require when IAM auth is active.

The AWS region is resolved from POSTGRESQL_AWS_REGION first, falling back to AWS_REGION if that variable is not set. This means standard IRSA environments that already set AWS_REGION require no additional region configuration.

Prerequisites

PostgreSQL is running on AWS RDS with IAM database authentication enabled. See the official AWS RDS documentation for IAM database authentication setup.
The IAM role attached to your Harbor workload (for example, via IRSA) has the rds-db:connect permission for the target database user.
Your Harbor deployment can reach the RDS endpoint over SSL.

Configuration

IAM authentication is configured per service via environment variables. The following variables must be set on every Harbor service that connects to PostgreSQL — at minimum core and jobservice.

Environment Variable	Description	Required
`POSTGRESQL_USE_IAM_AUTH`	Set to `true` to enable IAM authentication.	Yes
`POSTGRESQL_AWS_REGION`	AWS region for token generation. Falls back to `AWS_REGION` if unset.	No (if `AWS_REGION` is set)

When POSTGRESQL_USE_IAM_AUTH=true, SSL mode is automatically set to require regardless of any other SSL configuration.

Helm Deployment

For AWS-native deployments using the Harbor Helm chart, set the corresponding values in your values.yaml or via --set. Reference Helm values for IAM auth are included in the chart’s AWS deployment guide. Refer to the chart documentation for the exact value paths for each component.

Enabling on Core and Jobservice

Both core and jobservice must have POSTGRESQL_USE_IAM_AUTH configured. If jobservice is missing the IAM auth configuration, it will crash on startup. Ensure the variables are propagated to all services, not only core.

IAM auth is also supported in the exporter and the standalone database migrator components.

Steps

Enable IAM database authentication on your AWS RDS PostgreSQL instance and grant the rds-db:connect permission to the IAM role used by your Harbor workload. See the official AWS RDS IAM authentication documentation for the required IAM policy and database user setup.
Ensure the IAM role is available to the Harbor pods — for example, by annotating the Kubernetes service account with the IRSA role ARN.
Set the following environment variables on each Harbor service (core, jobservice, exporter, and the database migrator if used):
```
POSTGRESQL_USE_IAM_AUTH=true
POSTGRESQL_AWS_REGION=<your-aws-region>
```
If your environment already provides AWS_REGION, you may omit POSTGRESQL_AWS_REGION.
Remove or leave blank any static POSTGRESQL_PASSWORD value — it is not used when IAM auth is active.
Restart all affected Harbor services and verify they connect successfully to the database.

Reference

Variable	Default	Notes
`POSTGRESQL_USE_IAM_AUTH`	`false`	Set to `true` to activate IAM auth.
`POSTGRESQL_AWS_REGION`	(empty)	Falls back to `AWS_REGION` if unset.
SSL mode	`disable` (normally)	Forced to `require` when IAM auth is enabled.
Max connection lifetime	N/A (normally)	Capped at 14 minutes when IAM auth is enabled.

Troubleshooting

Jobservice crashes on startup Confirm that POSTGRESQL_USE_IAM_AUTH and POSTGRESQL_AWS_REGION are set on the jobservice component, not only on core. Missing IAM auth config on jobservice is a known cause of startup failures.

Connection refused or SSL errors IAM auth requires SSL. Verify that your RDS instance accepts SSL connections and that no other configuration is explicitly setting SSL mode to disable.

Token generation failures / region errors Check that POSTGRESQL_AWS_REGION or AWS_REGION is set and matches the region where your RDS instance is deployed. In IRSA setups, confirm the service account annotation and the IAM role trust policy are correct. See the official AWS IRSA documentation for trust policy configuration.

Access denied on database connection Verify that the IAM role has the rds-db:connect permission scoped to the correct database user and RDS resource ARN. See the official AWS RDS IAM authentication documentation for permission requirements.