Status

Table of Contents

Blueberry IDP Deployment Topology

This document illustrates how the Blueberry IDP components are deployed within the Google Cloud Platform and Kubernetes infrastructure.

Deployment Overview

graph TB subgraph "Internet" USERS[Users/Developers] GITHUB[GitHub/GitLab] end subgraph "Google Cloud Platform" subgraph "Networking" LB[Cloud Load Balancer
with SSL] DNS[Cloud DNS
*.blueberry.dev] end subgraph "GKE Autopilot Cluster" subgraph "kube-system" INGRESS[Nginx Ingress
Controller] CERTMGR[Cert Manager] METRICS[Metrics Server] end subgraph "argocd namespace" ARGO_SERVER[ArgoCD Server] ARGO_REPO[ArgoCD Repo Server] ARGO_APP[ArgoCD App Controller] ARGO_REDIS[(ArgoCD Redis)] end subgraph "blueberry namespace" subgraph "Blueberry App" API_POD1[API Pod 1
FastAPI] API_POD2[API Pod 2
FastAPI] API_PODN[API Pod N
FastAPI] end REDIS[(Redis Cache
StatefulSet)] REDIS_SENTINEL[Redis Sentinel] end subgraph "external-secrets namespace" ES_OPERATOR[External Secrets
Operator] ES_WEBHOOK[ES Webhook] end subgraph "crossplane-system namespace" CROSS_CORE[Crossplane Core] CROSS_GCP[GCP Provider] end subgraph "Environment Namespaces" subgraph "pr-123" APP1[Application Pods] SVC1[Services] ING1[Ingress] end subgraph "pr-456" APP2[Application Pods] SVC2[Services] ING2[Ingress] end subgraph "feature-xyz" APPN[Application Pods] SVCN[Services] INGN[Ingress] end end end subgraph "GCP Services" FIRESTORE[(Cloud Firestore
NoSQL Database)] GCS[(Cloud Storage
Artifacts & Logs)] SECRET_MGR[Secret Manager
API Keys & Secrets] FIREBASE[Firebase Auth
User Authentication] MONITORING[Cloud Monitoring
& Logging] ARTIFACT_REG[Artifact Registry
Container Images] end end %% External connections USERS --> LB GITHUB --> ARGO_APP LB --> INGRESS DNS --> LB %% Ingress routing INGRESS --> API_POD1 INGRESS --> API_POD2 INGRESS --> API_PODN INGRESS --> ARGO_SERVER INGRESS --> ING1 INGRESS --> ING2 INGRESS --> INGN %% Internal connections API_POD1 --> REDIS API_POD2 --> REDIS API_PODN --> REDIS API_POD1 --> FIRESTORE API_POD1 --> GCS API_POD1 --> SECRET_MGR API_POD1 --> FIREBASE ARGO_APP --> GITHUB ARGO_APP --> ARTIFACT_REG ARGO_SERVER --> ARGO_REDIS ES_OPERATOR --> SECRET_MGR CROSS_CORE --> GCS %% Monitoring API_POD1 -.-> MONITORING ARGO_APP -.-> MONITORING APP1 -.-> MONITORING classDef external fill:#e3f2fd,stroke:#1976d2,stroke-width:2px classDef network fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:2px classDef app fill:#fff3e0,stroke:#f57c00,stroke-width:2px classDef env fill:#fce4ec,stroke:#c2185b,stroke-width:2px classDef gcp fill:#fffde7,stroke:#f9a825,stroke-width:2px class USERS,GITHUB external class LB,DNS network class INGRESS,CERTMGR,METRICS system class ARGO_SERVER,ARGO_REPO,ARGO_APP,ARGO_REDIS,API_POD1,API_POD2,API_PODN,REDIS,REDIS_SENTINEL,ES_OPERATOR,ES_WEBHOOK,CROSS_CORE,CROSS_GCP app class APP1,SVC1,ING1,APP2,SVC2,ING2,APPN,SVCN,INGN env class FIRESTORE,GCS,SECRET_MGR,FIREBASE,MONITORING,ARTIFACT_REG gcp

Deployment Components

External Access Layer

  • Cloud Load Balancer: Google Cloud Load Balancer with SSL termination
  • Cloud DNS: Manages *.blueberry.dev domain with automatic subdomain routing
  • Users/Developers: Access via web browsers or CI/CD systems
  • GitHub/GitLab: Source repositories for GitOps

