Amazon RDS and Aurora
On Amazon RDS or Aurora PostgreSQL, each new connection in the query pool, cache pool, LISTEN/NOTIFY client, and migration Job signs a fresh 15-minute token with the pod's IAM role, so Archestra stores no database password.
- Network: set Public access to No, put the instance in private subnets, and allow port 5432 in its security group only from the cluster.
- TLS: IAM authentication always verifies the server certificate. The platform image ships the RDS CA bundle.
Prepare the Database and IAM Role
Enable IAM database authentication on your RDS or Aurora PostgreSQL instance, then connect as the master user to configure the archestra application database, required extensions, and IAM database role.
-
New database: Switch to the
archestradatabase first sovectorandpg_are installed in the application database, then create the IAM-enabled role and grant database and schema privileges:trgm sql\c archestra CREATE EXTENSION IF NOT EXISTS vector; CREATE EXTENSION IF NOT EXISTS pg_trgm; CREATE USER archestra_iam WITH LOGIN; GRANT rds_iam TO archestra_iam; GRANT ALL PRIVILEGES ON DATABASE archestra TO archestra_iam; GRANT ALL ON SCHEMA public TO archestra_iam; -
Existing Archestra database: Grant
rds_directly to the existing database role that owns Archestra's tables and sequences (for example,iam archestra) and keep that username inARCHESTRA_and theDATABASE_ URL rds-db:connectpolicy so table ownership and migration DDL (ALTER TABLE) privileges remain intact:sql\c archestra CREATE EXTENSION IF NOT EXISTS vector; CREATE EXTENSION IF NOT EXISTS pg_trgm; GRANT rds_iam TO archestra;If you must switch an existing database from its original owner role (
archestra) to a separatearchestra_role, also transfer object ownership and privileges in theiam archestradatabase so both application DML and migration DDL succeed:sql\c archestra CREATE USER archestra_iam WITH LOGIN; GRANT rds_iam TO archestra_iam; GRANT ALL PRIVILEGES ON DATABASE archestra TO archestra_iam; GRANT ALL ON SCHEMA public TO archestra_iam; GRANT archestra TO archestra_iam; REASSIGN OWNED BY archestra TO archestra_iam; GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO archestra_iam; GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO archestra_iam; GRANT ALL PRIVILEGES ON ALL FUNCTIONS IN SCHEMA public TO archestra_iam;
Attach an IAM policy to the pod's IAM role allowing rds-db:connect for the RDS resource ID (DbiResourceId) and database username:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "rds-db:connect",
"Resource": "arn:aws:rds-db:eu-west-1:123456789012:dbuser:db-ABCDEFGHIJKLMNOPQRSTUVWX/archestra_iam"
}
]
}
Configure the Helm Chart on Amazon EKS
On Amazon EKS, set archestra.database.iamAuth.enabled: true and archestra.database.iamAuth.roleArn (for IRSA) or bind the role with EKS Pod Identity:
postgresql:
enabled: false
archestra:
database:
iamAuth:
enabled: true
# Annotates the platform ServiceAccount with eks.amazonaws.com/role-arn (omit when using EKS Pod Identity):
roleArn: arn:aws:iam::123456789012:role/archestra-rds-iam-role
# Optional override when the endpoint hostname does not embed the AWS region
# (TLS hostname verification checks the URL hostname against the server certificate,
# so the URL must use an endpoint name covered by the certificate):
# awsRegion: eu-west-1
env:
ARCHESTRA_DATABASE_URL: postgresql://archestra_iam@mydb.123456789012.eu-west-1.rds.amazonaws.com:5432/archestra?sslmode=verify-full
The platform image includes the AWS RDS global CA bundle at /etc/ssl/certs/cloud-database-ca-bundle.pem and verifies the server certificate and URL hostname on every connection (sslmode=no-verify is rejected under IAM auth); use an endpoint hostname covered by the server certificate (such as the RDS instance, cluster, or RDS Proxy endpoint, or a custom certificate covering your alias).
Clusters Outside AWS
When running outside AWS with network connectivity to RDS on port 5432, you can authenticate using either OIDC federation or Kubernetes Secrets:
-
OIDC federation (recommended): Register your cluster's OIDC issuer in AWS IAM and enable
injectWebIdentityTokenVolumeso the chart mounts a projectedsts.amazonaws.comServiceAccount token volume and setsAWS_andROLE_ ARN AWS_on web, worker, and migration Job pods:WEB_ IDENTITY_ TOKEN_ FILE yamlpostgresql: enabled: false archestra: database: iamAuth: enabled: true roleArn: arn:aws:iam::123456789012:role/archestra-rds-iam-role injectWebIdentityTokenVolume: true env: ARCHESTRA_DATABASE_URL: postgresql://archestra_iam@mydb.123456789012.eu-west-1.rds.amazonaws.com:5432/archestra?sslmode=verify-full -
Secret-backed AWS credentials: Supply
AWS_,ACCESS_ KEY_ ID AWS_, and optionalSECRET_ ACCESS_ KEY AWS_throughSESSION_ TOKEN archestra.envFromSecrets(orarchestra.env, where the chart automatically storesAWS_andSECRET_ ACCESS_ KEY AWS_in a Kubernetes Secret).SESSION_ TOKEN
Connect Through RDS Proxy
Put RDS Proxy in front of the database when you want failovers to stay behind one endpoint: Archestra keeps signing IAM tokens, now for the proxy, with no chart change. Archestra holds session state on most connections (prepared statements, LISTEN, advisory locks), so the proxy pins them and pools little; size the proxy for the same connection budget as the database.
-
Create the proxy with IAM authentication for clients. With end-to-end IAM authentication, the proxy also signs in to the database with IAM and needs no Secrets Manager secret; the database user still needs
rds_, as in Prepare the Database and IAM Role.iam -
Allow
rds-db:connecton the proxy's resource ID (prx-…), not the database's:json{ "Effect": "Allow", "Action": "rds-db:connect", "Resource": "arn:aws:rds-db:eu-west-1:123456789012:dbuser:prx-ABCDEFGHIJKL01234/archestra_iam" } -
Point the URL at the proxy endpoint and run the Helm upgrade. It worked when the migration Job completes and the web pods turn ready:
yamlarchestra: env: ARCHESTRA_DATABASE_URL: postgresql://archestra_iam@archestra.proxy-abc123xyz.eu-west-1.rds.amazonaws.com:5432/archestra?sslmode=verify-full
- TLS: the proxy presents an AWS Certificate Manager certificate, which the platform image already trusts. Leave
sslrootcertunset, because the RDS CA bundle does not cover the proxy, and use the proxy endpoint name rather than a DNS alias. - Statement timeout: Archestra sends
ARCHESTRA_as a startup parameter, and RDS Proxy accepts only a fixed set of them. If connections fail with an error that namesDATABASE_ STATEMENT_ TIMEOUT_ MILLIS statement_, set it totimeout 0and set the timeout on the role instead:ALTER ROLE archestra_iam SET statement_timeout = '30s';.