Terraform: Adding a Business Unit

A Business Unit (BU) is the primary organizational construct in Badal Foundations. It represents a team, department, or product line and serves as the container for one or more Tenants.

This guide covers both methods for creating a BU: the recommended Backstage self-service approach and the direct Terraform approach.

What Is a Business Unit?

A Business Unit groups related workloads under a common organizational umbrella. When you create a BU, the platform provisions:

• Per-environment GCP folders under the foundation environment folders (dev, non-prod, prod)
• A common folder with a Workload Identity Federation (WIF) host project
• A GitHub repository (e.g., bu-data-80r13) pre-populated with scaffold code
• A Terraform Cloud project and workspace for managing the BU's infrastructure
• Optional Google Artifact Registry (GAR) repositories

Each BU receives a random 5-character suffix (e.g., 80r13, 9c9dl, 0r4dp) that is appended to resource names for uniqueness.

Method 1: Backstage UI (Recommended)

The easiest way to create a Business Unit is through the Backstage developer portal using the create-business-unit template.

Prerequisites

• Access to the Backstage portal
• Membership in the appropriate GitHub team
• Permission to create repositories in the badal-io GitHub organization

Step-by-Step

1. Open Backstage and navigate to the Create page (the "+" icon or /create route).

2. Select the "Create Business Unit" template from the list of available templates.

3. Fill in the basic configuration:

   Field	Description	Example
   Business Unit Name	Short identifier for the BU	data
   Description	Human-readable description	Data engineering team
   Owner	GitHub team that owns this BU	@badal-io/data-team
   Environments	Which environments to create	dev, non-prod, prod

4. Configure optional features:

   Feature	Description
   GAR (Artifact Registry)	Enable and select artifact types (DOCKER, PYTHON, NPM, etc.)

5. Review and submit. Backstage will create a Pull Request against the gcp-foundations-projects repository.

6. Merge the PR. Once approved and merged, Terraform Cloud will automatically provision all resources.

7. Monitor the workspace in Terraform Cloud to confirm the apply completes successfully.

Method 2: Direct Terraform

You can also create a Business Unit by adding configuration directly to the gcp-foundations-projects repository.

Step-by-Step

1. Clone the repository:

   git clone https://github.com/badal-io/gcp-foundations-projects.git
   cd gcp-foundations-projects

2. Create a new directory for your BU under the appropriate subdirectory, or add your BU configuration to the main module.

3. Add the BU module call using the create-business-unit platform module:

   module "bu_myteam" {
     source  = "app.terraform.io/Badal_devex/create-business-unit/platform"
   
     business_unit_name = "myteam"
     environments       = ["development", "non-production", "production"]
   
     github_org    = "badal-io"
     github_team   = "myteam-admins"
   
     gar_config = {
       enabled        = true
       artifact_types = ["DOCKER", "PYTHON"]
     }
   }

4. Open a Pull Request and get it reviewed.

5. Merge — Terraform Cloud will apply the changes automatically.

What Gets Created

After the Terraform apply completes, the following resources exist:

GCP Resources

• Common folder containing a WIF host project for cross-environment GitHub Actions authentication
• Per-environment folders (one under each of dev, non-prod, prod) where future tenant projects will be created

GitHub Repository

A repository named bu-{name}-{suffix} (e.g., bu-data-80r13) is created in the badal-io organization with the following scaffold:

bu-{name}-{suffix}/
├── backstage-manifest.json    # Backstage catalog metadata
├── terraform/
│   ├── main.tf                # Tenant definitions (module calls)
│   ├── variables.tf           # Input variables
│   ├── outputs.tf             # Exported outputs
│   ├── providers.tf           # Provider configuration
│   └── backend.tf             # TFC backend config
├── .github/
│   └── workflows/             # CI/CD workflows using reusable workflows
└── catalog-info.yaml          # Backstage component registration

The terraform/main.tf file is where you will add Tenant module calls to onboard workloads into this BU.

Terraform Cloud

• A TFC project for organizing the BU's workspaces
• A cross-environment workspace (e.g., bu-data-c-80r13) connected to the GitHub repo
• A shared workspace (e.g., data-shared-c-80r13) for BU-level shared resources

Google Artifact Registry (GAR)

If GAR is enabled during BU creation, the platform provisions a tiered artifact registry:

Level	Type	Purpose
BU-level virtual repos	Virtual	Aggregation point — upstream policies pull from standard repos
BU-level standard repos	Standard	BU-wide shared artifacts in the shared tenant project
Tenant-level standard repos	Standard	Per-tenant, per-env artifact storage (created when tenants are added)

Supported artifact types:

• DOCKER — container images
• PYTHON — Python packages
• NPM — Node.js packages
• MAVEN — Java packages

Real-World Examples

The current Foundations deployment includes three Business Units:

BU	Repo	Suffix	Environments	GAR Types	Tenants
data	bu-data-80r13	80r13	dev, non-prod, prod	DOCKER, PYTHON	governance, template
devex	bu-devex-9c9dl	9c9dl	non-prod, prod	DOCKER, NPM	backstage
platform	bu-platform-0r4dp	0r4dp	dev, non-prod, prod	None	gke-argocd

Post-Creation: Next Steps

Once your Business Unit is created:

1. Add Tenants — Follow the Adding a Tenant guide to create workload projects within your BU.
2. Configure access — Ensure the right GitHub teams and Google Groups have access to the BU repo and GCP folders.
3. Set up CI/CD — The scaffolded repo comes with GitHub Actions workflows. Customize them for your team's needs using the devex-reusable-workflows.
4. Register in Backstage — The catalog-info.yaml and backstage-manifest.json files auto-register the BU in the Backstage catalog for visibility.

Troubleshooting

Issue	Resolution
TFC workspace fails to apply	Check the workspace logs in Terraform Cloud. Common causes: missing permissions, state lock conflicts.
GitHub repo not created	Verify the GitHub token used by TFC has repo and admin:org scopes in the badal-io org.
Folders not appearing in GCP	The service account for stage 4 needs roles/resourcemanager.folderCreator on the parent folders. Check the bootstrap outputs.