Infrastructure Overview

The DevEx Backstage Platform infrastructure is managed via Terraform and deployed on Google Cloud Platform (GCP). This documentation covers the infrastructure architecture, environments, and key resources.

Directory Structure

terraform/
├── common/              # Shared infrastructure modules (called by both environments)
│   ├── main.tf          # Primary resource definitions (~880 lines)
│   ├── variables.tf     # Input variables
│   ├── outputs.tf       # Output values
│   ├── versions.tf      # Provider requirements
│   └── templates/       # Cloud-init and Vault configuration templates
│
├── modules/             # Reusable Terraform modules
│   └── gh-runner-mig-arm64/  # ARM64 GitHub Actions runners
│
├── non-production/      # Non-prod environment configuration
│   ├── main.tf          # Calls common module
│   ├── backend.tf       # Terraform Cloud backend
│   └── remote.tf        # Remote data sources
│
└── production/          # Production environment configuration
    ├── main.tf          # Calls common module
    ├── backend.tf       # Terraform Cloud backend
    └── remote.tf        # Remote data sources

Environments

Environment	TFC Workspace	Auto-Deploy	Purpose
Non-Production	wrkspc-np-devex-backstage	✅ Yes	Development and staging
Production	wrkspc-p-devex-backstage	❌ Manual	Production deployment

Both environments use the same common/ module, with environment-specific variables provided via Terraform Cloud workspace variables.

Architecture Diagram

Key Resources

Networking

Resource	Purpose	CIDR/Details
private-network VPC	Main network	Primary region: northamerica-northeast1
shared-subnet	Backstage & Vault services	10.1.0.0/28
devpods-subnet	DevPods infrastructure	10.1.254.0/24
github-actions-subnet	GitHub runners	10.2.1.0/24 (us-central1)
VPC Connector	Cloud Run → private resources	e2-micro, 2-3 instances
Cloud NAT	Outbound internet access	All subnets

Compute

Resource	Type	Purpose
Vault Instance	e2-standard-2	Secrets management
Vault Data Disk	50GB SSD	Persistent Vault storage
GitHub Runners	ARM64 T2A	CI/CD job execution

Database

Resource	Details
Cloud SQL Instance	PostgreSQL 15, db-g1-small
Database	backstage-db
User	backstage with random 32-char password
Network	Private IP only (via service networking)

Storage

Bucket	Purpose
{project}-backstage-techdocs	TechDocs storage
{project}-vault-config	Vault configuration files

Security

Resource	Purpose
vault-keyring	KMS keyring for Vault auto-unseal
vault-unseal-key	RSA encryption key (30-day rotation)
Service Accounts	backstage-app, vault-app
IAP OAuth Client	Secure external Vault access
Self-signed TLS	Vault internal communication

Service Accounts & IAM

Backstage Service Account (backstage-app)

Role	Purpose
cloudsql.client	Connect to Cloud SQL
iam.serviceAccountTokenCreator	Create Vault tokens
secretmanager.secretAccessor	Access Vault CA cert
storage.objectCreator	Write TechDocs

Vault Service Account (vault-app)

Role	Purpose
cloudkms.cryptoKeyEncrypterDecrypter	KMS auto-unseal
compute.viewer	List compute instances
logging.logWriter	Write logs
monitoring.metricWriter	Write metrics
storage.objectViewer	Read Vault config

Vault Architecture

Vault Components

• Instance: Ubuntu 22.04, e2-standard-2, Shielded VM
• Internal LB: 10.1.0.10:8200 for Cloud Run access
• External LB: HTTPS + IAP for admin access
• Auto-unseal: GCP KMS key with 30-day rotation
• TLS: Self-signed certificate for internal traffic

GitHub Actions Runners

The gh-runner-mig-arm64 module provisions ARM64 GitHub Actions runners:

Feature	Configuration
Architecture	ARM64 (T2A/C4A)
Container	Ubuntu 22.04 + Docker-in-Docker
Authentication	GitHub App (ID: 1998375)
Ephemeral	Single job execution
Region	us-central1 (ARM64 availability)
Zones	a, b, f (excluding c for ARM64)

Runner Labels

["arm64", "ubuntu", "docker", "gcp", "basic-example", "{env_type}"]

Terraform Cloud Integration

Workspace Configuration

terraform {
  cloud {
    organization = "Badal_devex"
    workspaces {
      name = "wrkspc-np-devex-backstage"  # or wrkspc-p-devex-backstage
    }
  }
}

Variables (Provided by TFC)

Variable	Type	Description
project_id	string	GCP Project ID
region	string	Primary region
zone	string	Primary zone
env_type	string	nonprod or prod
backstage_url	string	Backstage application URL
github_private_key	sensitive	GitHub App private key

Outputs

The common module exports these values for use by CI/CD:

Output	Purpose
backstage_cloud_sql_instance_connection_name	Cloud SQL connection
backstage_vpc_connector_id	VPC connector for Cloud Run
backstage_service_account_email	Cloud Run service account
backstage_db_password_secret_id	DB password secret
vault_internal_url	Vault URL for backend
vault_external_ip	Vault external access
vault_iap_audience	IAP audience for JWT

Related Documentation

• ARM64 Runner Module - GitHub Actions runners module