Enable Explorer on Terraform Enterprise

This topic contains reference information about the configurations you can specify to run Explorer on Terraform Enterprise.

Introduction

Complete the following steps to enable Explorer:

1. Provide a new database. This database is in addition to the database required for using external or active-active mode.
2. 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

• You can only use Explorer when running in external or active-active operational modes.
• Before running Explorer, you must ensure that any custom agents deployed to your Terraform Enterprise environment are on version v1.26 or greater, even if you have been running Explorer in previous versions of Terraform Enterprise. Otherwise, the backfill migration may fail.

Database requirements

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 Enterprise 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 example sslmode=require.

Explorer settings for passwordless IAM authentication

Configure the applicable settings for your installation to enable passwordless IAM authentication for the Explorer database.

TFE_EXPLORER_DATABASE_PASSWORDLESS_AWS_USE_INSTANCE_PROFILE

Whether to use Identity and Access Management (IAM) for Explorer database authentication. Defaults to false.

TFE_EXPLORER_DATABASE_PASSWORDLESS_AWS_REGION

AWS Region of the Explorer RDS PostgreSQL resource. Defaults to "".

TFE_EXPLORER_DATABASE_AUTH_USE_AZURE_MSI

Whether to use Managed Service Identity (MSI) for Explorer database authentication. Defaults to false.

TFE_EXPLORER_DATABASE_AUTH_AZURE_CLIENT_ID

Client ID of a user-assigned Managed Service Identity. Leave blank to use the system-assigned Managed Service Identity. Defaults to "".

TFE_EXPLORER_DATABASE_AUTH_USE_GCP_IAM

Whether to use Default Credentials for Explorer database authentication. Defaults to false.

Terraform Enterprise Explorer backfill process

The Explorer for visibility helps surface a wide range of valuable information from across your Terraform Enterprise organizations. When you first enable Explorer in a Terraform Enterprise instance, the Explorer database is populated with information drawn from the primary database. Terraform Enterprise completes this process in two stages.

The first stage checks each workspace in the primary database to see if it has the information needed by Explorer. If the Explorer information is not present, it is created from the information in the last run applied to that workspace.

• Explorer was introduced in Terraform Enterprise version 1.0.0. As a result, Terraform Enterprise only creates the information for workspaces that have not had a run in version 1.0.0 or later.

• During this stage, Terraform Enterprise writes warning messages to the logs that match the following pattern:

  "Update type <TYPE> (id: <ID>) missing association of type workspace".

  This is normal behavior while Explorer creates the missing data.

During the second stage, Terraform Enterprise populates the Explorer database with information about all organizations and workspaces in your system. Terraform Enterprise gets this information from the primary database.

Both of these processes run in the background, and you can use Terraform Enterprise while they are running. Data starts to appear in Explorer when the second stage begins, but Explorer will not show all of your organizations and workspaces until the stage is complete.

Explorer status endpoint

Call the /explorer-backfill-status API endpoint to monitor the status of the Explorer database backfill process. The endpoint requires authentication with an administrator API token.

GET /api/v2/admin/explorer-backfill-status

Request example

curl --header "Authorization: Bearer $TOKEN" \
  'https://my-tfe-hostname/api/v2/admin/explorer-backfill-status'

Response

The endpoint returns 200 OK with a JSONAPI structure containing the backfill status:

{
  "data": {
    "type": "explorer-status",
    "attributes": {
      "status": "not started"
    }
  }
}

The status attribute contains one of the following values: "not started", "in progress", or "done".

The endpoint returns a 4xx error code for invalid requests, including non-GET methods, missing or non-administrator authentication tokens, or when Explorer is not enabled.