Understanding the Architecture

Badal Foundations implements a layered, sequential infrastructure pipeline based on the Google Cloud Security Foundations blueprint. Each layer has a single responsibility and builds on the outputs of the layer before it.

This guide explains how the layers fit together, how state flows between them, and the design decisions behind the networking and security model.

The Layered Pipeline

Stage 0: Bootstrap

Repository: gcp-foundations-bootstrap

This is the only stage that runs manually. An operator with Organization Admin privileges runs it once to create the foundational infrastructure that all other stages depend on:

• Seed project (prj-b-seed) — hosts the Terraform state bucket and KMS encryption keys
• CI/CD project (prj-b-cicd-wif-gh) — hosts the GitHub Actions Workload Identity Federation (WIF) pool
• GCS state bucket (bkt-prj-b-seed-tfstate-6a60) — shared state storage for all stages, encrypted with customer-managed KMS keys
• 5 granular service accounts — one per stage (bootstrap, org, env, net, proj), each with least-privilege IAM bindings
• Google Groups — for role-based access control across the organization

The bootstrap uses the terraform-google-modules/bootstrap/google module (~11.0).

Stage 1: Organization

Repository: gcp-foundations-org

Sets up organization-wide governance:

• Top-level folders — fldr-common, fldr-network, fldr-pci-dss
• Shared projects — logging (prj-c-logging), billing logs, KMS, secrets, artifact registry, SCC, DNS hub, interconnect
• Organization policies — a comprehensive set of security constraints (see Security Model below)
• Centralized logging — Cloud Logging sinks and BigQuery exports
• Security Command Center — org-wide threat detection

Stage 2: Environments

Repository: gcp-foundations-envs

Creates three environment folders, each with their own shared infrastructure:

Environment	Folder	Shared Projects
Development	fldr-development	Monitoring, Secrets, KMS
Non-production	fldr-non-production	Monitoring, Secrets, KMS
Production	fldr-production	Monitoring, Secrets, KMS

This stage uses a branch-per-environment deployment model — the development, non-production, and production branches each deploy their respective environment.

Stage 3: Networks

Repository: gcp-foundations-networks

Provisions the complete networking layer including the dual Shared VPC architecture, DNS hub, and connectivity services.

Stage 4: Projects

Repository: gcp-foundations-projects

The project factory stage. This is where Business Units are defined and tenant workload projects are created. It uses TFC modules to orchestrate BU creation and project provisioning.

How State Flows Between Stages

Every stage writes its Terraform state to the shared GCS bucket and exposes outputs via terraform_remote_state data sources. Downstream stages read these outputs to configure themselves.

This design means stages must be deployed in order. Changing a foundational stage (e.g., networks) will not automatically propagate to downstream stages — those must be re-applied as well.

Dual Shared VPC Architecture

Badal Foundations implements two parallel Shared VPC networks per environment:

Base VPC

• For general workloads that do not require VPC Service Controls
• IP range: 10.0.x.x/18 per environment
• GKE pods: 100.64.x.x/18, GKE services: 100.65.x.x/18

Restricted VPC

• For sensitive workloads protected by a VPC Service Controls perimeter
• IP range: 10.8.x.x/18 per environment
• Same GKE secondary ranges as base

DNS Hub

• Centralized DNS resolution via prj-c-dns-hub (172.16.0.0/25)
• All VPCs peer with the DNS hub for consistent name resolution
• Supports Private Service Connect for Google API access

Tenant Subnets

Tenants can request subnets in either the base or restricted VPC. Subnet configuration is JSON-driven, managed in tenant_subnets/ directories within the networks repository.

Additional Networking Features

• Cloud NAT — outbound internet access for private instances
• Hierarchical Firewalls — organization-level firewall policies
• Private Service Connect — private access to Google APIs without public endpoints

Environment Model

Every environment is structurally identical — same folder hierarchy, same network topology, same security controls. This ensures that workloads behave consistently as they promote from dev through to production.

The environment codes used in naming conventions are:

Full Name	Code	Short Code
Common (cross-env)	c	ce
Development	d	d
Non-production	np	n
Production	p	p

BU and Tenant Hierarchy

The organizational model is a two-level hierarchy:

Organization
└── Business Unit (BU)        — team, department, or product line
    └── Tenant                — individual workload or application

In GCP terms, this maps to:

Concept	GCP Resource	Example
Business Unit	Folder (per environment)	bu-data-80r13/ under fldr-development
BU Common	Folder + WIF host project	data-80r13/ under fldr-common
Tenant	Project (per environment)	prj-governance-d-f6y39

Current Business Units

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

Security Model

Badal Foundations enforces security at multiple layers:

Organization Policies

Policies are applied at the organization level and enforced across all projects:

Category	Policies
Compute	Disable nested virtualization, disable serial port access, require OS Login, no external IPs on VMs
SQL	Restrict public IP on Cloud SQL instances
IAM	Disable service account key creation, disable default SA grants
Storage	Enforce uniform bucket-level access, no public buckets
Networking	Domain-restricted sharing, VPC SC access policy

note

The fldr-pci-dss folder is excluded from most organization policies to support PCI-DSS compliance requirements that may need different controls.

VPC Service Controls

The restricted Shared VPC is protected by a VPC Service Controls perimeter. This prevents data exfiltration by restricting which Google APIs can be accessed and from where.

IAM and Workload Identity Federation

• No service account keys — all CI/CD authentication uses Workload Identity Federation (WIF) with GitHub Actions OIDC tokens.
• Per-stage service accounts — each pipeline stage has its own SA with least-privilege permissions.
• Per-environment WIF for tenants — each tenant gets separate WIF configurations per environment, ensuring workloads in dev cannot access production resources.

Centralized Logging and Monitoring

• Cloud Logging — org-wide log sinks to the centralized logging project (prj-c-logging)
• BigQuery exports — billing logs exported to prj-c-billing-logs for cost analysis
• Security Command Center — organization-level threat detection and vulnerability scanning via prj-c-scc

Next Steps

• Adding a Business Unit — create your first organizational unit
• Adding a Tenant — provision workload projects within a BU
• Terraform Cloud Integration — understand workspace management