# starrocks/starrocks-kubernetes-operator architecture

> Architecture diagram of the GitHub repository starrocks/starrocks-kubernetes-operator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/starrocks/starrocks-kubernetes-operator
- Repository: https://github.com/starrocks/starrocks-kubernetes-operator

## Overview

This repository implements a Kubernetes operator for deploying and managing StarRocks clusters and warehouses. Users submit StarRocks custom resources; the operator reconciles them into Kubernetes workloads and services, tracks status, and supports scaling, upgrades, persistent volumes, FE/BE/CN separation, and warehouse-driven CN management. The README documents STREAM LOAD and autoscaling capabilities; the source index identifies related load and autoscaler modules, but their runtime wiring is not shown in the excerpts. Edges without direct excerpt or README support are omitted.

Main entry points: [`pkg/controllers/starrockscluster_controller.go`](https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/controllers/starrockscluster_controller.go) (Cluster reconciler), [`pkg/controllers/starrockswarehouse_controller.go`](https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/controllers/starrockswarehouse_controller.go) (Warehouse reconciler), [`pkg/subcontrollers/be/be_controller.go`](https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/subcontrollers/be/be_controller.go) (BE controller), [`pkg/subcontrollers/cn/cn_controller.go`](https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/subcontrollers/cn/cn_controller.go) (CN controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Operator runtime"]
  node_manager["Controller manager<br/>[main.go]"]
  node_registration["Controller registration<br/>[controllers.go]"]
end

subgraph group_api["Cluster API"]
  node_clustercr["Cluster resource"]
  node_warehousecr["Warehouse resource"]
end

subgraph group_reconcile["Reconciliation"]
  node_clusterrec["Cluster reconciler"]
  node_warehouserec["Warehouse reconciler"]
end

subgraph group_workloads["Workload management"]
  node_fe["FE controller<br/>[fe_controller.go]"]
  node_be["BE controller<br/>[be_controller.go]"]
  node_cn["CN controller<br/>[cn_controller.go]"]
  node_proxy["FE proxy"]
  node_status["Workload status<br/>[subcontroller.go]"]
  node_resource["Kubernetes resources<br/>[k8sutils.go]"]
  node_services["Service builder<br/>[service.go]"]
  node_podmount["Volume mounting<br/>[mount.go]"]
end

subgraph group_integrations["Operational features"]
  node_autoscale["CN autoscaling<br/>[autoscaler.go]"]
  node_load["STREAM LOAD support<br/>[load.go]"]
  node_mysql["FE SQL access<br/>[cn_mysql.go]"]
end

node_user(("Cluster operator"))
node_kube[("Kubernetes API")]

node_user -->|"applies resources"| node_kube
node_kube -.->|"watches resources"| node_manager
node_manager -->|"sets up controllers"| node_registration
node_registration -->|"registers"| node_clusterrec
node_registration -->|"registers"| node_warehouserec
node_clusterrec -->|"reads and updates"| node_clustercr
node_warehouserec -->|"reads and updates"| node_warehousecr
node_clusterrec -->|"reconciles FE"| node_fe
node_clusterrec -->|"reconciles BE"| node_be
node_clusterrec -->|"reconciles CN"| node_cn
node_clusterrec -->|"reconciles proxy"| node_proxy
node_warehouserec -->|"reconciles warehouse"| node_cn
node_fe -.->|"applies workloads"| node_resource
node_be -.->|"applies workloads"| node_resource
node_cn -.->|"applies workloads"| node_resource
node_proxy -->|"applies deployment"| node_resource
node_be -->|"builds service"| node_services
node_fe -.->|"updates status"| node_status
node_be -->|"updates status"| node_status
node_proxy -->|"updates status"| node_status
node_clusterrec -->|"persists status"| node_kube
node_warehouserec -->|"persists status"| node_kube
node_podmount -->|"mounts configured volumes"| node_clustercr
node_autoscale -.->|"manages scaling"| node_kube
node_load -->|"supports data loading"| node_kube
node_cn -->|"queries FE"| node_mysql

click node_manager "https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/cmd/main.go"
click node_clustercr "https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/apis/starrocks/v1/starrockscluster_types.go"
click node_warehousecr "https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/apis/starrocks/v1/starrockswarehouse_types.go"
click node_clusterrec "https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/controllers/starrockscluster_controller.go"
click node_warehouserec "https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/controllers/starrockswarehouse_controller.go"
click node_registration "https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/controllers/controllers.go"
click node_fe "https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/subcontrollers/fe/fe_controller.go"
click node_be "https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/subcontrollers/be/be_controller.go"
click node_cn "https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/subcontrollers/cn/cn_controller.go"
click node_proxy "https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/subcontrollers/feproxy/feproxy_controller.go"
click node_status "https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/subcontrollers/subcontroller.go"
click node_resource "https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/k8sutils/k8sutils.go"
click node_services "https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/common/resource_utils/service.go"
click node_podmount "https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/k8sutils/templates/pod/mount.go"
click node_autoscale "https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/common/resource_utils/autoscaler.go"
click node_load "https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/k8sutils/load/load.go"
click node_mysql "https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/subcontrollers/cn/cn_mysql.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_manager,node_registration toneBlue
class node_clustercr,node_warehousecr,node_kube toneAmber
class node_clusterrec,node_warehouserec toneMint
class node_fe,node_be,node_cn,node_proxy,node_status,node_resource,node_services,node_podmount toneRose
class node_autoscale,node_load,node_mysql,node_user toneIndigo
```

## Components

### Operator runtime

- [Controller manager](https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/cmd/main.go): `cmd/main.go`
- [Controller registration](https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/controllers/controllers.go): `pkg/controllers/controllers.go`

### Cluster API

- [Cluster resource](https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/apis/starrocks/v1/starrockscluster_types.go): `pkg/apis/starrocks/v1/starrockscluster_types.go`
- [Warehouse resource](https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/apis/starrocks/v1/starrockswarehouse_types.go): `pkg/apis/starrocks/v1/starrockswarehouse_types.go`

### Reconciliation

- [Cluster reconciler](https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/controllers/starrockscluster_controller.go): `pkg/controllers/starrockscluster_controller.go`
- [Warehouse reconciler](https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/controllers/starrockswarehouse_controller.go): `pkg/controllers/starrockswarehouse_controller.go`

### Workload management

- [FE controller](https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/subcontrollers/fe/fe_controller.go): `pkg/subcontrollers/fe/fe_controller.go`
- [BE controller](https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/subcontrollers/be/be_controller.go): `pkg/subcontrollers/be/be_controller.go`
- [CN controller](https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/subcontrollers/cn/cn_controller.go): `pkg/subcontrollers/cn/cn_controller.go`
- [FE proxy](https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/subcontrollers/feproxy/feproxy_controller.go): `pkg/subcontrollers/feproxy/feproxy_controller.go`
- [Workload status](https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/subcontrollers/subcontroller.go): `pkg/subcontrollers/subcontroller.go`
- [Kubernetes resources](https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/k8sutils/k8sutils.go): `pkg/k8sutils/k8sutils.go`
- [Service builder](https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/common/resource_utils/service.go): `pkg/common/resource_utils/service.go`
- [Volume mounting](https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/k8sutils/templates/pod/mount.go): `pkg/k8sutils/templates/pod/mount.go`

### Operational features

- [CN autoscaling](https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/common/resource_utils/autoscaler.go): `pkg/common/resource_utils/autoscaler.go`
- [STREAM LOAD support](https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/k8sutils/load/load.go): `pkg/k8sutils/load/load.go`
- [FE SQL access](https://github.com/starrocks/starrocks-kubernetes-operator/blob/main/pkg/subcontrollers/cn/cn_mysql.go): `pkg/subcontrollers/cn/cn_mysql.go`

### Other components

- **Cluster operator**
- **Kubernetes API**

## Connections

- Cluster operator → Kubernetes API: applies resources (evidence: `README.md`)
- Kubernetes API → Controller manager: watches resources
- Controller manager → Controller registration: sets up controllers (evidence: `cmd/main.go`)
- Controller registration → Cluster reconciler: registers (evidence: `pkg/controllers/controllers.go`)
- Controller registration → Warehouse reconciler: registers (evidence: `pkg/controllers/controllers.go`)
- Cluster reconciler → Cluster resource: reads and updates (evidence: `pkg/controllers/starrockscluster_controller.go`)
- Warehouse reconciler → Warehouse resource: reads and updates (evidence: `pkg/controllers/starrockswarehouse_controller.go`)
- Cluster reconciler → FE controller: reconciles FE (evidence: `pkg/controllers/starrockscluster_controller.go`)
- Cluster reconciler → BE controller: reconciles BE (evidence: `pkg/controllers/starrockscluster_controller.go`)
- Cluster reconciler → CN controller: reconciles CN (evidence: `pkg/controllers/starrockscluster_controller.go`)
- Cluster reconciler → FE proxy: reconciles proxy (evidence: `pkg/controllers/starrockscluster_controller.go`)
- Warehouse reconciler → CN controller: reconciles warehouse (evidence: `pkg/controllers/starrockswarehouse_controller.go`)
- FE controller → Kubernetes resources: applies workloads
- BE controller → Kubernetes resources: applies workloads
- CN controller → Kubernetes resources: applies workloads
- FE proxy → Kubernetes resources: applies deployment (evidence: `pkg/subcontrollers/feproxy/feproxy_controller.go`)
- BE controller → Service builder: builds service (evidence: `pkg/subcontrollers/be/be_controller.go`)
- FE controller → Workload status: updates status
- BE controller → Workload status: updates status (evidence: `pkg/subcontrollers/be/be_controller.go`)
- FE proxy → Workload status: updates status (evidence: `pkg/subcontrollers/feproxy/feproxy_controller.go`)
- Cluster reconciler → Kubernetes API: persists status (evidence: `pkg/controllers/starrockscluster_controller.go`)
- Warehouse reconciler → Kubernetes API: persists status (evidence: `pkg/controllers/starrockswarehouse_controller.go`)
- Volume mounting → Cluster resource: mounts configured volumes (evidence: `README.md`)
- CN autoscaling → Kubernetes API: manages scaling
- STREAM LOAD support → Kubernetes API: supports data loading (evidence: `README.md`)
- CN controller → FE SQL access: queries FE (evidence: `pkg/subcontrollers/cn/cn_controller.go`)
