Terraform provisions the infrastructure · Helm packages the application · Kubernetes runs the workloads · Same code, any cloud
What it does: Declares the entire cloud infrastructure in code files. Run one command → everything exists. Run another → everything is gone.
Directory: terraform/ — 9 modules, 3+ environment configs
Key commands:
terraform plan — Preview what will change (safe, read-only)
terraform apply — Create or update all infrastructure
terraform destroy — Tear everything down cleanly
State: Stored in Azure Blob / S3 / GCS — encrypted, locked, versioned. Zero secrets in state files (uses Managed Identity references).
terraform plan — Shows exactly what will be created, modified, or destroyed before making any changes.
Like a construction blueprint review — you see every change before the builders start. No surprises.
Output example: "Plan: 23 to add, 2 to change, 0 to destroy"
terraform apply — Creates all infrastructure: Kubernetes cluster, databases, search service, vault, networking, DNS.
Then helm install deploys the application workloads into the cluster.
Full stack from zero: One terraform apply + helm install = entire platform running.
helm upgrade cerebro-app ./helm/cerebro-app — Rolling update, zero downtime.
What can be upgraded:
→ Application code (new Docker image)
→ Configuration (env vars, secrets, replicas)
→ Infrastructure (Terraform detects drift and reconciles)
→ Plugins (hot-reload via MCP engine API)
Rollback: helm rollback cerebro-app 1 — instant revert to previous version.
terraform destroy — Removes ALL infrastructure cleanly. Every resource, every service, every DNS record.
Useful for: dev/test environments, cost optimization, migration between clouds.
Safety: Requires explicit confirmation. State file records what was created, so destroy is precise — no orphaned resources.
Each module abstracts one cloud service into a cloud-agnostic interface:
🆔 Identity: Azure Managed Identity / AWS IAM Roles / GCP Workload Identity
☸️ Kubernetes: AKS / EKS / GKE — same K8s API, different provisioning
💾 Database: Cosmos DB / DynamoDB / Firestore
🔍 Search: Azure AI Search / OpenSearch / Vertex AI Search
🤖 LLM: Azure OpenAI / AWS Bedrock / Vertex AI
🔐 Vault: Azure Key Vault / AWS Secrets Manager / GCP Secret Manager
📦 Registry: ACR / ECR / Artifact Registry
🌐 Networking: VNet / VPC / Ingress controllers
🌍 DNS: Azure DNS / Route 53 / Cloud DNS
The app code never references cloud-specific APIs — only the Terraform modules change per cloud.
Helm packages Kubernetes manifests into versioned, configurable releases:
cerebro-app: The main platform — Flask app, ingress, TLS, HPA autoscaling, service account with workload identity.
mcp-engine: Each MCP engine gets its own Helm release in its own namespace. Deploy new engines by adding a release.
monitoring: Full observability stack — Prometheus, Grafana, Loki, Promtail, AlertManager, dashboards.
Values files: values-azure.yaml, values-aws.yaml, values-local.yaml — same chart, different cloud configs.
Runs the main Cerebro app — the Flask web server, OIDC auth, agent loop, Visual Designer, all API endpoints.
Pods: cerebro-app (4 Gunicorn workers), ingress-nginx controller
TLS: cert-manager auto-provisions Let's Encrypt certificates
Secrets: Cosmos endpoint, search keys, LLM keys, SSO secret — all injected via Helm values
Each MCP engine runs in its own Kubernetes namespace for isolation. Deploy additional engines (mcp2, mcp-healthcare, mcp-finance) as separate Helm releases.
Ports: 5000 (dashboard/API), 5001 (MCP transport — SSE/HTTP)
Plugins: Mounted as volumes or uploaded via API. Each plugin is a ZIP with manifest + Python code.
Scaling: Each engine scales independently based on load.
Full observability stack running alongside the application:
Prometheus: Scrapes metrics from all pods via ServiceMonitors
Grafana: Dashboards for platform, MCP, RAG, security, users, Loki logs
Loki + Promtail: Aggregates all pod logs, searchable with LogQL
Alertmanager: Fires alerts on high error rates, slow tools, pod crashes, disk/memory pressure
Fully wired and running. cd terraform/environments/azure && terraform apply
AKS (D4ds_v5 nodes), Cosmos DB, Azure AI Search, Azure OpenAI (GPT-4o), Key Vault, ACR, Application Gateway
Security: Managed Identity for all service-to-service auth — zero API keys stored in pods.
Same Terraform modules, AWS provider. cd terraform/environments/aws && terraform apply
EKS, DynamoDB, OpenSearch, Bedrock (Claude/Titan), Secrets Manager, ECR
Security: IAM Roles for Service Accounts (IRSA) — same zero-key pattern as Azure.
Same Terraform modules, GCP provider. cd terraform/environments/gcp && terraform apply
GKE, Firestore, Vertex AI Search, Vertex AI (Gemini), Secret Manager, Artifact Registry
Security: Workload Identity Federation — same zero-key pattern.
For development, demos, and air-gapped deployments. docker-compose up
Docker Compose, SQLite (no Cosmos needed), Ollama (free local LLM), file-based vault
No cloud account required. Everything runs on a single machine.