How gorizond/gorizond-cluster works
Project Type and Purpose
• This is a Kubernetes Operator (written in Go) that automates provisioning and management of distributed K3s clusters.
• It uses Custom Resource Definitions (CRDs), the operator pattern (Kubebuilder), Helm charts, Rancher Fleet (GitOps), and integrates Headscale/Tailscale for secure networking.
Main Components
a. Kubernetes Control Plane
• API Server (handles CRD objects)
• etcd (implicit)
b. Gorizond Operator (Controller Manager)
• Go binary (main.go)
• Watches Cluster CRDs under group provisioning.gorizond.io/v1
• Controller loops (billing, cluster provisioning, reconnection)
c. Custom Resources
• Cluster CRD
• Billing and BillingEvent CRDs
d. Datastores
• PostgreSQL / MySQL (DB_DSN_HEADSCALE, DB_DSN_KUBERNETES)
e. Headscale Server Instances
• One per provisioned cluster
f. Install-Server Helm Chart
• nginx-based HTTP server serving install scripts
• Generates Tailscale + K3s bootstrap script
g. Rancher Fleet GitOps
• Fleet repository (manages fleet.yaml in each chart)
• Applies Helm releases (gorizond-cluster-controller, install-server)
h. Target K3s Worker Nodes
• Fetch install script from install-server
• Join Tailscale mesh and K3s cluster
Relationships and Data Flows
1. User applies a Cluster CRD to the K8s API server.
2. API Server persists CRD; Operator’s informer sees new object.
3. Gorizond Operator reads Cluster.spec, writes provisioning state to DB.
4. Operator deploys:
• A Headscale server (as a Deployment + Service via Helm)
• The install-server Helm chart (nginx) under that cluster’s namespace
• K3s cluster bootstrap jobs or manifests via Rancher Fleet (using fleet.yaml)
5. Operator updates CRD status as cluster comes up.
6. Admin/automation fetches the install script (HTTP GET) from install-server.
7. Worker node runs script:
• Installs Tailscale, auths against Headscale
• Installs K3s agent, joins the cluster control plane over Tailscale
8. Tailscale mesh ensures secure networking among nodes and control plane.
Architectural Patterns and Design Principles
• Kubernetes Operator Pattern: control loops, informers, reconcilers.
• CRD-driven declarative state.
• GitOps via Rancher Fleet: Helm charts (gorizond-cluster-controller, install-server).
• Isolation per cluster: dedicated Headscale & install-server per CRD.
• Externalized configuration: DB credentials, domain names via environment vars in Helm values.
Essential Elements
• Clear labels for:
• CRD types (Cluster, Billing, BillingEvent)
• Helm charts (gorizond-cluster-controller, install-server)
• External systems (Postgres/MySQL, Rancher Fleet)
• Kubernetes-native components
• Operator code
• External services
• Worker nodes