Using AWS RDS provides a managed PostgreSQL database for Onyx. This guide covers both basic and IAM authentication for enhanced security.

​
Guide

1

Create an RDS PostgreSQL instance

Navigate to the Amazon RDS console and create a new PostgreSQL database.
  • Click Create database
  • Select PostgreSQL as the engine type
  • Choose Standard create for the creation method
  • Select your preferred PostgreSQL version
  • Choose Production or Dev/Test template as needed
2

Configure database settings

Set up your database identifier, credentials, and instance configuration.Settings:
  • Set a descriptive DB instance identifier like onyx-prod-db
  • Set Master username (e.g., postgres)
  • Set a strong Master password and confirm it
Instance configuration:
  • Choose an appropriate Instance class (e.g., db.t3.micro for testing, db.t3.medium for production)
  • Configure Storage size and enable autoscaling if needed
Save your database credentials securely - you’ll need them to configure Onyx.
3

Configure connectivity and security

Set up network access and security groups for your database.
  • Select your VPC and Subnet group
  • Configure VPC security group to allow access from your Onyx instance
  • Set Public access to “No” for production (recommended)
  • Choose your preferred Availability Zone
Click Create database to launch your RDS instance.
4

Configure Onyx environment variables

Once your RDS instance is running, configure Onyx to connect to it.Get your database details from the RDS console:
  • Endpoint: Found in the RDS instance details
  • Port: Typically 5432
  • Database name: Your database name or postgres if using default
For Docker deployments, add these variables to your .env file:
USE_IAM_AUTH=false
POSTGRES_HOST=<your-rds-endpoint>
POSTGRES_PORT=5432
POSTGRES_DB=<your-database-name>
POSTGRES_USER=<your-master-username>
POSTGRES_PASSWORD=<your-master-password>
For EKS deployments, add these to your values.yaml file:
auth:
  secrets:
    POSTGRES_PASSWORD: "<your-master-password>"
configMap:
  USE_IAM_AUTH: "false"
  POSTGRES_HOST: "<your-rds-endpoint>"
  POSTGRES_PORT: "5432"
  POSTGRES_DB: "<your-database-name>"
  POSTGRES_USER: "<your-master-username>"
Onyx will now connect to your RDS PostgreSQL instance using these credentials.

​
Optional: Enable IAM Authentication

For enhanced security, you can enable IAM database authentication instead of using static passwords. This allows Onyx to connect using short-lived IAM credentials.
1

Enable IAM authentication on RDS

Navigate to your RDS instance in the AWS console and enable IAM authentication.
  • Go to your RDS PostgreSQL instance
  • Click Modify
  • Under Database authentication, enable IAM database authentication
  • Click Continue, then Apply immediately
2

Create IAM database user

Connect to your database and create a user for IAM authentication.Using your master credentials, run these SQL commands:
CREATE ROLE onyxuser LOGIN;
GRANT rds_iam TO onyxuser;
ALTER ROLE onyxuser WITH NOINHERIT;
GRANT CREATE ON DATABASE <your-db-name> TO onyxuser;
GRANT USAGE ON SCHEMA public TO onyxuser;
GRANT CREATE ON SCHEMA public TO onyxuser;
3

Configure IAM policy

Create an IAM policy to allow database connections.Get your DbiResourceId or DbClusterResourceId:
aws rds describe-db-instances \
  --db-instance-identifier <your-db-instance-name> \
  --region <your-region>
Create this IAM policy, fill in the region, account-id, resource-id, and attach it to your EC2 instance role:
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "rds-db:connect",
      "Resource": "arn:aws:rds-db:<region>:<account-id>:dbuser:<resource-id>/onyxuser"
    }
  ]
}
4

Download SSL certificate

Download the RDS CA certificate bundle for secure connections.
wget https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem
The SSL certificate is required for IAM authentication to work properly.
5

Configure Onyx for IAM authentication

Update your environment variables to use IAM authentication.For Docker deployments, add these variables to your .env file:
USE_IAM_AUTH=true
AWS_REGION=<your-region>
POSTGRES_HOST=<your-rds-endpoint>
POSTGRES_PORT=5432
POSTGRES_DB=<your-database-name>
POSTGRES_USER=onyxuser
Mount the SSL certificate in your docker-compose.yml:
docker-compose-prod.yml
services:
  api_server:
    volumes:
      - ./rds-combined-ca-bundle.pem:/app/bundle.pem:ro
For Kubernetes deployments, add these to your values.yaml file:
configMap:
  USE_IAM_AUTH: "true"
  AWS_REGION: "<your-region>"
  POSTGRES_HOST: "<your-rds-endpoint>"
  POSTGRES_PORT: "5432"
  POSTGRES_DB: "<your-database-name>"
  POSTGRES_USER: "onyxuser"
Create a secret for the SSL certificate and mount it:
kubectl create secret generic bundle-pem-secret --from-file=rds-combined-ca-bundle.pem
Next, we’ll mount the certificate in all of our containers in the values.yaml file.Go through each container and replace the empty volumes and volumeMounts with the following:
volumes:
- name: rds-ca
    secret:
      secretName: bundle-pem-secret

volumeMounts:
  - name: rds-ca
    mountPath: "/app/bundle.pem"
    subPath: bundle.pem
    readOnly: true
6

Restart Onyx

Restart your Onyx instance to apply the changes.
Docker
docker compose -f docker-compose.dev.yml -p onyx-stack up -d --build --force-recreate
kubectl
kubectl rollout restart deployment
For more details, see the AWS RDS IAM Authentication documentation.