Skip to content

architecture.md

Latest commit

 

History

History
150 lines (133 loc) · 8.38 KB

architecture.md

File metadata and controls

150 lines (133 loc) · 8.38 KB

Architecture: OrbStack Kubernetes & ArgoCD Bootstrap

Component Diagram

┌─────────────────────────────────────────────────────────────────────────────┐
│                            macOS ARM (Apple Silicon)                        │
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────────┐ │
│  │                          OrbStack Runtime                               │ │
│  │                                                                         │ │
│  │  ┌──────────────────────────────────────────────────────────────────┐   │ │
│  │  │              Kubernetes 1.31.x (Single Node)                     │   │ │
│  │  │                                                                  │   │ │
│  │  │  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────┐ │   │ │
│  │  │  │   argocd     │  │ ingress-nginx│  │    cert-manager        │ │   │ │
│  │  │  │              │  │              │  │                        │ │   │ │
│  │  │  │ ArgoCD 3.1.9 │  │ ingress-nginx│  │ cert-manager 1.19.3   │ │   │ │
│  │  │  │ (Helm 9.0.1) │  │   4.14.3     │  │ + SelfSigned CA chain │ │   │ │
│  │  │  └──────────────┘  └──────────────┘  └────────────────────────┘ │   │ │
│  │  │                                                                  │   │ │
│  │  │  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────┐ │   │ │
│  │  │  │sealed-secrets│  │  monitoring  │  │    sample-app          │ │   │ │
│  │  │  │              │  │              │  │                        │ │   │ │
│  │  │  │ sealed-      │  │ kube-prom-   │  │ nginx:1.27-alpine     │ │   │ │
│  │  │  │ secrets 2.18 │  │ stack 81.5.2 │  │ (validation only)     │ │   │ │
│  │  │  └──────────────┘  └──────────────┘  └────────────────────────┘ │   │ │
│  │  │                                                                  │   │ │
│  │  │  ┌────────────────────────────────────────────────────────────┐  │   │ │
│  │  │  │                    kube-system                              │  │   │ │
│  │  │  │  CoreDNS · kube-proxy · Flannel CNI                        │  │   │ │
│  │  │  └────────────────────────────────────────────────────────────┘  │   │ │
│  │  └──────────────────────────────────────────────────────────────────┘   │ │
│  │                                                                         │ │
│  │  DNS: *.k8s.orb.local → cluster LoadBalancer (automatic)                │ │
│  └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘

Network Topology

External (Browser)
       │
       ▼
OrbStack DNS (*.k8s.orb.local)
       │
       ▼
┌──────────────────────────────┐
│  ingress-nginx (LoadBalancer)│
│  Port 80/443                 │
└──────────┬───────────────────┘
           │
    ┌──────┼──────────────────────────────┐
    │      │                              │
    ▼      ▼                              ▼
 argocd  grafana                     sample-app
 .k8s.   .k8s.                      .k8s.
 orb.    orb.                        orb.
 local   local                       local

Sync-Wave Ordering

ArgoCD deploys infrastructure components in dependency order using sync-wave annotations:

Wave 0: cert-manager
        └── CRDs must exist before ClusterIssuers can be created
        └── ServerSideApply=true for CRD management

Wave 1: ingress-nginx, sealed-secrets (parallel)
        └── ingress-nginx: provides Ingress routing for all services
        └── sealed-secrets: enables encrypted secret management

Wave 2: kube-prometheus-stack
        └── Depends on ingress-nginx for Grafana ingress
        └── ServerSideApply=true for large CRDs
        └── ServiceMonitors target components from waves 0-1

Wave 3: namespace-templates
        └── Depends on cert-manager for TLS (ClusterIssuer)
        └── Depends on ingress-nginx for sample app routing
        └── Depends on monitoring for ServiceMonitor scraping

GitOps Data Flow

Git Repository (source of truth)
       │
       │  argocd/applications/ (App-of-Apps directory)
       │
       ▼
┌─────────────────────────────────┐
│  ArgoCD (argocd namespace)      │
│                                 │
│  root-app-of-apps               │
│    ├── ingress-nginx  (Helm)    │
│    ├── cert-manager   (Helm)    │
│    ├── sealed-secrets (Helm)    │
│    ├── kube-prom-stack(Helm)    │
│    └── namespace-tmpl (Kustom.) │
│                                 │
│  Multi-Source Pattern:          │
│    Source 1: Helm chart (repo)  │
│    Source 2: Git values ($vals) │
└─────────────────────────────────┘
       │
       │  Reconcile → Apply
       ▼
  Kubernetes Cluster (desired state)

TLS Certificate Chain

selfsigned-issuer (ClusterIssuer: SelfSigned)
       │
       │  Issues
       ▼
local-ca (Certificate: isCA=true)
       │  namespace: cert-manager
       │  secret: local-ca-key-pair
       │  duration: 10 years
       │
       │  Backs
       ▼
local-ca-issuer (ClusterIssuer: CA)
       │
       │  Issues
       ├──► argocd.k8s.orb.local (TLS)
       ├──► grafana.k8s.orb.local (TLS)
       └──► sample.k8s.orb.local (TLS)

Resource Budget (Local Development)

Component CPU Request CPU Limit Mem Request Mem Limit
ArgoCD (all) ~150m ~500m ~384Mi ~768Mi
ingress-nginx 100m 200m 128Mi 256Mi
cert-manager 30m 100m 64Mi 128Mi
sealed-secrets 20m 100m 64Mi 128Mi
Prometheus 50m 200m 256Mi 512Mi
Grafana 30m 100m 128Mi 256Mi
Total ~380m ~1200m ~1024Mi ~2048Mi

Budget is optimized for local development on machines with 4+ CPU cores and 8+ GiB RAM. kube-prometheus-stack components disabled for OrbStack: kubeEtcd, kubeControllerManager, kubeScheduler, kubeProxy.