Getting Started
Badal Foundations is a production-ready GCP landing zone built with Terraform. It provides a secure, scalable, and opinionated cloud infrastructure foundation based on the Google Cloud Security Foundations blueprint (Cloud Foundation Toolkit).
Whether you are onboarding a new team, creating a new workload, or understanding how the platform works, this guide will orient you to the key concepts and get you started.
Why Badal Foundations?
Standing up a secure, multi-environment GCP organization from scratch is a significant undertaking. Badal Foundations solves this by providing:
- Security by default — org policies, VPC Service Controls, hierarchical firewalls, and IAM best practices are baked in from day one.
- Self-service infrastructure — teams can create Business Units and Tenants through Backstage or Terraform without needing deep GCP expertise.
- Repeatable environments — dev, non-prod, and prod environments are structurally identical, reducing drift and surprises.
- Auditability — centralized logging, billing exports, and Security Command Center are enabled at the organization level.
- GitOps workflow — all infrastructure changes flow through GitHub PRs, Terraform Cloud workspaces, and automated CI/CD pipelines.
Prerequisites
Before working with Badal Foundations, make sure the following are in place:
| Prerequisite | Details |
|---|---|
| GCP Organization | A Google Cloud organization linked to a verified domain. Badal uses foundation.badal.io (Org ID: 758951886862). |
| Billing Account | An active GCP billing account attached to the organization. |
| GitHub Organization | A GitHub org (e.g., badal-io) for hosting all infrastructure and application repos. |
| Terraform Cloud Organization | A TFC org (e.g., Badal_devex) for workspace and state management. |
| Admin Access | Organization Admin, Billing Admin, and GitHub Org Owner permissions are required for the initial bootstrap. |
Day-to-day operations (creating BUs, tenants, deploying workloads) do not require Org Admin access. Only the one-time bootstrap step does.
High-Level Architecture
Badal Foundations is deployed as a 5-stage sequential pipeline, where each stage builds on the outputs of the previous one. After the foundation is in place, the platform layer lets teams self-service their own Business Units and Tenants.
0-bootstrap → 1-org → 2-environments → 3-networks → 4-projects → platform
| Stage | Repository | Purpose |
|---|---|---|
| 0 - Bootstrap | gcp-foundations-bootstrap | One-time setup: seed project, service accounts, state bucket, GitHub OIDC |
| 1 - Organization | gcp-foundations-org | Org-wide governance: folders, org policies, logging, SCC, shared projects |
| 2 - Environments | gcp-foundations-envs | Create dev, non-prod, and prod environment folders with shared infra |
| 3 - Networks | gcp-foundations-networks | Dual Shared VPC architecture, DNS hub, firewalls, Cloud NAT |
| 4 - Projects | gcp-foundations-projects | Project factory, BU onboarding, workload project creation |
| Platform | terraform-platform-create-business-unit, terraform-platform-create-tenant | Self-service BU and Tenant creation |
Each stage stores its Terraform state in a shared GCS bucket (bkt-prj-b-seed-tfstate-6a60) and exposes outputs via terraform_remote_state for downstream stages to consume.
Key Concepts
Business Units (BUs)
A Business Unit represents an organizational group — a team, department, or product line. Each BU gets:
- Per-environment GCP folders (under dev, non-prod, prod)
- A common folder with a Workload Identity Federation (WIF) host project
- A dedicated GitHub repository (e.g.,
bu-data-80r13) - A Terraform Cloud project and workspace
BUs are the container in which Tenants live. See Adding a Business Unit for details.
Tenants
A Tenant is a workload or application that lives inside a BU. Each Tenant gets:
- Per-environment GCP projects (e.g.,
prj-governance-d-f6y39) - A dedicated GitHub repository scaffolded from foundations-template
- Per-environment WIF and service accounts
- Optional GAR repositories and budget alerts
See Adding a Tenant for the full walkthrough.
Shared VPCs
Networking follows a dual Shared VPC model:
- Base VPC — for general workloads with standard network access
- Restricted VPC — for sensitive workloads protected by VPC Service Controls
Both are managed centrally in stage 3 and shared with tenant projects via host/service project relationships.
Environments
The platform defines three standard environments:
| Environment | Code | Purpose |
|---|---|---|
| Development | d | Experimentation and active development |
| Non-production | np / n | Staging, QA, integration testing |
| Production | p | Live workloads and customer-facing services |
Each environment has its own GCP folder hierarchy, network configuration, and set of tenant projects.
Quick Start: What to Do First
If the foundation is already deployed
Most teams will join an existing Foundations deployment. In that case:
- Get access — Ask your platform team to add you to the appropriate Google Groups and GitHub teams.
- Create a Business Unit — Follow the Adding a Business Unit guide (or ask your platform admin to do it via Backstage).
- Create a Tenant — Follow the Adding a Tenant guide to set up your first workload project.
- Deploy your application — Use the scaffolded repo (based on foundations-template) with YAML-driven configuration to deploy Cloud Run services, GCS buckets, BigQuery datasets, and more.
If you are bootstrapping from scratch
- Run the bootstrap — Clone gcp-foundations-bootstrap and run it manually with Org Admin credentials. This is a one-time operation.
- Deploy stages 1-4 — Each subsequent stage is deployed via CI/CD (GitHub Actions + WIF). Merge PRs in order: org, envs, networks, projects.
- Set up Backstage (optional) — Deploy repo-devex-backstage for self-service BU and Tenant creation through a developer portal.
- Onboard teams — Create Business Units and Tenants as teams come on board.
Next Steps
- Understanding the Architecture — deep dive into the layered design
- Adding a Business Unit — create your first BU
- Adding a Tenant — provision workload projects
- Available Features — explore GAR, VPC-SC, budgets, and more
- Terraform Cloud Integration — understand workspace management