Terraform Configurations in HCP Terraform Workspaces

Each HCP Terraform workspace is associated with a particular Terraform configuration, which is expected to change and evolve over time.

Since every organization has its own preferred source code control practices, HCP Terraform does not provide integrated version management. Instead, it expects Terraform configurations to be managed in your existing version control system (VCS).

In order to perform remote Terraform runs for a given workspace, HCP Terraform needs to periodically receive new versions of its configuration. Usually, this can be handled automatically by connecting a workspace to a VCS repository.

Note: If a workspace's execution mode is set to local, it doesn't require configuration versions, since HCP Terraform won't perform runs for that workspace.

Providing Configuration Versions

There are two ways to provide configuration versions for a workspace:

With a connected VCS repository. HCP Terraform can automatically fetch content from supported VCS providers, and uses webhooks to get notified of code changes. This is the most convenient way to use HCP Terraform. See The UI- and VCS-driven Run Workflow for more information.
A VCS connection can be configured when a workspace is created, or later in its version control settings.
Note: When a workspace is connected to a VCS repository, directly uploaded configuration versions can only be used for speculative plans. This helps ensure your VCS remains the source of truth for all real infrastructure changes.
With direct uploads. You can use a variety of tools to directly upload configuration content to HCP Terraform:
- Terraform CLI: With the CLI integration configured, the terraform plan and terraform apply commands will perform remote runs by uploading a configuration from a local working directory. See The CLI-driven Run Workflow for more information.
- API: HCP Terraform's API can accept configurations as .tar.gz files, which can be uploaded by a CI system or other workflow tools. See The API-driven Run Workflow for more information.
When configuration versions are provided via the CLI or API, HCP Terraform can't automatically react to code changes in the underlying VCS repository.

Code Organization and Repository Structure

Organizing Separate Configurations

Most organizations either keep each Terraform configuration in a separate repository, or keep many Terraform configurations as separate directories in a single repository (often called a "monorepo").

HCP Terraform works well with either approach, but monorepos require some extra configuration:

Each workspace must specify a Terraform working directory, so HCP Terraform knows which configuration to use.
If the repository includes any shared Terraform modules, you must add those directories to the automatic run triggering setting for any workspace that uses those modules.

Note: If your organization does not have a strong preference, we recommend using separate repositories for each configuration and using the private module registry to share modules. This allows for faster module development, since you don't have to update every configuration that consumes a module at the same time as the module itself.

Organizing Multiple Environments for a Configuration

There are also a variety of ways to handle multiple environments. The most common approaches are:

All environments use the same main branch, and environment differences are handled with Terraform variables. To protect production environments, wait to apply runs until their changes are verified in staging.
Different environments use different long-lived VCS branches. To protect production environments, merge changes to the production branch after they have been verified in staging.
Different environments use completely separate configurations, and shared behaviors are handled with shared Terraform modules. To protect production environments, verify new module versions in staging before updating the version used in production.

HCP Terraform works well with all of these approaches. If you used long-lived branches, be sure to specify which branch to use in each workspace's VCS connection settings.

Archiving Configuration Versions

Once all runs using a particular configuration version are complete, HCP Terraform no longer needs the associated .tar.gz file and may discard it to save storage space. This process is handled differently depending on how the configuration version was created.

Created with a connected VCS repository. HCP Terraform will automatically archive VCS configuration versions once all runs are completed and they are no longer current for any workspace. HCP Terraform will re-fetch the configuration files from VCS as needed for new runs.
Created with direct uploads via the API or CLI. HCP Terraform does not archive CLI and API configuration versions automatically, because it cannot re-fetch the files for new runs. However, you can use the Archive a Configuration Version endpoint to archive them manually.

For Terraform Enterprise customers upgrading from a previous version, the functionality has a backfill capability that will clean up space for historical runs in batches. In each organization, Terraform Enterprise archives a batch of 100 configurations each time a run completes or a new configuration version is uploaded. This will gradually free up existing object storage space over time.