How to Enable sslmode=verify-full for an External PostgreSQL Database in Terraform Enterprise (Docker)

Steps

Introduction

Terraform Enterprise (TFE) deployed using the Flexible Deployment Option (FDO) with Docker supports connecting to external PostgreSQL databases over SSL/TLS.

Terraform Enterprise allows you to control database TLS behavior using the TFE_DATABASE_PARAMETERS setting. Supported sslmode values include:

• disable

• require

• verify-ca

• verify-full

When sslmode is set to verify-ca or verify-full, Terraform Enterprise validates the PostgreSQL server’s TLS certificate to ensure the connection is secure. This is commonly required in environments with strict security or compliance requirements.

This article explains how to correctly configure sslmode=verify-full for Terraform Enterprise deployed with Docker.

Expected Outcome

After completing this procedure:

• Terraform Enterprise starts successfully

• A secure TLS connection is established between Terraform Enterprise and the external PostgreSQL database

• The database server identity is verified using a trusted Certificate Authority (CA)

Prerequisites

• Terraform Enterprise version: v202309-1 or later

• Deployment type: Flexible Deployment Option (Docker)

• External PostgreSQL database (for example, AWS RDS PostgreSQL)

• Access to the CA certificate bundle that signs the PostgreSQL server certificate

• Ability to modify the Terraform Enterprise Docker Compose configuration

Note:
Starting with Terraform Enterprise v202309-1, the Terraform Enterprise container runs as a non-root user. The CA certificate must be mounted to a directory that is accessible to this user.

Use Case

Use this procedure when:

• Terraform Enterprise is deployed with Docker using FDO

• An external PostgreSQL database is used

• Security requirements mandate sslmode=verify-full or sslmode=verify-ca

Procedure

Step 1: Obtain the PostgreSQL CA Certificate

Download the CA certificate bundle used by your PostgreSQL database:

• For AWS RDS PostgreSQL, download the AWS RDS CA bundle.

• Save the certificate in PEM format (for example, aws_postgres.pem).

Step 2: Copy the Certificate to the TFE Host

Copy the CA certificate bundle to the Terraform Enterprise host machine.

Example location:

/home/ubuntu/fdo/certs/aws_postgres.pem

Ensure the file is readable by Docker.

Step 3: Configure the Docker Compose File

Edit your Terraform Enterprise Docker Compose configuration and:

1. Set TFE_DATABASE_PARAMETERS with sslmode=verify-full

2. Mount the CA certificate into the container

Example:

services:
  terraform-enterprise:
    environment:
      TFE_DATABASE_PARAMETERS: "sslmode=verify-full&sslrootcert=/rdsdbdata/rds-metadata/aws_postgres.pem"
    volumes:
      - type: bind
        source: /home/ubuntu/fdo/certs/aws_postgres.pem
        target: /rdsdbdata/rds-metadata/aws_postgres.pem

Step 4: Use a Supported Target Directory

The Terraform Enterprise container allows access to specific directories, including:

• /rdsdbdata/rds-metadata/

• /tmp

Ensure that the certificate is mounted to one of these directories. Mounting the certificate to directories such as /root will cause Terraform Enterprise to fail during startup.

Step 5: Start Terraform Enterprise

Start or restart Terraform Enterprise:

docker compose up --detach

Confirm that Terraform Enterprise starts successfully and no database-related startup errors are present in the logs.

Common Error and Resolution

Error

failed to configure TLS (unable to read CA file: open /root/server-cert.pem: no such file or directory)

Resolution

• Ensure the sslrootcert path matches the mounted certificate path

• Mount the certificate to a directory accessible by the non-root Terraform Enterprise user

• Restart Terraform Enterprise after updating the configuration

Additional Information

• AWS RDS SSL/TLS Documentation
  https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.SSL.html

• Terraform Enterprise Configuration Reference
  https://developer.hashicorp.com/terraform/enterprise/configuration