Synapse Platform Control Plane - manages fleet clusters via Flux GitOps.
┌─────────────────────────────────────────────────────────────────────┐
│ CORTEX (Platform Cluster) │
│ │
│ Flux manages: │
│ ├── Platform infrastructure (Crossplane, Kyverno, etc.) │
│ ├── Argo CD installation on fleet clusters │
│ └── Tenant boundaries (namespaces, quotas, RBAC) │
└─────────────────────────────────────────────────────────────────────┘
│
│ Deploys control plane TO
▼
┌─────────────────────────────────────────────────────────────────────┐
│ FLEET CLUSTERS (Spokes) │
│ │
│ Argo CD manages: │
│ ├── Application workloads │
│ └── Product team resources │
└─────────────────────────────────────────────────────────────────────┘
cortex/
├── hub/ # Flux entry point (bootstrapped to cortex)
│ ├── flux-system/ # Flux components (auto-generated)
│ ├── cortex.yaml # Platform cluster Kustomizations
│ └── dev.yaml # Dev fleet cluster Kustomizations
│
├── clusters/ # Per-cluster overlays
│ ├── cortex/ # Platform cluster
│ ├── dev/ # Fleet: dev environment
│ └── production/ # Fleet: production environment
│
├── plane/ # Shared base definitions
│ ├── control/ # Control plane components
│ │ ├── crossplane/ # Crossplane + providers + configs
│ │ ├── argocd/ # Argo CD
│ │ └── tools/ # Argo Workflows, Flink, etc.
│ ├── infrastructure/ # Infrastructure components
│ │ ├── gateway/ # kgateway controller + CRDs
│ │ ├── istio/ # Istio service mesh
│ │ └── tailscale/ # Tailscale operator
│ └── security/ # Security components
│ ├── cert-manager/ # Certificate management
│ └── kyverno/ # Policy engine
│
├── apis/ # Crossplane composition packages
│ └── management/ # Platform API definitions
│ ├── apis/tenant/ # Tenant XRD + Composition
│ └── functions/ # Composition functions
│
├── pkg/ # Shared Go libraries
│ ├── composer/ # XR field accessor + error accumulator
│ └── resources/ # k8s resource builders
│
├── kind/ # Kind cluster configurations
├── scripts/ # Shell scripts
└── go.work # Go workspace
Flux applies in order: tenants → controllers → config
Each namespace has its own set:
flux-system/tenants→flux-system/controllers→flux-system/config(platform)dev/tenants→dev/controllers→dev/config(fleet dev)
| Command | Description |
|---|---|
just fleet-up |
Create Kind clusters |
just fleet-down |
Destroy clusters |
just fleet-status |
Check cluster health |
just bootstrap <owner> <repo> |
Bootstrap Flux |
just flux-status |
View Flux status |
just flux-reconcile |
Force reconciliation |
just validate |
Validate manifests |
Fleet cluster services are exposed via Tailscale for secure access without port-forwarding.
-
Create OAuth client at https://login.tailscale.com/admin/settings/oauth
- Scopes:
devices:write,dns:write - Tag:
tag:k8s(or your preferred tag)
- Scopes:
-
Create the secret on cortex cluster before bootstrapping:
kubectl --context kind-cortex create namespace dev
kubectl --context kind-cortex create secret generic tailscale-oauth \
--namespace dev \
--from-literal=clientId=<your-client-id> \
--from-literal=clientSecret=<your-client-secret>Services are exposed via kgateway with TLS termination on custom domains.
Architecture:
Client → DNS → Tailscale (encrypted) → LoadBalancer → kgateway (TLS) → Service
Or use an A record pointing to the Tailscale IP (check with kubectl get svc synapse-gateway -n kgateway-system).
Certificate:
Development uses a self-signed CA. Browser will show a certificate warning.
For production, configure Let's Encrypt with DNS-01 challenge:
- Create a ClusterIssuer with your DNS provider credentials
- Update
deploy/config/gateway/issuer.yamlto use Let's Encrypt - Update
deploy/config/gateway/certificate.yamlissuer reference
- Create overlay in
clusters/<env>/ - Create hub file
hub/<env>.yaml - Add to
hub/kustomization.yaml - Create kubeconfig secret in
<env>namespace on cortex