HashiCorp Developer AI Private beta now available Sign up today
Terraform
Terraform Home

You are viewing documentation for version v202409-1. View latest version.

Configure external PostgreSQL connection

This topic describes how to configure Terraform Enterprise to connect to an external PostgreSQL database. You only need to complete this task to operate Terraform Enterprise in active-active or external mode, which instructs Terraform Enterprise to store and retrieve data in an externally-managed database. If you prefer to allow Terraform Enterprise to manage the database, configure Terraform Enterprise to run in disk mode. Refer to Configure operational mode for additional information.

Introduction

Terraform Enterprise stores stateful application data, such as, workspace settings, organization settings, run information, and user information in a PostgreSQL database. Complete the following steps to configure Terraform Enterprise to store and retrieve the data in an externally-managed PostgreSQL database:

  1. Prepare the PostgreSQL server to host the data. Preparation includes creating a user appropriate permissions and creating the extensions in the database.
  2. Specify the connection settings in your deployment configuration. If your server requires additional connection parameters, you must also specify them in the configuration.

Requirements

Before proceeding, verify that you meet the following requirements.

Server

One of the following servers is required:

  • PostgreSQL server, such as Amazon RDS for PostgreSQL, version 12.x, 13.x, 14.4 and up, or 15.x.

    Note that PostgreSQL v12 will reach end of life on November 12, 2024. As a result, Terraform Enterprise will no longer v12 after that date.

  • PostgreSQL-compatible server, such as Amazon Aurora PostgreSQL.

User

Create a PostgreSQL user with the following permissions on the database:

  • Permissions to create, modify, and read all tables and indices on all schemas within the database. Database owners commonly have these permissions.
  • Permissions to create extensions. If you are unable to create a user with the CREATE EXTENSION privilege, refer to Create extensions for instructions on creating the necessary extensions.

Create extensions

Create extensions for the rails, vault, registry, and task_worker PostgreSQL schemas. The database server automatically creates these schemas if they do not already exist.

Run the following commands on the PostgreSQL server to create the extensions:

CREATE EXTENSION IF NOT EXISTS "hstore" WITH SCHEMA "rails";
CREATE EXTENSION IF NOT EXISTS "uuid-ossp" WITH SCHEMA "rails";
CREATE EXTENSION IF NOT EXISTS "citext" WITH SCHEMA "registry";

Specify PostgreSQL connection settings

Add the following settings to your Terraform Enterprise configuration:

  • Set the TFE_DATABASE_HOST variable to the location of your PostgreSQL server. Format the location as HOST[:PORT], for example db.example.com or db.example.com:5432.
  • Set the TFE_DATABASE_NAME variable to the name of the database you want to store the data in.
  • Set the TFE_DATABASE_USER variable to the user name you want to use to access the database.
  • Set the TFE_DATABASE_PASSWORD variable to the password for the user.

Refer to Database settings in the configuration reference for additional information.

Additional connection parameters

Add the TFE_DATABASE_PARAMETERS variable to your configuration and specify any additional connection parameters necessary to connect to the server.

sslmode

When providing extra keyword parameters for the database connection, the sslmode parameter only allows the following values:

When operating Terraform Enterprise in external mode, the sslmode parameter is set to require by default. When operating Terraform Enterprise in disk mode, the sslmode parameter is set to disable by default.

Terraform Enterprise provides a certificates file at /etc/ssl/private/terraform-enterprise/bundle.pem, which is required by the verify-full and verify-ca modes.

Refer to the PostgreSQL library documentation for additional information about using sslmode.

Client certificate configuration

Terraform Enterprise does not support PostgreSQL client certificates configuration due to the limitation of storing certificate files for the sslcert and sslkey connection parameters. Refer to Client Certificates in the PostgreSQL documentation for additional information.