Backstage Platform

Overview

The Badal Foundations Backstage portal is a customized Backstage deployment serving as the developer experience layer for the Foundations platform. It provides a unified interface for infrastructure management, team collaboration, and AI-powered development tools.

Deployment

Property	Value
URL	https://backstage-778221394647.northamerica-northeast1.run.app
Platform	Google Cloud Run
Region	northamerica-northeast1
Database	Cloud SQL (PostgreSQL)
Repository	badal-io/repo-devex-backstage
GCP Project	backstage-np-mly9n (non-production)

Custom Plugins

Gemini Agent

AI-powered development assistant that deploys Claude/Gemini agent instances as Cloud Run services. Each session creates an isolated container with access to the user's GitHub repositories.

Key characteristics:

• One Cloud Run service per agent session for isolation
• KMS-signed authentication for secure access
• Repository and branch scoping per session
• Session lifecycle management (create, stop, delete)

Claude Flow

Integration with Claude AI for workflow orchestration.

Capabilities:

• GitHub token passthrough for repository access
• Vault secrets access for secure configuration
• Workflow automation with AI-driven orchestration

Vault Secrets

HashiCorp Vault integration for secrets management within Backstage.

Key paths:

Path	Description	Access Control
/backstage/users	User-specific secrets	Authenticated user
/backstage/groups	Group-based secrets	Requires GitHub team membership
/backstage/backend	Backend service secrets	Service account only

UI Mockup

Drag-and-drop dashboard builder with live Backstage catalog data integration.

Features:

• Versioned mockups with save and iteration support
• Preview mode for visualizing final output
• Live catalog data integration (e.g., querying kind:component, type:gcp-project)

Available components:

Component	Description
Title	Heading text for sections
Text Block	Free-form text content
Link	Clickable links
Image	Embedded images
Catalog Item	Live data from the Backstage catalog
Dropdown	Selection menus
Button	Action buttons
Input Field	Text input fields
Text Area	Multi-line text input

Terraform Cloud

Integration with the Terraform Cloud API for workspace management and state retrieval. Provides visibility into workspace runs, state versions, and outputs directly within Backstage.

Homepage Links

Customizable homepage with group-aware content:

• Group-based onboarding -- Content tailored to your team memberships
• Pull request management -- Review, comment, approve, and merge PRs from the home page
• Team links -- Quick access to team-specific resources and calendars
• GCP projects and GitHub repos -- Direct links to infrastructure and code

Authentication

Backstage uses three authentication providers working together:

1. GitHub OAuth (Primary Identity)

The primary identity provider for Backstage. GitHub OAuth extracts:

• Organization membership
• Team memberships (used for group-based access control)
• User profile information

2. Google OAuth (GCP Access)

Used for accessing GCP resources from within Backstage.

Requested scopes:

• cloud-platform.read-only -- Read access to GCP resources
• compute.readonly -- Read access to Compute Engine resources

3. JIT User Provisioning

Just-In-Time user entity creation:

• On first sign-in, a catalog entity is automatically created for the user
• No pre-registration required
• User entity is linked to GitHub identity and team memberships

Allowed Domains

Authentication is restricted to the following email domains:

• badal.io
• foundation.badal.io
• telus.com

Catalog Discovery

The Backstage catalog is populated through automatic discovery from multiple sources.

GitHub Discovery

• Source: All repositories in the badal-io organization
• Mechanism: Scans for catalog-info.yaml files in repository roots
• Frequency: Every 5 minutes (non-production), hourly (production)

Terraform State Discovery

• Sources:
  • Terraform Cloud workspaces
  • GCS bucket bkt-prj-b-seed-tfstate-6a60
• Maximum state age: 6 months
• Discovered entities: GCP projects, service accounts, IAM bindings

Entity Types

Type	Description
Component	Software components, GCP projects, Terraform modules
System	Groups of related components
API	API definitions and documentation
Resource	Infrastructure resources
Location	Pointers to other entity sources
Template	Scaffolder templates
User	User entities (JIT provisioned)
Group	Team and organization groups

Scaffolder Templates

Available Templates

There are 7 templates available for creating new resources:

Template	Description	Steps
Create Business Unit	New BU with automated PR and pipeline validation	3 steps: BU config, GitHub teams, review
Create Tenant	Multi-step tenant creation within a business unit	6 steps: BU selection, tenant config, branching model, environments, teams, CODEOWNERS
Create Sandbox Project	Customizable sandbox GCP project	Variable based on configuration

Custom Scaffolder Actions

Action	Description
create-pr	Creates a GitHub Pull Request with generated content
pr-checks	Waits for pipeline checks to complete (polls every 30s, up to 30 minutes)
create-terraform-module	Generates Terraform module scaffolding
validate-tenant-name	Validates tenant naming conventions

Custom Field Extensions

Extension	Description
GithubRepoPicker	Repository selection with topic-based filtering
GithubTeamPicker	Team selection from the GitHub organization
GithubRepoVariablePicker	Extracts and displays GitHub repository variables
TerraformVariablesEditorExtension	Interactive HCL variable editing

Infrastructure

Networking

Resource	CIDR / Details
VPC	private-network
Backstage subnet	10.1.0.0/28
Dev pods subnet	10.1.254.0/24
GitHub runners subnet	10.2.1.0/24
Cloud NAT	Outbound connectivity for Cloud Run and VMs

Database

Property	Value
Type	Cloud SQL (PostgreSQL)
Password management	Secret Manager
Access	Private IP via VPC

HashiCorp Vault

Property	Value
Deployment	VM-based
Auto-unseal	Google Cloud KMS
Internal LB	10.1.0.10:8200
Access	IAP (Identity-Aware Proxy) for administrative access

KMS

Property	Value
Key Ring	vault-keyring
Unseal Key	vault-unseal-key
Rotation	30-day automatic rotation

Service Accounts

Service Account	Purpose
backstage-app	Backstage application runtime
vault-app	HashiCorp Vault runtime
gemini-agent	Gemini Agent Cloud Run instances

Repository

Repository	Purpose
badal-io/repo-devex-backstage	Backstage application code and Terraform infrastructure