Startup checks reference
This topic contains reference information about Terraform Enterprise startup checks. The startup checks validate the configuration in order to prevent operators from starting Terraform Enterprise with invalid certificates and 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.
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.
Types of checks
Startup checks run the following validations to detect misses and gaps during the setup of the installation.
Configuration Variables
This check validates required configuration and acceptable values listed in the installation configuration reference.
Database
This check validates database access by querying for the supported version. When the 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
or15
.
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
This check validates that the application has read privilege to the license and that it is a valid HashiCorp-provided license. License validation does not fail if the license is expired, but it can fail for the following reasons:
- The license value was not provided via
TFE_LICENSE
orTFE_LICENSE_PATH
is empty.
Redis
This check validates the application's connectivity to Redis. When the connection fails, the check retries using a linear backoff strategy. For external Redis configurations, you must set the following variables:
TFE_REDIS_HOST
- If
TFE_REDIS_USE_TLS
is set totrue
the application will userediss
instead ofredis
as the scheme. - If
TFE_REDIS_USE_AUTH
is set totrue
the application will use the credentials provided byTFE_REDIS_PASSWORD
andTFE_REDIS_USER
(optional) for authentication.
TLS certificates
This check validates that the TFE_TLS_CA_BUNDLE_FILE
variable has been set and that it points to a valid PEM-encoded file.
Upgrade
This check ensures that upgrades to Terraform Enterprise occur in a sequential manner and do not forego required Terraform Enterprise releases. The upgrade check fails and logs error messages if the following conditions apply:
A Terraform Enterprise instance is trying to upgrade to a version of the application that is not newer than the current version:
"failed validating TFE version: vYYYYMM-P is not newer than existing version vYYYYMM-P"
A Terraform Enterprise instance has skipped over required releases:
"failed to meet upgrade requirements: missing required releases: vYYYYMM-P, vYYYYMM-P"
Kubernetes
This validation applies to TFE_RUN_PIPELINE_KUBERNETES_POD_TEMPLATE
, if provided. It ensures that the template is a valid corev1.PodTemplateSpec
and contains no more than one corev1.Container
.