Terraform Cloud Integration

Badal Foundations uses Terraform Cloud (TFC) as the central hub for infrastructure state management, workspace orchestration, and automated deployments. This guide explains the workspace hierarchy, naming conventions, module registry, and deployment workflows.

TFC Organization

Setting	Value
Organization	Badal_devex
Total workspaces	46
VCS provider	GitHub (badal-io)
Execution mode	Remote (default)

Workspace Naming Conventions

Foundations uses two naming conventions — a newer standard and a legacy format from earlier deployments.

New Convention

{type}-{name}-{env}-{suffix}

Component	Description	Examples
type	Resource type	bu, data, devex, platform
name	Resource name	data, backstage, governance
env	Environment code	c (common), d (dev), np (non-prod), p (prod), ce (cross-env)
suffix	Random 5-char identifier	80r13, 9c9dl, mly9n

Examples:

• bu-data-c-80r13 — Data BU, common/cross-env workspace
• data-governance-d-f6y39 — Data governance tenant, dev environment
• devex-backstage-np-mly9n — Backstage tenant, non-prod environment

Legacy Convention

wrkspc-{env}-{domain}-{name}

Examples:

• wrkspc-ce-bu-devex — DevEx BU, cross-environment
• wrkspc-np-devex-backstage — Backstage, non-prod
• wrkspc-p-data-tenant-0001 — Data tenant, prod

Environment Codes

Full Name	New Code	Legacy Code
Common / cross-environment	c	ce
Development	d	d
Non-production	np	n or np
Production	p	p

Workspace Hierarchy

When a Business Unit and its Tenants are created, TFC workspaces are organized in a three-tier hierarchy:

BU Cross-Environment Workspace

• Purpose: Manages the BU-level resources (folders, WIF, GAR, tenant definitions)
• VCS: Connected to the BU repository (e.g., bu-data-80r13)
• Trigger: Runs on merge to main branch
• Creates: Tenant projects, repos, and per-env workspaces

Shared Workspace

• Purpose: Manages BU-level shared resources (shared GAR repos, shared configurations)
• Example: data-shared-c-80r13

Per-Environment Tenant Workspaces

• Purpose: Deploys the tenant's infrastructure for a specific environment
• VCS: Connected to the tenant repository
• Trigger: Branch-based (environment branches) or tag-based (trunk-based), depending on the tenant's branching model
• Scope: Can only access resources in its designated environment

How Workspaces Are Created Automatically

Workspaces are not created manually. The platform modules handle workspace creation as part of BU and Tenant provisioning:

1. BU creation (create-business-unit/platform) creates the BU workspace and shared workspace.
2. Tenant creation (create-tenant/platform) creates per-environment tenant workspaces.

Each workspace is automatically configured with:

• VCS connection to the appropriate GitHub repository
• Correct working directory
• Environment variables (GCP project ID, region, etc.)
• Terraform variables from the module configuration
• Appropriate execution mode

VCS Connections and Branch-Based Deployments

VCS-Driven Workspaces

Most workspaces are connected to a GitHub repository and trigger automatically:

Event	Result
PR opened	Speculative plan (shows what would change)
PR merged to main/env branch	Apply run (deploys changes)
Manual trigger	On-demand plan or apply

Branch Mapping

For environment-based branching:

Branch	Workspace Environment
development	Dev workspace
non-production	Non-prod workspace
production	Prod workspace
main	Cross-env / common workspace

For trunk-based branching:

Event	Workspace Environment
Push to main	Dev and/or non-prod
Git tag (v*)	Production

Auto-Apply vs Manual Confirm

Workspace Type	Auto-Apply	Rationale
Module registry	Yes	Registry updates should propagate immediately
Dev workspaces	Configurable	Teams can choose to auto-apply in dev
Non-prod workspaces	Configurable	Depends on team preference
Prod workspaces	No (default)	Production changes require manual confirmation

The Module Registry

Repository: devex-terraform-module-registry Workspace: devex-terraform-module-registry (auto-apply, 122 resources)

The TFC private module registry hosts all custom Terraform modules used by Foundations. Key modules:

Platform Modules

Module	Registry Path	Purpose
create-business-unit	app.terraform.io/Badal_devex/create-business-unit/platform	Provisions a complete Business Unit
create-tenant	app.terraform.io/Badal_devex/create-tenant/platform	Provisions a Tenant within a BU
business_unit_breakout	app.terraform.io/Badal_devex/business_unit_breakout/google	Breaks out BU resources into per-env folders

How Modules Are Published

1. Module source code is maintained in the respective GitHub repository.
2. The tfc-private-module-registry repo manages the registry configuration.
3. The devex-terraform-module-registry workspace (auto-apply) keeps the registry in sync.
4. Modules are versioned semantically — consumers pin to specific versions in their source blocks.

Environment Promotion Path

Infrastructure changes flow through environments in a controlled sequence:

Promotion Strategies

For environment-based branching:

1. Make changes in the development branch
2. Verify the dev workspace apply succeeds
3. Merge development into non-production
4. Verify the non-prod workspace apply succeeds
5. Merge non-production into production
6. Manually confirm the production apply in TFC

For trunk-based branching:

1. Open a PR against main — speculative plan runs
2. Merge PR — dev/non-prod workspaces apply
3. Create a release tag — production workspace triggers
4. Manually confirm the production apply in TFC

Key Workspaces

Active BU Workspaces

Workspace	Resources	VCS Repo	Purpose
bu-data-c-80r13	346	bu-data-80r13	Data BU (largest)
bu-platform-c-0r4dp	199	bu-platform-0r4dp	Platform BU
wrkspc-ce-bu-devex	149	repo-bu-devex	DevEx BU (legacy naming)

Infrastructure Workspaces

Workspace	Resources	Purpose
devex-terraform-module-registry	122	Module registry (auto-apply)
wrkspc-np-devex-backstage	110	Backstage non-prod (auto-apply)
gcp-foundations-projects-workspace-manager	N/A	Workspace management (no VCS)

Shared Workspaces

Workspace	BU
data-shared-c-80r13	data
devex-shared-c-9c9dl	devex
platform-shared-c-0r4dp	platform

Workspace Variables

Common variables set on TFC workspaces:

Variable	Type	Description
TF_VAR_project_id	Terraform	GCP project ID for this workspace
TF_VAR_region	Terraform	Primary GCP region
GOOGLE_CREDENTIALS	Environment	Service account key or WIF token
TF_VAR_environment	Terraform	Environment name
TF_VAR_business_unit	Terraform	Parent BU identifier

Troubleshooting

Issue	Resolution
Workspace stuck in "Planning"	Check for state locks. Another run may be in progress. Cancel queued runs if needed.
VCS connection failed	Verify the GitHub OAuth token is valid and has access to the repository. Re-authorize in TFC settings if needed.
Module version not found	Check that the module is published in the registry. Run the devex-terraform-module-registry workspace to sync.
Speculative plan on PR shows no changes	Ensure the workspace's VCS working directory matches the Terraform root module path.
Apply fails with permission error	The service account may lack IAM permissions. Check the WIF configuration and SA bindings.

Next Steps

• Understanding the Architecture — how TFC fits into the overall pipeline
• Adding a Business Unit — see workspaces being created in practice
• Adding a Tenant — see per-environment workspace creation