Configure general Terraform Enterprise settings | Terraform

This topic describes how to configure general settings in Terraform Enterprise. General settings affect global behaviors, including 2FA, limits on creating organizations, service timeouts, HCP Terraform agent connections, and remote state sharing. Refer to the Admin Settings API documentation for instruction on how to configure general settings using the API.

Access General Settings

To access general settings, visit the site admin area and click Settings. To save the settings, click Save Settings.

Require Site Admins to Enable Two-factor Authentication

This setting can make the site more secure by requiring that admins enable two-factor authentication to access site admin functionality. You can use this setting in conjunction with SAML.

Admins that do not have two-factor authentication enabled may still log in, but will be unable to perform any admin-only functions until they enable and verify two-factor authentication.

You can use this setting in conjunction with SAML Single Sign On.

Organization Creation

Organization creation can be limited to site administrators or allowed for all users. Limiting organization creation to administrators means that the need for new organizations can be audited and their creation easily monitored.

When new user accounts are created, if they cannot create their own organizations, they will be unable to access any HCP Terraform resources until they are added to a team.

API Rate Limiting

By default, requests to the HCP Terraform API from a single user or IP address are limited to 30 requests per second to prevent abuse or hogging of resources. Since usage patterns may vary for a given instance, this can be updated to match local needs. A few endpoints have lower limits to prevent certain spam and abuse scenarios. If you receive a rate limited response, the limit will be reflected in the x-ratelimit-limit header once triggered.

HCP Terraform agents

HCP Terraform agents allow Terraform Enterprise to communicate with isolated, private, or on-premises infrastructure.

You can enable agents by clicking the Enable agents functionality checkbox.

Agents also use HTTP polling to acquire operations from Terraform Enterprise. This interval is the minimum number of seconds an agent should wait before polling for again in the event that there are no jobs to execute.

To set the minimum polling interval, enter a number in the Minimum polling interval in seconds field.

Note: Using a value that is significantly lower than the previous value may temporarily cause agents to report as Unknown because the agent may already be waiting for a longer period of time.

Refer to HCP Terraform agents on Terraform Enterprise for more details and requirements.

Health Assessments

Automatic Assessment Interval sets the minimum amount of time that must pass after a run or health assessment before a new health assessment can start. Decreasing the interval increases the frequency of health assessments. A high volume of concurrent runs and assessments in your organization may result in provider API rate-limiting or performance degradation.

Maximum concurrent assessments triggered sets the number of health assessments that can start for each polling event. HCP Terraform polls all workspaces every 5 minutes to check if they are due for an assessment. This setting prevents running assessments on all of your workspaces at once.

Note: If the previous polling event's assessments are still in progress, the number of concurrent active assessments may exceed the Maximum concurrent assessments triggered setting.

Organization and Workspace Limits

By default, you can create unlimited organizations and each organization can have unlimited workspaces. However, you can optionally limit these settings.

To limit organizations, check the Limit organizations per user box and enter a number in the Organizations per user limit field.

To limit workspaces, check the Limit workspaces per organization box and enter a number in the Workspaces per organization limit field.

Terraform Run Timeout Settings

The default timeout setting for Terraform runs are 2h for plans, and 24h for applies.

These are configurable on a global level, or in the Admin settings at an organization level.

Note: The maximum supported timeout for plans or applies is 24h.

Commit Statuses for Untriggered Speculative Plans

This setting affects Terraform Enterprise's behavior with shared VCS repositories that contain multiple Terraform configurations.

Workspaces that use part of a shared repository typically don't run plans for changes that don't affect their files; this includes speculative plans on pull requests. Since "pending" status checks can block pull requests, a workspace will automatically send passing commit statuses for any PRs that don't affect its files.

However, if this results in sending too many status checks to your VCS provider due to a large number of workspaces sharing one VCS repository, you can disable this behavior and ignore the pending status checks for unaffected workspaces.

The "Share state globally by default" admin setting determines the default value for the "Share state globally" setting on newly created workspaces.

When true, a newly created workspace will allow all workspaces in its organization to read its state.
When false, a newly created workspace will not allow any other workspaces to read its state.

In all cases, a workspace's state access settings can be changed after creation by workspace admins; this admin setting only affects the initial default value. Additionally, if the global-remote-state attribute is provided when creating a workspace via the API, the provided value will be used instead of using the default.

Refer to the following resources for more information:

Allow Speculative Plans on Pull Requests from Forks

This setting is supported for the following VCS providers: GitHub.com, GitHub.com (OAuth), GitHub Enterprise, Bitbucket Cloud, Azure DevOps Server, Azure DevOps Services.

By default, this setting is disabled because Terraform Enterprise assumes that forks of a trusted repository are not necessarily themselves trusted. Enabling this setting may allow Terraform Enterprise to execute malicious code or expose sensitive information through speculative plans on pull requests that originated from a repository fork.

Data Retention Policies

Data retention policies are exclusive to Terraform Enterprise and unavailable in HCP Terraform. Learn more about Terraform Enterprise.

By default, the Set data retention policy option is disabled. As a result, no data retention policy is active and Terraform Enterprise retains all data associated with configuration and state versions.

To set a global data retention policy, enable the Set data retention policy setting and choose a duration from the drop-down menu. When a duration is set, Terraform soft deletes the backing data associated with configuration versions and state versions. Soft deleting refers to marking a data object for garbage collection so that Terraform deletes it after the set number of days.

Once an object is soft deleted, any attempts to read the object will fail. Until the garbage collection process begins, you can restore soft deleted objects using the APIs described in the configuration version documentation and the state version documentation. Terraform permanently deletes the archivist storage after the garbage collection grace period elapses.

Organization owners can configure their organizations to inherit or override the global policy. Refer to Organization settings for instructions.

Workspace admins can also configure their workspaces to inherit the parent policy or override the global policy in the workspace settings. Refer to Workspace settings for instructions.

Automated License Utilization Reporting

Automated license utilization reporting sends license utilization data to HashiCorp without requiring you to manually collect and report them. Learn about automated license utilization reporting.

Configure General Settings