# gorizond/gorizond-cluster architecture

> Architecture diagram of the GitHub repository gorizond/gorizond-cluster, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gorizond/gorizond-cluster
- Repository: https://github.com/gorizond/gorizond-cluster

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Kubernetes Control Plane"
        APIS["API Server"]:::control
    end

    APIS -->|"Persist CRD"| OperatorMgr["Gorizond Operator (Controller Manager)"]:::operator

    subgraph "Operator Controller Manager (Go)"
        OpBin["main.go"]:::operator
        ControllersCl["controllers/gorizond_cluster.go"]:::operator
        ControllersRec["controllers/reconnect_cluster.go"]:::operator
        ControllersBill["controllers/billing.go"]:::operator
        ControllersBillDec["controllers/billing_decrease_controller.go"]:::operator
        ControllersBillEvt["controllers/billing_event.go"]:::operator
        CRDTypes1["pkg/apis/provisioning.gorizond.io/v1/types.go"]:::operator
        CRDTypes2["pkg/apis/provisioning.gorizond.io/v1/zz_generated_deepcopy.go"]:::operator
        CRDTypes3["pkg/apis/provisioning.gorizond.io/v1/zz_generated_list_types.go"]:::operator
        CRDTemplate1["charts/gorizond-cluster-controller/templates/crd-clusters.yaml"]:::operator
        CRDTemplate2["charts/gorizond-cluster-controller/templates/crd-billing.yaml"]:::operator
        CRDTemplate3["charts/gorizond-cluster-controller/templates/crd-billing-event.yaml"]:::operator
        GenFact1["pkg/generated/controllers/provisioning.gorizond.io/v1/cluster.go"]:::operator
        GenFact2["pkg/generated/controllers/provisioning.gorizond.io/v1/billing.go"]:::operator
        GenFact3["pkg/generated/controllers/provisioning.gorizond.io/v1/billingevent.go"]:::operator
        GenFact4["pkg/generated/controllers/provisioning.gorizond.io/factory.go"]:::operator
        GenFact5["pkg/generated/controllers/provisioning.gorizond.io/interface.go"]:::operator
    end

    OperatorMgr --> OpBin
    OpBin --> ControllersCl
    OpBin --> ControllersRec
    OpBin --> ControllersBill
    OpBin --> ControllersBillDec
    OpBin --> ControllersBillEvt
    OpBin --> CRDTypes1
    OpBin --> CRDTypes2
    OpBin --> CRDTypes3
    OpBin --> CRDTemplate1
    OpBin --> CRDTemplate2
    OpBin --> CRDTemplate3
    OpBin --> GenFact1
    OpBin --> GenFact2
    OpBin --> GenFact3
    OpBin --> GenFact4
    OpBin --> GenFact5

    OperatorMgr -->|"Write state"| DB["PostgreSQL / MySQL"]:::external
    OperatorMgr -->|"helm install"| OpHelm["Operator Helm Chart"]:::external

    subgraph "Operator Helm Chart"
        OpChartY["charts/gorizond-cluster-controller/Chart.yaml"]:::external
        OpChartV["charts/gorizond-cluster-controller/values.yaml"]:::external
        OpChartF["charts/gorizond-cluster-controller/fleet.yaml"]:::external
        OpChartDep["charts/gorizond-cluster-controller/templates/deployment.yaml"]:::external
        OpChartSA["charts/gorizond-cluster-controller/templates/serviceaccount.yaml"]:::external
        OpChartHPA["charts/gorizond-cluster-controller/templates/hpa.yaml"]:::external
    end

    OperatorMgr --> OpChartY
    OperatorMgr --> OpChartV
    OperatorMgr --> OpChartF
    OperatorMgr --> OpChartDep
    OperatorMgr --> OpChartSA
    OperatorMgr --> OpChartHPA

    OperatorMgr -->|"Commit fleet.yaml"| FleetRepo["Rancher Fleet Git Repo"]:::external
    FleetRepo -->|"Sync Charts"| K8sSync["Kubernetes (Helm Releases)"]:::control

    subgraph "Per-Cluster Resources"
        Headscale["Headscale Server Deployment + Service"]:::nodes
        InstallServ["install-server (nginx)"]:::nodes
    end

    K8sSync -->|"helm install Headscale & install-server"| Headscale
    K8sSync --> Headscale & InstallServ

    subgraph "Install-Server Helm Chart"
        ISChartY["charts/install-server/Chart.yaml"]:::external
        ISChartV["charts/install-server/values.yaml"]:::external
        ISChartF["charts/install-server/fleet.yaml"]:::external
        ISConfig["charts/install-server/templates/configmap.yaml"]:::external
        ISDep["charts/install-server/templates/deployment.yaml"]:::external
        ISIngress["charts/install-server/templates/ingress.yaml"]:::external
        ISSettings["charts/install-server/templates/settings.yaml"]:::external
        ISTest["charts/install-server/templates/tests/test-connection.yaml"]:::external
    end

    InstallServ --> ISChartY
    InstallServ --> ISChartV
    InstallServ --> ISChartF
    InstallServ --> ISConfig
    InstallServ --> ISDep
    InstallServ --> ISIngress
    InstallServ --> ISSettings
    InstallServ --> ISTest

    Worker["Worker Node"]:::nodes
    Worker -->|"GET /install.sh"| InstallServ
    Worker -->|"Tailscale auth"| Headscale
    Worker -->|"K3s join"| APIS

    classDef control fill:#D0E8FF,stroke:#007ACC,color:#000;
    classDef operator fill:#DFF6DD,stroke:#2E7D32,color:#000;
    classDef external fill:#F0F0F0,stroke:#666,color:#000;
    classDef nodes fill:#FFF3E0,stroke:#E65100,color:#000;

    click OpBin "https://github.com/gorizond/gorizond-cluster/blob/main/main.go"
    click ControllersCl "https://github.com/gorizond/gorizond-cluster/blob/main/controllers/gorizond_cluster.go"
    click ControllersRec "https://github.com/gorizond/gorizond-cluster/blob/main/controllers/reconnect_cluster.go"
    click ControllersBill "https://github.com/gorizond/gorizond-cluster/blob/main/controllers/billing.go"
    click ControllersBillDec "https://github.com/gorizond/gorizond-cluster/blob/main/controllers/billing_decrease_controller.go"
    click ControllersBillEvt "https://github.com/gorizond/gorizond-cluster/blob/main/controllers/billing_event.go"
    click CRDTypes1 "https://github.com/gorizond/gorizond-cluster/blob/main/pkg/apis/provisioning.gorizond.io/v1/types.go"
    click CRDTypes2 "https://github.com/gorizond/gorizond-cluster/blob/main/pkg/apis/provisioning.gorizond.io/v1/zz_generated_deepcopy.go"
    click CRDTypes3 "https://github.com/gorizond/gorizond-cluster/blob/main/pkg/apis/provisioning.gorizond.io/v1/zz_generated_list_types.go"
    click CRDTemplate1 "https://github.com/gorizond/gorizond-cluster/blob/main/charts/gorizond-cluster-controller/templates/crd-clusters.yaml"
    click CRDTemplate2 "https://github.com/gorizond/gorizond-cluster/blob/main/charts/gorizond-cluster-controller/templates/crd-billing.yaml"
    click CRDTemplate3 "https://github.com/gorizond/gorizond-cluster/blob/main/charts/gorizond-cluster-controller/templates/crd-billing-event.yaml"
    click GenFact1 "https://github.com/gorizond/gorizond-cluster/blob/main/pkg/generated/controllers/provisioning.gorizond.io/v1/cluster.go"
    click GenFact2 "https://github.com/gorizond/gorizond-cluster/blob/main/pkg/generated/controllers/provisioning.gorizond.io/v1/billing.go"
    click GenFact3 "https://github.com/gorizond/gorizond-cluster/blob/main/pkg/generated/controllers/provisioning.gorizond.io/v1/billingevent.go"
    click GenFact4 "https://github.com/gorizond/gorizond-cluster/blob/main/pkg/generated/controllers/provisioning.gorizond.io/factory.go"
    click GenFact5 "https://github.com/gorizond/gorizond-cluster/blob/main/pkg/generated/controllers/provisioning.gorizond.io/interface.go"
    click OpChartY "https://github.com/gorizond/gorizond-cluster/blob/main/charts/gorizond-cluster-controller/Chart.yaml"
    click OpChartV "https://github.com/gorizond/gorizond-cluster/blob/main/charts/gorizond-cluster-controller/values.yaml"
    click OpChartF "https://github.com/gorizond/gorizond-cluster/blob/main/charts/gorizond-cluster-controller/fleet.yaml"
    click OpChartDep "https://github.com/gorizond/gorizond-cluster/blob/main/charts/gorizond-cluster-controller/templates/deployment.yaml"
    click OpChartSA "https://github.com/gorizond/gorizond-cluster/blob/main/charts/gorizond-cluster-controller/templates/serviceaccount.yaml"
    click OpChartHPA "https://github.com/gorizond/gorizond-cluster/blob/main/charts/gorizond-cluster-controller/templates/hpa.yaml"
    click ISChartY "https://github.com/gorizond/gorizond-cluster/blob/main/charts/install-server/Chart.yaml"
    click ISChartV "https://github.com/gorizond/gorizond-cluster/blob/main/charts/install-server/values.yaml"
    click ISChartF "https://github.com/gorizond/gorizond-cluster/blob/main/charts/install-server/fleet.yaml"
    click ISConfig "https://github.com/gorizond/gorizond-cluster/blob/main/charts/install-server/templates/configmap.yaml"
    click ISDep "https://github.com/gorizond/gorizond-cluster/blob/main/charts/install-server/templates/deployment.yaml"
    click ISIngress "https://github.com/gorizond/gorizond-cluster/blob/main/charts/install-server/templates/ingress.yaml"
    click ISSettings "https://github.com/gorizond/gorizond-cluster/blob/main/charts/install-server/templates/settings.yaml"
    click ISTest "https://github.com/gorizond/gorizond-cluster/blob/main/charts/install-server/templates/tests/test-connection.yaml"
```