Kubernetes System Components

  • Nginx Ingress Controller: Routes HTTP/HTTPS traffic to services
  • Cert Manager: Automated TLS certificate management via Let's Encrypt
  • Metrics Server: Provides resource metrics for HPA and monitoring

ArgoCD Components (GitOps)

  • ArgoCD Server: Web UI and API server
  • ArgoCD Repo Server: Git repository cache and manifest generation
  • ArgoCD App Controller: Reconciles desired state with actual state
  • ArgoCD Redis: Caching and session storage for ArgoCD

Blueberry Application

  • API Pods: Multiple FastAPI instances for high availability
  • Horizontal Pod Autoscaler (HPA) for dynamic scaling
  • Rolling updates for zero-downtime deployments
  • Redis Cache: StatefulSet with persistent volumes
  • Master-slave replication for HA
  • Sentinel for automatic failover

Supporting Operators

  • External Secrets Operator: Syncs secrets from Google Secret Manager
  • Crossplane: Provisions GCP resources via Kubernetes CRDs

Environment Namespaces

Each environment gets its own namespace with:
- Application pods specific to that environment
- Services for internal communication
- Ingress for external access via subdomain
- Network policies for isolation
- Resource quotas to prevent resource exhaustion

GCP Managed Services

  • Cloud Firestore: NoSQL database for application metadata
  • Cloud Storage: Object storage for artifacts and logs
  • Secret Manager: Secure storage for sensitive data
  • Firebase Auth: User authentication service
  • Cloud Monitoring: Metrics, logs, and alerting
  • Artifact Registry: Container image storage

Network Flow

Inbound Traffic Flow

  1. User request to pr-123.blueberry.dev
  2. DNS resolves to Cloud Load Balancer IP
  3. Load Balancer terminates SSL
  4. Traffic forwarded to Nginx Ingress
  5. Ingress routes to appropriate service
  6. Service load balances to pod endpoints

GitOps Flow

  1. Developer pushes code to Git
  2. CI/CD builds and pushes images to Artifact Registry
  3. ArgoCD polls Git repository
  4. ArgoCD detects changes
  5. ArgoCD applies manifests to cluster
  6. Kubernetes creates/updates resources

High Availability

Application Layer

  • Multiple API pod replicas across zones
  • Horizontal Pod Autoscaler for dynamic scaling
  • Pod Disruption Budgets for safe updates
  • Liveness and readiness probes

Data Layer

  • Redis with master-slave replication
  • Firestore with automatic replication
  • GCS with multi-region storage
  • Regular backups of critical data

Infrastructure Layer

  • GKE Autopilot manages node availability
  • Multi-zone deployment by default
  • Automatic node repair and upgrade
  • Resource reservations for system components

Security Layers

Network Security

  • Private GKE cluster with authorized networks
  • Network policies for pod-to-pod communication
  • Ingress rules for external access
  • Service mesh consideration for future

Identity & Access

  • Workload Identity for GCP service authentication
  • RBAC for Kubernetes resource access
  • Firebase Auth for user authentication
  • API tokens for programmatic access

Data Security

  • Encryption in transit (TLS everywhere)
  • Encryption at rest (GCP managed keys)
  • Secret Manager for sensitive data
  • No secrets in container images or Git

Scaling Strategies

Horizontal Scaling

  • HPA for API pods based on CPU/memory
  • Event-driven scaling for webhook processing
  • Cluster autoscaling via GKE Autopilot

Vertical Scaling

  • Right-sizing based on metrics
  • Resource requests and limits
  • Quality of Service (QoS) classes

Monitoring & Observability

Metrics Collection

  • Prometheus metrics from applications
  • GCP Cloud Monitoring for infrastructure
  • Custom metrics for business KPIs

Logging Pipeline

  • Structured JSON logs from pods
  • Cloud Logging aggregation
  • Log-based metrics and alerts

Tracing

  • Correlation IDs across services
  • Distributed tracing consideration
  • Performance profiling

Disaster Recovery

Backup Strategy

  • Firestore automated backups
  • GCS object versioning
  • Git as source of truth
  • Infrastructure as Code

Recovery Procedures

  • Automated cluster recreation
  • GitOps-based application restoration
  • Data recovery from backups
  • Runbook documentation

Cost Optimization

Resource Efficiency

  • GKE Autopilot for pay-per-pod
  • Spot instances for non-critical workloads
  • Automatic environment cleanup
  • Resource quotas and limits

Monitoring & Alerts

  • Cost tracking per environment
  • Budget alerts
  • Resource utilization reports
  • Optimization recommendations
Document ID: architecture/diagrams/deployment-topology