Skip to content

RDS IAM

PgDog supports obtaining temporary credentials from AWS IAM and using those to connect to RDS PostgreSQL (and Aurora) instances.

Configuration

To use RDS IAM authentication, configure it on each user in users.toml, for example:

[[users]]
name = "pgdog"
database = "prod"
password = "hunter2"
server_auth = "rds_iam"

users:
  - name: pgdog
    database: prod
    password: hunter2
    serverAuth: rds_iam

How it works

Under the hood, PgDog is using the AWS RDS SDK to fetch credentials at runtime. The SDK can retrieve temporary credentials from the environment or from the EC2 IAM API. It will use the role assigned to the EC2 instance or Kubernetes pod to connect to RDS.

If you're deploying PgDog in Kubernetes using our Helm chart, you can assign the PgDog container an IAM role with the correct permissions, for example:

values.yaml
serviceAccount:
  create: true
  annotations:
    eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/pgdog-role"

Client authentication

RDS IAM authentication is currently only supported for connections between PgDog and PostgreSQL. Clients need to continue using one of the supported authentication mechanisms, e.g., password auth.

To completely avoid using passwords for user authentication, take a look at mTLS.

Multiple roles

PgDog supports assuming different roles for each user in order to connect to RDS. This is common when deploying PgDog across different AWS accounts or regions.

For each user in users.toml, you can specify its IAM role (and optionally IAM region) as follows:

[[users]]
name = "pgdog"
database = "prod"
password = "hunter2"
server_auth = "rds_iam"
server_iam_region = "us-west-2"
server_iam_assume_role = "arn:aws:iam::123456789012:role/pgdog-role-us-west-2"

users:
  - name: pgdog
    database: prod
    password: hunter2
    serverAuth: rds_iam
    serverIamRegion: us-west-2
    serverIamAssumeRole: arn:aws:iam::123456789012:role/pgdog-role-us-west-2

In order for this to work correctly, make sure the IAM role used to deploy PgDog has the correct Trust Policy to assume all roles specified in the configuration.

Read more

TLS

Configure encrypted connections for applications connecting to PgDog and PgDog's connections to the database.

mTLS

Passwordless authentication for application connections to PgDog.