Enable Explorer on Terraform Enterprise

Note

This feature is currently in beta. Do not use beta functionality in production environments.

This topic contains reference information about the configurations you can specify to run Explorer on Terraform Enterprise. The Explorer beta is available with Terraform Enterprise 1.0.0.

Warning

Do not enable Explorer in production environments. Updates that we push during non-GA phases may require you to destroy the Explorer database. Additionally, running the explorer may increase the load on the Terraform Enterprise server in unexpected ways, resulting in slowdowns or outages.

You can provide feedback on this feature by selecting Give Feedback from the Actions menu or by contacting your account team.

Introduction

Complete the following steps to enable Explorer:

Provide a new database. This database is in addition to the database required for using external or active-active mode.
Specify environment variables that enable Explorer and to store Explorer data. Add the variables to the configuration file for your runtime environment, such as a Docker Compose file, Kubernetes Helm chart, or in the env block of your Nomad job. Refer to Create deployment configuration overview for additional information.

Requirements

Explorer beta is available in Terraform Enterprise 1.0.0.
You must perform a Terraform run for Explorer to collect data. Upgrading to Terraform Enterprise 1.0.0 does not retroactively populate the database.
You can only use Explorer when running in external or active-active operational modes.
Authentication to the Explorer database only support usernames and passwords. You cannot use passwordless or other authentication methds.

Database requirements

We will conduct performance testing throughout the beta, which may result in changing guidelines. We recommend creating an Explorer database that is approximately 25-50% the size of your main Terraform Enterprise database.

You may also need to slightly increase the size of your Redis instance due to the increased load. We recommend monitoring the resource utilization of all your external services in addition to the Terraform Enteprise nodes.

Upon the first start, Terraform Enterprise creates a schema named explorer if it does not already exist. You can also pre-create the schema if necessary. No extensions need to be installed.

Explorer settings

Configure the following settings to enable Explorer.

`TFE_EXPLORER_DATABASE_HOST`

The PostgreSQL server to connect to. Use the HOST[:PORT] format, for example, db.example.com or db.example.com:5432. If only HOST is provided then the :PORT defaults to :5432. Multi host connection strings are not supported.

Setting this variable enables the Explorer feature.

`TFE_EXPLORER_DATABASE_NAME`

Name of the PostgreSQL database to store the Explorer data in.

Required to use Explorer.

`TFE_EXPLORER_DATABASE_USER`

PostgreSQL username.

Required to use Explorer.

`TFE_EXPLORER_DATABASE_PASSWORD`

PostgreSQL password.

Required to use Explorer.

`TFE_EXPLORER_DATABASE_PARAMETERS`

PostgreSQL server parameters for the connection URI. Used to configure the PostgreSQL connection, for examplesslmode=require.