TFE Restore Issues Caused by SSL mode Mismatch After RDS PostgreSQL Upgrade

Avatar
Konica Sethi
  • Updated

 

Introduction

This article describes a Terraform Enterprise (TFE) restore or rollback issue caused by an SSL mode mismatch in an AWS RDS PostgreSQL database during snapshot restoration. This scenario commonly occurs when restoring older PostgreSQL snapshots and may prevent Terraform Enterprise from starting or connecting to the database.

Problem

After restoring a PostgreSQL snapshot (for example PostgreSQL 12.x) for Terraform Enterprise, the following symptoms may occur:

  • Terraform Enterprise fails database health checks.

  • Errors such as context deadline exceeded appear in logs.

  • Database check failures are reported during startup.

  • Terraform Enterprise UI becomes inaccessible.

  • Database connectivity fails despite restoring the expected PostgreSQL snapshot.

Cause

The issue occurs due to an SSL configuration mismatch following an automatic PostgreSQL engine upgrade in AWS RDS during database snapshot restoration.

When restoring older PostgreSQL snapshots (for example PostgreSQL 12):

  • AWS RDS may automatically upgrade the database engine to a newer supported version (for example PostgreSQL 17).

  • This typically occurs when:

    • The original PostgreSQL version is nearing or past end of standard support.

    • AWS RDS Extended Support is not enabled.

    • The restore operation uses the default DB parameter group.

After the automatic upgrade:

  • Database parameter defaults may change, particularly SSL enforcement settings.

  • Terraform Enterprise may remain configured with SSL disabled based on the previous PostgreSQL version.

  • The upgraded RDS instance may enforce SSL by default.

This mismatch prevents Terraform Enterprise from successfully connecting to the database, leading to database health check failures, startup errors, and service availability issues.

Solutions

Solution 1 — Restore Using a Custom RDS Parameter Group (Recommended)

To prevent unintended PostgreSQL engine upgrades:

  • Create a custom RDS DB parameter group aligned with the required PostgreSQL version.

  • Disable automatic upgrade options where applicable.

  • Explicitly assign this custom parameter group during snapshot restoration.

This helps ensure:

  • Database version compatibility with Terraform Enterprise.

  • Preservation of parameter defaults, including SSL settings.

Solution 2 — Restore to a Supported PostgreSQL Version

If the original PostgreSQL version is no longer supported:

  • Restore the database to a supported intermediate version (for example PostgreSQL 15).

  • Confirm compatibility with Terraform Enterprise.

  • Validate parameter group configuration and SSL settings.

  • Reconnect Terraform Enterprise after verification.

Always refer to official compatibility requirements before proceeding.

Solution 3 — Align SSL Configuration

If connectivity issues persist after restore:

  • Review SSL settings in the RDS parameter group.

  • Confirm whether SSL enforcement is enabled (for example the rds.force_ssl parameter).

  • Ensure Terraform Enterprise database configuration matches the database SSL mode.

  • Restart Terraform Enterprise services after configuration changes.

Outcome

Successful resolution typically includes:

  • Database engine version aligned with Terraform Enterprise compatibility.

  • Database health checks passing.

  • Terraform Enterprise UI accessible.

  • Terraform runs completing successfully.

Additional Information

Articles in this section

See more