RDS - Gorbit Documentation

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

Guide

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

Configure database settings

Set up your database identifier, credentials, and instance configuration.Settings:

Set a descriptive DB instance identifier like gorbit-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 Gorbit.

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 Gorbit instance
Set Public access to “No” for production (recommended)
Choose your preferred Availability Zone

Click Create database to launch your RDS instance.

Configure Gorbit environment variables

Once your RDS instance is running, configure Gorbit 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>"

Gorbit 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 Gorbit to connect using short-lived IAM credentials.

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

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 gorbituser LOGIN;
GRANT rds_iam TO gorbituser;
ALTER ROLE gorbituser WITH NOINHERIT;
GRANT CREATE ON DATABASE <your-db-name> TO gorbituser;
GRANT USAGE ON SCHEMA public TO gorbituser;
GRANT CREATE ON SCHEMA public TO gorbituser;

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>/gorbituser"
    }
  ]
}

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.

Configure Gorbit 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=gorbituser

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: "gorbituser"

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

Restart Gorbit

Restart your Gorbit instance to apply the changes.

Docker

docker compose -f docker-compose.dev.yml -p gorbit-stack up -d --build --force-recreate

kubectl

kubectl rollout restart deployment

For more details, see the AWS RDS IAM Authentication documentation.

​Guide

​Optional: Enable IAM Authentication

Guide

Optional: Enable IAM Authentication