Passwordless authentication for RDS

Spacelift can connect to an AWS RDS database using IAM database authentication instead of a password.

This is optional and disabled by default. Password authentication continues to work as before.

How it works

When a backend service opens a database connection, it generates an RDS auth token and uses it as the password. The token is generated locally using SigV4 from the cluster endpoint and database username. No AWS API call is made, so generating a token does not add network latency or consume an AWS API quota.

The IAM role used by the service needs rds-db:connect permission for the database user. The reference architecture modules add this permission to the relevant task roles.

An auth token is valid for 15 minutes. It only needs to be valid while the connection is being established. Existing connections continue working after the token expires.

Note

The service needs working AWS credentials because the IAM role is used for authentication. On ECS this is the task role; on EKS it is the IRSA service account role. The modules configure these roles.

Create the database user

Terraform cannot create this user because creating it requires a PostgreSQL connection to the database. Connect as the master user and run:

CREATE USER spacelift_iam;
GRANT rds_iam TO spacelift_iam;
GRANT spacelift TO spacelift_iam;

rds_iam is a built-in role available on every RDS PostgreSQL cluster. Adding the user to this role enables IAM authentication for that user. See the AWS documentation for Using IAM authentication with PostgreSQL.

The username must match the value passed to the modules below, including case.

The spacelift grant makes the new user a member of the spacelift role. This role owns the tables created by the migrations. Since the user inherits the role's permissions, new tables created by later upgrades do not require additional grants.

Do not grant rds_iam to the master user

For PostgreSQL, adding rds_iam to a user makes IAM authentication take precedence over password authentication for that user. Do not add it to the master user, as this would also disable password-based break-glass access.

Always create a separate user for IAM authentication.

Configure the modules

ECSEKS

Set rds_iam_auth on terraform-aws-ecs-spacelift-selfhosted v3.1.0 or later:

rds_iam_auth = {
  cluster_resource_id = module.spacelift-infra.rds_cluster_resource_id
  db_username         = "spacelift_iam"
}

cluster_resource_id is the cluster's resource ID (cluster-ABC...), not its identifier. The module does not create the database, so this value must be provided.

The module grants rds-db:connect and enables DATABASE_IAM_AUTH on the services.

You also need to use the passwordless connection string. With terraform-aws-spacelift-selfhosted v3.2.0 or later, set rds_iam_username = "spacelift_iam". The existing secret will then contain DATABASE_IAM_URL and DATABASE_IAM_READ_ONLY_URL alongside the existing password-based URLs.

Change the service configuration to use the IAM URLs:

 sensitive_env_vars = [
   {
     name      = "DATABASE_URL"
-    valueFrom = "${module.spacelift-infra.database_secret_arn}:DATABASE_URL::"
+    valueFrom = "${module.spacelift-infra.database_secret_arn}:DATABASE_IAM_URL::"
   },
   {
     name      = "DATABASE_READ_ONLY_URL"
-    valueFrom = "${module.spacelift-infra.database_secret_arn}:DATABASE_READ_ONLY_URL::"
+    valueFrom = "${module.spacelift-infra.database_secret_arn}:DATABASE_IAM_READ_ONLY_URL::"
   }
 ]

If you manage the database yourself, construct the connection string with the IAM username and no password.

Applying the Terraform changes registers new task definitions and rolls the services.

Set rds_iam_auth on terraform-aws-eks-spacelift-selfhosted v4.2.0 or later:

rds_iam_auth = {
  db_username = "spacelift_iam"
}

When the module creates the database, this is all that is required. The IAM roles get rds-db:connect, and the kubernetes_secrets output contains a passwordless connection string for the IAM user.

If you use an external database (create_database = false), also provide the cluster resource ID:

rds_iam_auth = {
  db_username         = "spacelift_iam"
  cluster_resource_id = "cluster-ABCDEFGHIJKLMNOPQRSTUVWXYZ"
}

The connection string is stored in a Kubernetes secret. After applying the Terraform changes, re-apply the output and restart the services:

tofu output -raw kubernetes_secrets | kubectl apply -f -
kubectl rollout restart deployment -n spacelift

If you do not use the kubernetes_secrets output, the same strings are available as the database_iam_url and database_iam_read_only_url outputs.

Going back to password authentication

The password-based connection strings are left unchanged. To switch back, remove rds_iam_auth, point the services back to DATABASE_URL and DATABASE_READ_ONLY_URL, and re-apply.

The master user's password authentication remains available, so it can still be used for break-glass access.