HashiTalks 2025 Learn about unique use cases, homelab setups, and best practices at scale at our 24-hour virtual knowledge sharing event. Register
Terraform
Terraform Home

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

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"
2023-06-30T17:54:58.628Z [INFO]  terraform-enterprise: check passed: name=upgrade duration=29.954ms"

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 [INFO]  terraform-enterprise: check passed: name=upgrade duration=29.954ms"
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

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

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 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

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 or TFE_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 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

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"