Post-installation configuration

This page covers the first-run Terraform Enterprise setup tasks that follow deployment. HCP Terraform does not require installation; HCP Terraform readers should use the Administration and User guides for shared service configuration and consumption workflows.

Post-installation tasks

An optional step at the end of automated installation of Terraform Enterprise is the creation of the Initial Admin Creation Token(opens in new tab) (IACT), but further initialization tasks complete the setup. There are two viable options for post-provision configuration in Terraform Enterprise: API scripts or using the Terraform Provider. The best practice is to use the Terraform Enterprise provider(opens in new tab) to derive state for the configuration.

Connect to a version control system

We recommend connecting HCP Terraform/Terraform Enterprise to your VCS provider to enable workflows for managing modules in the private registry, managing Sentinel or OPA policy-sets, and connecting VCS-backed Stacks and workspaces to VCS repositories.

GitHub app

If using GitHub, the preferred method of VCS connection is a GitHub App, for a number of reasons. A GitHub App is not tied to a specific user, does not require a personal access token, and is safe to set up as a static VCS connection with no need to rotate tokens. A GitHub App connects Terraform to GitHub, but confers no access permissions itself. Instead, the following elements govern access to repositories.

• The GitHub organization(s) housing the GitHub App.
• Individual GitHub user permissions (to use the GitHub App, Terraform users must authorize it with their GitHub credentials).

See GitHub's documentation(opens in new tab) for more detail.

Terraform Enterprise supports a single site-wide GitHub App, shared across all Terraform Enterprise organizations. To use it, create and configure it(opens in new tab) using a site administrator account.

Choose the appropriate level of visibility for your GitHub App from the following list.

• If you only have one GitHub organization, configure your GitHub App as private.
• If you have multiple organizations under the same GitHub Enterprise, create the App under your enterprise account(opens in new tab) (at the time of writing, this feature is in public preview).
• If you need access to repositories across multiple GitHub organizations, configure your GitHub App as public but do not list it on GitHub's marketplace.

HCP Terraform has a pre-configured public GitHub app(opens in new tab) which you can install in any GitHub organization(s) as required.

OAuth

For providers other than GitHub, authorize VCS connections using OAuth within each Terraform Enterprise organization. Do this using a manual UI workflow(opens in new tab) using an ID and secret from the VCS, or automated using the HCP Terraform and Terraform Enterprise provider(opens in new tab) using an access token from the respective VCS account. As with all static tokens, it is good practice to rotate this periodically.

OAuth authorizes Terraform Enterprise to act as a specific user or account on the VCS. The permissions of that account govern the access Terraform has to VCS organizations and repositories. For simplicity, we recommend setting up a single OAuth connection per VCS provider in each Terraform Enterprise organization. Use a service account with access to all IaC and policy-as-code repositories, to avoid any dependency on individual employee accounts.

If you require a more granular or least-privilege permissions model, you can create multiple OAuth VCS connections, each mapping a subset of VCS repositories to a subset of Terraform projects. In this case it would be a function of a landing-zone module to create these OAuth connections and project mappings(opens in new tab) on demand whenever a new project onboards.