TRACECAT__DB_AUTH_MODE set to aws_iam or azure_entra, each Tracecat service signs a short-lived token with its cloud identity and sends it as the database password. Every new connection gets a valid token, so no service holds a database password. The default, password, keeps the existing password login. Redis has the same modes in REDIS_AUTH_MODE.
Settings
A token mode connects with these variables and refuses to start ifTRACECAT__DB_PASS, TRACECAT__DB_PASS__ARN or TRACECAT__DB_URI is set:
require encrypts the connection without checking the server’s certificate, and verify-ca checks the certificate’s CA but not the host name, so any certificate from that CA passes. Only verify-full checks that the server is the host you named. For a direct connection to the database, use verify-full and point PGSSLROOTCERT at the CA bundle, such as the RDS global bundle or /etc/ssl/certs/ca-certificates.crt for Azure.
aws_iam also reads TRACECAT__DB_AWS_REGION (default AWS_REGION) and TRACECAT__DB_AWS_IAM_HOST / TRACECAT__DB_AWS_IAM_PORT, the RDS endpoint the token is signed for (default TRACECAT__DB_ENDPOINT / TRACECAT__DB_PORT). azure_entra reads TRACECAT__DB_AZURE_CLIENT_ID, the managed identity’s client ID (default AZURE_CLIENT_ID).
Amazon RDS
1
Turn on IAM database authentication
2
Create the database user
As the master user, create the login and grant it
rds_iam:rds_iam turns off a role’s password login, so never grant it to the master user. With database roles, tracecat db roles upgrade --login aws_iam creates app, migrator and agent_runtime and grants them rds_iam for you.3
Allow each service's IAM role to connect
Look up the instance’s resource ID, which looks like Attach this statement to every IAM role a Tracecat service runs as (IRSA or Pod Identity on EKS, the task role on ECS). The resource is the With database roles, give the migrations Job’s role the same statement for
db-ABCDEFGHIJKLMNOPQRSTUVWXYZ:rds-db user ARN, not the instance ARN:/migrator instead of /app. Never use dbuser:<DbiResourceId>/* or share one policy between the two roles.Every pod or task on the app role can then log in as app, including executors that run workflow actions. Never grant it to the node’s instance role: every pod on the node could then log in as app. On EKS, set AWS_EC2_METADATA_DISABLED=true on Tracecat’s pods so a pod without its own identity fails instead of signing with the node role (the Helm chart sets it).4
Configure Tracecat
Download the RDS CA bundle and mount it into every Tracecat container, here at
/etc/tracecat/rds-global-bundle.pem (a Kubernetes ConfigMap or Secret volume, or an ECS bind mount):Azure Database for PostgreSQL
1
Turn on Microsoft Entra authentication
On the flexible server, enable Microsoft Entra authentication and set an Entra administrator. On AKS, turn on the cluster’s OIDC issuer and Workload Identity:
2
Create a managed identity for Tracecat
Create a user-assigned managed identity for Note each identity’s client ID and object ID; the next steps use both:Label the pods
app and federate it with each Kubernetes service account that Tracecat’s services run as (Workload Identity), never the migrations Job’s. With the Helm chart, list them from the render. Give the app identity no Azure role beyond its database and cache logins: the API, MCP server, tool gateway and the executors that run workflow code all hold it. With database roles, create two more the same way: one for migrator, federated with the migrations Job’s service account, and one for agent_runtime, with no federated credential. Give no one rights to use, assign or federate the agent_runtime identity. Run this once per identity and service account, with a credential name unique to each:azure.workload.identity/use: "true" and give them the client ID, in TRACECAT__DB_AZURE_CLIENT_ID or the service account annotation azure.workload.identity/client-id. Never assign the identity to the node pool: every pod on the node could then log in as app. Set AZURE_TOKEN_CREDENTIALS=WorkloadIdentityCredential so a pod without its projected token fails instead of using the node’s managed identity (the Helm chart sets it).3
Create the database users
As the Entra administrator, connected to the With database roles (Tracecat 1.5.0-alpha.3 and earlier refuse the membership these calls give the Entra administrator in each role. On those versions, run
postgres database, map each database role to the object ID of the identity that logs in as it. Without database roles, create app only:tracecat db roles upgrade --login azure_entra), create all three login roles instead; role setup then grants their privileges. migrator maps to the migrations Job’s identity and app to the services’ identity. The agent runtime logs in as app too. Role setup needs agent_runtime to exist, but nothing logs in as it yet, so map it to its own identity that no workload uses:REVOKE app, migrator, agent_runtime FROM "<entra-admin>"; before role setup.4
Allow Tracecat's extensions
Azure only creates extensions that the server’s Then set it to With an empty list, use
azure.extensions parameter lists, and migrations need vector and pg_trgm. Setting the parameter replaces the whole list, so read it first:VECTOR,PG_TRGM plus every extension that printed, comma-separated:--value VECTOR,PG_TRGM.Then, as the Entra administrator, connected to the Tracecat database, create them (see pgvector for the version Tracecat needs):5
Configure Tracecat
DefaultAzureCredential, which caches each token and renews it before it expires.
If app, migrator or agent_runtime had a password before, clear it as the admin once the token login works, since Azure keeps password login on for these roles. Then unset TRACECAT__DB_APP_PASSWORD, TRACECAT__DB_MIGRATOR_PASSWORD and TRACECAT__DB_AGENT_RUNTIME_PASSWORD and delete them wherever you store them. Without database roles, run only the app statement:
Kubernetes with PgDog
The Helm chart’sexternalPostgres.auth.mode takes awsIam or azureWorkloadIdentity. Every Tracecat workload, the agent runtime included, then logs in to PgDog with a token, which PgDog passes through to the database. PgDog’s user takes auth_type = "external_token": PgDog checks each new token once by logging in to the database with it, as pgdog.serverUser, so serverUser must be the workloads’ username. The token modes need database roles: the migrations Job logs in directly, as migrator with a token of its own (see Migrations), and no workload needs externalPostgres.auth.existingSecret. Once the token login works, delete that Secret from the cluster and rotate the admin’s password, and keep the admin login with whoever manages the database. Delete any old externalPostgres.auth.appSecret and migrations.migrator.passwordSecret Secrets too, along with whatever provisions them. On Azure, also clear the roles’ old passwords.
Both modes need:
- PgDog v0.1.65 or newer, which has the token-cache fix (pgdog#1989). Set
pgdog.image.tagif your chart’s default is older. externalPostgres.sslMode: require, andexternalPostgres.tls.verifyCAwith the database’s CA incaCert. PgDog verifies the database with that CA; the chart rejectsverify-caandverify-fullwith PgDog.agentRuntime.durable.database.dsnSecretleft empty, so the agent runtime logs in as the workloads do.- An agent runtime image (
agentRuntime.image.tag) with token login. Check with the Tracecat team that your chart’s default includes it.
app until it expires.
Clients reach PgDog over TLS that doesn’t verify PgDog’s certificate. A token taken from that hop logs in to the database until it expires (15 minutes for an RDS token, up to about 24 hours for an Entra ID token), and through PgDog for up to 15 minutes longer: PgDog accepts a token for 15 minutes after each check with the database, then checks it again. Limit who can reach PgDog’s port with a Kubernetes NetworkPolicy that admits only Tracecat’s pods.
RDS IAM
The chart signs the tokens forexternalPostgres.host, so set it to the RDS endpoint.
Azure Workload Identity
Azure maps each Entra identity to one Postgres role, and PgDog checks the workloads’ tokens asserverUser. So the workloads and PgDog share the one identity mapped to app, with a federated credential for each service account. The migrations Job uses migrator’s own identity.
azure.workload.identity/use: "true" and passes clientId to the workloads and PgDog in the environment, so their service accounts need no annotation. Get caCert from Microsoft’s TLS certificates for Azure Database for PostgreSQL.
List the service accounts of the pods the chart labels, with the same chart reference, version and values you install with:
tracecat, that prints names such as tracecat-api, tracecat-app, tracecat-migrations and tracecat-pgdog. Federate the migrator identity with the one that ends in -migrations, which migrations.serviceAccount.annotations annotates, and the app identity with each of the others.
Migrations
Without database roles, the migrations Job logs in withexternalPostgres.auth.existingSecret. With them, it logs in as migrator (migrations.migrator, with login: aws_iam or login: azure_entra for a token of its own) and never as the admin; see Database roles. The token modes need migrations.migrator. The tracecat-admin migrate commands take a password URI only.
Redis
WithREDIS_AUTH_MODE set to aws_iam or azure_entra, Tracecat logs in to Redis with a token from its cloud identity and renews it before it expires. Tracecat then needs a rediss:// URL with no username or password.
Azure Managed Redis
1
Create the cache
Create the cache with TLS on (
Encrypted). Entra authentication works over TLS only, and Microsoft turns it on by default. Tracecat’s Redis client needs the EnterpriseCluster clustering policy. A new cache can start with access keys off:<sku> is a size such as Balanced_B1. On an existing cache, keep access keys on until every client logs in with Entra ID, then turn them off on its default database: turning them off closes every open connection.2
Allow the app identity
Assign the default access policy to the object ID of the identity mapped to
app (see Azure Database for PostgreSQL):3
Configure Tracecat
externalRedis.auth.existingSecret’s URL; once you list every component, remove it from your values and delete the Secret. clientId defaults to externalPostgres.auth.azureWorkloadIdentity.clientId:<cache-name>.redis.cache.windows.net and its TLS port is 6380.
Amazon ElastiCache
aws_iam logs each component in as its own ElastiCache IAM user, on a replication group (ElastiCache Serverless isn’t supported). Set REDIS_AWS_IAM_USER_ID, REDIS_AWS_IAM_REPLICATION_GROUP_ID and REDIS_AWS_REGION; the Helm chart sets them per component from externalRedis.auth.awsIam. Once every component logs in with IAM, remove the password user from the cache’s user group so the old URL stops working. See Environment variables for their formats.
Limitations
- The AWS Fargate Terraform doesn’t set
TRACECAT__DB_AUTH_MODEyet; Fargate deployments keep password login. - Self-hosted Temporal still logs in to its own database with a password. Give it its own database role and Secret, never the admin’s. A fully passwordless install needs Temporal Cloud or another external Temporal.
Related pages
- See Kubernetes for the rest of the Helm chart’s PostgreSQL and Redis settings.
- See Database roles to set up
app,migratorand read-only roles. - See Environment variables for every database and Redis setting.