Startup checks

Terraform Enterprise startup checks validate the supplied configuration to prevent operators from starting Terraform Enterprise with invalid configurations, invalid certificates or other issues that could prevent the application from running successfully or safely.

Startup checks:

Run concurrently at startup
Cannot be skipped
Have a 1 minute timeout

The results of the startup checks are logged alongside application logs. When all of the startup checks pass, the application will continue to start up.

2023-06-30T17:54:58.628Z [INFO]  terraform-enterprise: check passed: name=configuration duration="29.741µs"
2023-06-30T17:54:58.628Z [INFO]  terraform-enterprise: check passed: name=database duration=10.053393ms
2023-06-30T17:54:58.628Z [INFO]  terraform-enterprise: check passed: name=disk duration="169.438µs"
2023-06-30T17:54:58.628Z [INFO]  terraform-enterprise: check passed: name=license duration=7.896534ms
2023-06-30T17:54:58.628Z [INFO]  terraform-enterprise: check passed: name=redis duration="632.735µs"
2023-06-30T17:54:58.628Z [INFO]  terraform-enterprise: check passed: name=tls duration="241.12µs"

If any of the startup checks fail, the application will log the checks that failed and exit. Operators can check the logs for information on how they can resolve the failing checks.

2023-06-30T18:14:45.792Z [INFO]  terraform-enterprise: check passed: name=configuration duration="102.266µs"
2023-06-30T18:14:45.792Z [INFO]  terraform-enterprise: check passed: name=database duration=11.925026ms
2023-06-30T18:14:45.792Z [INFO]  terraform-enterprise: check passed: name=disk duration="360.432µs"
2023-06-30T18:14:45.792Z [ERROR] terraform-enterprise: check failed: name=license duration="423.448µs" err="failed parsing license: incorrectly formatted license"
2023-06-30T18:14:45.792Z [INFO]  terraform-enterprise: check passed: name=redis duration="945.784µs"
2023-06-30T18:14:45.792Z [INFO]  terraform-enterprise: check passed: name=tls duration="795.072µs"
2023-06-30T18:14:45.792Z [ERROR] terraform-enterprise: the following startup checks failed: checks=["license"]
2023-06-30T18:14:45.792Z [ERROR] terraform-enterprise: startup: error="startup checks failed"

Types of checks

Startup checks run the following validations to detect misses and gaps during the setup of the installation.

Configuration Variables

Validate required configuration and acceptable values for Flexible Deployment Options, listed in the install configuration page.

Database

Validates database access by querying for the supported version. When database connection fails, it will retry using a linear backoff strategy. For external database configuration, the following must be set and are used for validation.

The database validation can fail for the following reasons:

The database user set via TFE_DATABASE_USER has insufficient permissions to execute the query: SHOW server_version;
The Postgres database version is a value other than 12, 13, 14 or 15.

Filesystem access

This validation only applies to application running TFE_OPERATIONAL_MODE: disk on Docker runtime.

Validates the application has read / write privileges in the directory configured in TFE_DISK_PATH. This filesystem access validation can fail for the following reasons:

The application has no privilege to read / write files to the directory and its subdirectories configured in TFE_DISK_PATH.

License

Validate the application has read privilege to the license, and is a valid HashiCorp provided license. The license validation will not fail if the license is expired. It can fail for the following reasons:

The license value was not provided via TFE_LICENSE or TFE_LICENSE_PATH is empty.

Redis

Validate the application's connectivity to Redis. When connection fails, it will retry using a linear backoff strategy. For external Redis configuration, the following must be set and are used for validation:

TFE_REDIS_HOST
If TFE_REDIS_USE_TLS is set to true the application will use rediss instead of redis as the scheme.
If TFE_REDIS_USE_AUTH is set to true the application will use the credentials provided by TFE_REDIS_PASSWORD and TFE_REDIS_USER (optional) for authentication.

TLS certificates

Validate the presence of TFE_TLS_CA_BUNDLE_FILE and it is a valid PEM-encoded file.