Introduction
This Knowledge Base article documents a behavior observed in Terraform Enterprise when configuring different authentication methods for the primary TFE database and the Explorer database.
Specifically, the issue occurs when the main TFE database uses Google IAM passwordless authentication, while the Explorer database continues to use password-based authentication.
The configuration unexpectedly fails and causes TFE pods to continuously restart, resulting in the application becoming unavailable.
Problem
When the following setup is attempted:
Main TFE database: IAM authentication enabled
(TFE_DATABASE_PASSWORDLESS_GOOGLE_USE_DEFAULT_CREDENTIALS="true")Explorer database: Password authentication
(TFE_EXPLORER_DATABASE_PASSWORDprovided)
TFE is unable to start. Both pods remain in a CrashLoopBackOff, with 0/2 Ready and health checks failing.
Key Error Messages
FATAL: empty password returned by client (SQLSTATE 28P01)
PG::ConnectionBad: password authentication failed for user "admin-tfe-explorer"
TFE attempts to use IAM authentication for both the main and Explorer databases, causing the Explorer database connection to fail because it expects a password.
Prerequisites
- You are running Terraform Enterprise version 1.1.1 with Explorer feature enabled
- Using passwordless IAM authentication for the primary TFE database while configuring the Explorer database with password-based authentication.
Cause
This behavior occurs because:
TFE_DATABASE_PASSWORDLESS_GOOGLE_USE_DEFAULT_CREDENTIALS is a global setting.
Once enabled, it forces all database connections inside TFE including the Explorer database to use IAM passwordless authentication.
At this time:
TFE does NOT support mixed database auth modes
(IAM for primary DB + password for Explorer DB)There is no environment variable available to independently configure IAM for only the Explorer database.
Engineering confirmed this as a product limitation and a bug has been created to track the issue. ( Article will be update with release version once it is fixed )
Solutions/Workaround:
Until mixed-mode authentication is supported, use one of the following supported configurations:
Option 1 — Use Password Authentication for Both Databases (Recommended)
Set:
TFE_DATABASE_PASSWORDTFE_EXPLORER_DATABASE_PASSWORD
Leave IAM disabled.
This configuration works reliably.
Option 2 — Use IAM Authentication Only for Main Database and Disable Explorer
Enable IAM:
TFE_DATABASE_PASSWORDLESS_GOOGLE_USE_DEFAULT_CREDENTIALS="true"But do not configure the Explorer database.