Terraform CLOUD

Andi Lamprecht ·2026-05-11· 10 min read· Accepted

Terraform Cloud Architecture

Context

Terraform Cloud is a service developed by HashiCorp built for centralized management of terraform pipelines, variables and states. Existing terraform pipeline introduces less flexibility, scalability issues.

The approach should be selected on how to organize Terraform Cloud workspaces altogether with github repositories that supports the code for infrastructure.

TFC Workspace - represent single state, stored in Terraform Cloud.

TF Workspace - an environment that can collect multiple states and resources under it and handle resource for each environment separately based on the prefixed naming convention.

Decision drivers

• Scalability

• Maintainability

• Automation (reduce amount of manual actions)

  • Ability to reference module outputs from other states

• Security

  • Single source of state access/management

  • Governance features across any resource (cost, security and

    compliance guardrails)

Decision

Terraform Cloud with Microrepos

Sectioning out the code into microrepos = 1 state per repo where the state will have multiple workspaces. To make this happen there will be multiple modules that will be used to be called in the Microrepos so that resources can be created using those modules and each state will allow for only state specific resources. The state files will live in TFC and will be managed there to take advantage of the state file security scanning that TFC provides.

Considered options

• Terraform Cloud

  • One repo - Multiple TFC
  • One repo - less TFC workspaces
  • Multiple repo - Multiple TFC

• Terraform on CI

  • Break existing monorepo into multiple repos with one CI flow

  • Migrate existing repo into new single repo with updates of

    setup/pipelines

• Terraform Cloud with GCP State Backend

  • One repo - Multiple Environment workspaces on one CI flow

  • Multiple repos - Multiple Environment workspaces on multiple CI

    Pipelines

Pros and Cons of the Options

1. Terraform Cloud with its own state

Monorepo - Multiple TFC Workspaces

The idea is to create one repo with multiple folders, each folder will

hold the single state and will be represented by single TFC workspace.

Initial setup of new TFC workspaces can be done with tf automation as

well including Doppler and separate Github repository.

Repo: terraform

Folders: cloud_name/project/component

TFC Workspace name: cloud-name_project-name_component-name

Further improvements: group resources into modules on existing state

using moved block:\

