• Overview
    • Enforce Policy as Code
    • Infrastructure as Code
    • Inject Secrets into Terraform
    • Integrate with Existing Workflows
    • Manage Kubernetes
    • Manage Virtual Machine Images
    • Multi-Cloud Deployment
    • Network Infrastructure Automation
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
  • Registry
  • Tutorials
    • About the Docs
    • Intro to Terraform
    • Configuration Language
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
    • Provider Use
    • Plugin Development
    • Registry Publishing
    • Integration Program
    • Terraform Tools
    • CDK for Terraform
    • Glossary
  • Community
GitHubTerraform Cloud
Download

    Terraform Cloud and Enterprise

  • Overview
  • Plans and Features
  • Getting Started
    • API Docs template
    • Overview
    • Account
    • Agent Pools
    • Agent Tokens
    • Applies
    • Audit Trails
    • Comments
    • Configuration Versions
    • Cost Estimates
    • Feature Sets
    • Invoices
    • IP Ranges
    • Notification Configurations
    • OAuth Clients
    • OAuth Tokens
    • Organizations
    • Organization Memberships
    • Organization Tags
    • Organization Tokens
    • Plan Exports
    • Plans
    • Policies
    • Policy Checks
    • Policy Sets
    • Policy Set Parameters
      • Modules
      • Providers
      • Private Provider Versions and Platforms
      • GPG Keys
    • Runs
      • Run Tasks
      • Stages and Results
      • Custom Integration
    • Run Triggers
    • SSH Keys
    • State Versions
    • State Version Outputs
    • Subscriptions
    • Team Access
    • Team Membership
    • Team Tokens
    • Teams
    • User Tokens
    • Users
    • Variables
    • VCS Events
    • Workspaces
    • Workspace-Specific Variables
    • Workspace Resources
    • Variable Sets
      • Overview
      • Module Sharing
      • Organizations
      • Runs
      • Settings
      • Terraform Versions
      • Users
      • Workspaces
    • Changelog
    • Stability Policy
    • Overview
    • Creating Workspaces
    • Naming
    • Terraform Configurations
      • Overview
      • Managing Variables
      • Overview
      • VCS Connections
      • Access
      • Drift Detection
      • Notifications
      • SSH Keys for Modules
      • Run Triggers
      • Run Tasks
    • Terraform State
    • JSON Filtering
    • Remote Operations
    • Viewing and Managing Runs
    • Run States and Stages
    • Run Modes and Options
    • UI/VCS-driven Runs
    • API-driven Runs
    • CLI-driven Runs
    • The Run Environment
    • Installing Software
    • Users
    • Teams
    • Organizations
    • Permissions
    • Two-factor Authentication
    • API Tokens
      • Overview
      • Microsoft Azure AD
      • Okta
      • SAML
      • Linking a User Account
      • Testing
    • Overview
    • GitHub.com
    • GitHub.com (OAuth)
    • GitHub Enterprise
    • GitLab.com
    • GitLab EE and CE
    • Bitbucket Cloud
    • Bitbucket Server and Data Center
    • Azure DevOps Services
    • Azure DevOps Server
    • Troubleshooting
    • Overview
    • Adding Public Providers and Modules
    • Publishing Private Providers
    • Publishing Private Modules
    • Using Providers and Modules
    • Configuration Designer
  • Migrating to Terraform Cloud
    • Overview
    • Using Sentinel with Terraform 0.12
    • Manage Policies
    • Enforce and Override Policies
    • Mocking Terraform Sentinel Data
    • Working With JSON Result Data
      • Overview
      • tfconfig
      • tfconfig/v2
      • tfplan
      • tfplan/v2
      • tfstate
      • tfstate/v2
      • tfrun
    • Example Policies
    • Overview
    • AWS
    • GCP
    • Azure
      • Overview
      • Service Catalog
      • Admin Guide
      • Developer Reference
      • Example Customizations
      • V1 Setup Instructions
    • Splunk Integration
    • Kubernetes Integration
    • Run Tasks Integration
    • Overview
    • IP Ranges
    • Data Security
    • Security Model
    • Overview
    • Part 1: Overview of Our Recommended Workflow
    • Part 2: Evaluating Your Current Provisioning Practices
    • Part 3: How to Evolve Your Provisioning Practices
    • Part 3.1: From Manual Changes to Semi-Automation
    • Part 3.2: From Semi-Automation to Infrastructure as Code
    • Part 3.3: From Infrastructure as Code to Collaborative Infrastructure as Code
    • Part 3.4: Advanced Workflow Improvements

  • Terraform Cloud Agents

  • Terraform Enterprise Admin

  • Other Docs

  • Intro to Terraform
  • Configuration Language
  • Terraform CLI
  • Terraform Cloud
  • Terraform Enterprise
  • Provider Use
  • Plugin Development
  • Registry Publishing
  • Integration Program
  • Terraform Tools
  • CDK for Terraform
  • Glossary
Type '/' to Search

»Terraform Configurations in Terraform Cloud Workspaces

Each Terraform Cloud 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, Terraform Cloud 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, Terraform Cloud 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 Terraform Cloud 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. Terraform Cloud 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 Terraform Cloud. 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 Terraform Cloud:

    • 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: Terraform Cloud'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, Terraform Cloud 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").

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

  • Each workspace must specify a Terraform working directory, so Terraform Cloud 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.

Terraform Cloud 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, Terraform Cloud 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. Terraform Cloud will automatically archive VCS configuration versions once all runs are complete and re-fetch the configuration files from VCS as needed for new runs.

  • Created with direct uploads via the API or CLI. Terraform Cloud 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.

Note: This functionality is available in Terraform Enterprise v202203-1 or later. In earlier versions, Terraform Enterprise keeps the .tar.gz files associated with configuration versions until the associated workspace is deleted.

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.

github logoEdit this page
  • Overview
  • Docs
  • Extend
  • Privacy
  • Security
  • Press Kit
  • Consent Manager