[https://learn.hashicorp.com/tutorials/terraform/move-config#move-your-resources-with-the-moved-configuration-block]

Pros:

• Each state that we have right now will have its own folder in Github

  and its own TFC workspace

• Each project will have corresponding Doppler project (1 Doppler

  project with few environments)

• Migration flow will require completion of following steps:

  • Creation of Github repo with the same folder structure (we can

    add one more subpath to point to cloud name to differentiate

    between Azure, GCP, AWS), the only difference is that single

    state=tf file can be dropped into multiple files (providers,

    variables, main, etc) instead of a single file

  • TFC workspace creation with the set of variables that replicates

    corresponding variables in WT-terraform ENVKEY project and

    repo connection to specific folder using

    Terraform Working Directory setting in Terraform Cloud

  • Downloading existing state using the same TF version that is

    currently used by that state

  • Update backend and init remote one based on instructions

    here

• New items will created from scratch on new TF version

• All Terraform setup in one place

• Modules can be placed in same folder, but with versions

Cons:

• Terraform Cloud apply will require hosted agent in our

  infrastructure to access closed resources

Microrepos - Multiple TFC Workspaces

Each existing state file will be presented as a separate repository

(less granular - each GCP/AWS/Azure project will have its own repository

with resources). Initial setup of new TFC workspaces can be done with tf

automation as well including Doppler and separate Github repository.

Repo names: cloud-name_project-name_component-name or

cloud-name_project-name

Folders: component

TFC Workspace name: cloud-name_project-name_component-name

Pros:

• Each state that we have right now will have its own folder in Github

  and its own TFC workspace

• Each project will have corresponding Doppler project (1 Doppler

  project with few environments)

• Migration flow is the same as for monorepo with multiple TFC

  workspaces

• New items will created from scratch on new tf version

Cons:

• In case of repo per component it will be harder to find the source

  of change

• Terraform Cloud apply will require hosted agent in our

  infrastructure to access closed resources

Terraform on CI

Monorepo - Environment Workspaces

There is only 1 repo with multiple folders, where each folder will hold

a single state and will have multiple state files.

• Each state will have as many state files as we have environments

  (Sandbox, Development, Testing, UAT, Production,

  Production-us-west-2, etc…)

• There will be 1 CircleCI pipeline that when a change is committed to

  the repo will check to see what state(s) have changed. That/Those

  state(s) then plan and apply into the Cloud platform for their

  respective resources.

• The CircleCI pipeline will have to have a series of scripts that

  will run the Terraform plan/apply commands and connect to all

  services via services accounts and secrets will either have to be

  maintained in the receptive cloud platforms (ex: SSM for AWS) or be

  kept in Doppler and read in at the time of plan/apply

• The state file will get stored in a GCS file path such as

  terraform-us-east-1/droneup_infrastructure/<workspace>/<platform structure>/<state>

  where the things that will change are the <workspace>,

  <platform structure> (IE: platform/services, platform/common,

  sharedservices/common, global, etc), and <state>

  • example:

    terraform-us-east-1/droneup_infrastructure/Sandbox/platform/services/airmap.service.foo

• The Variables will be kept in tfvar files inside the state folders

  and will be used to keep workspace information separate

• Versions will be kept in a .terraform-version file

Microrepos - Environment Workspaces

There is one repo for every state, each state will have multiple state

files

• Each state will have as many state files as we have environments

  (Sandbox, Development, Testing, UAT, Production,

  Production-us-west-2, etc…)

• There will either be 1 CircleCI pipeline per state or 1 CircleCI

  Template Pipeline that all Terraform code will run through without

  developer intervention.

• The CircleCI pipeline(s) will have to have a series of scripts that

  will run the Terraform plan/apply commands and connect to all

  services via services accounts and secrets will either have to be

  maintained in the receptive cloud platforms (ex: SSM for AWS) or be

  kept in Doppler and read in at the time of plan/apply

• The state file will get stored in a GCS file path such as

  terraform-us-east-1/droneup_infrastructure/<workspace>/<platform structure>/<state>

  where the things that will change are the <workspace>,

  <platform structure> (IE: platform/services, platform/common,

  sharedservices/common, global, etc), and <state>

  • example:

    terraform-us-east-1/droneup_infrastructure/Sandbox/platform/services/airmap.service.foo

• The Variables will be kept in tfvar files inside the repo and will

  be used to keep workspace information separate

• Versions will be kept in a .terraform-version file

Terraform Cloud with GCP State Backend

Invalid Image Path

Monorepo - Environment Workspaces

There is one repo with multiple folders, each folder will hold a single

state and will have multiple state files.

• Each state will have as many state files as we have environments

  (Sandbox, Development, Testing, UAT, Production,

  Production-us-west-2, etc…)

• There will be 1 CircleCI pipeline that when a change is committed to

  the repo will check to see what state(s) have changed. That/Those

  state(s) then plan and apply into the Cloud platform for their

  respective resources.

• The state file will get stored in a GCS file path such as

  terraform-us-east-1/droneup_infrastructure/<workspace>/<platform structure>/<state>

  where the things that will change are the <workspace>,

  <platform structure> (IE: platform/services, platform/common,

  sharedservices/common, global, etc), and <state>

  • example:

    terraform-us-east-1/droneup_infrastructure/Sandbox/platform/services/airmap.service.foo

• The Variables, Versions, and resources are then stored in Terraform

  Cloud where we are able to manage the content and upgrade path

  without needing to manually migrate states upon new version releases

Microrepos - Environment Workspaces

There is one repo for every state, each state will have multiple state

files

• Each state will have as many state files as we have environments

  (Sandbox, Development, Testing, UAT, Production,

  Production-us-west-2, etc…)

• There will either be 1 CircleCI pipeline per state or 1 CircleCI

  Template Pipeline that all Terraform code will run through without

  developer intervention.

• The state file will get stored in a GCS file path such as

  terraform-us-east-1/droneup_infrastructure/<workspace>/<platform structure>/<state>

  where the things that will change are the <workspace>,

  <platform structure> (IE: platform/services, platform/common,

  sharedservices/common, global, etc), and <state>

  • example:

    terraform-us-east-1/droneup_infrastructure/Sandbox/platform/services/airmap.service.foo

• The Variables, Versions, and resources are then stored in Terraform

  Cloud where we are able to manage the content and upgrade path

  without needing to manually migrate states upon new version releases

Pros and Cons of the options