# siderolabs/omni architecture

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

- Interactive diagram: https://gitdiagram.com/siderolabs/omni
- Repository: https://github.com/siderolabs/omni

## Overview

##### Project type and purpose
- Omni is a full-stack Kubernetes management platform for bare-metal/VM/cloud (SaaS-style), with a web UI, a Go-based backend (gRPC + HTTP gateway + controllers), a Go client SDK, and a CLI (omnictl).
- The README describes SaaS-simple deployment of Kubernetes on your own hardware, an elegant UI, built‐in HA API, OIDC integration, and CSI/GPU support.

##### File structure
- Top-level directories:
- cmd/omni & cmd/omnictl: entry points for the server and CLI
- internal/backend: core server logic—gRPC setup, discovery, OIDC, controllers, resource reconcilers
- internal/frontend: static assets embedding and HTTP handlers for the UI
- client/: Go client library with protobuf definitions and HTTP/gRPC stubs
- frontend/: Vue.js SPA with API clients (protobuf + fetch), components, views, state management, routing, and E2E tests
- deploy/: Docker Compose, Helm charts, env templates
- Configuration/build scripts: Dockerfile, Makefile, hack/, GitHub workflows for CI, tests, releases
- Persistence/config: internal/backend/runtime/state with boltdb/etcd, OIDC storage adapters, certs under hack/, config under internal/pkg/config

##### README for additional insights
- Mentions Talos Linux integration, enterprise IDP (OIDC), and external storage (S3 for etcd backups)

##### Essential details
- Both synchronous (API calls) and asynchronous (controller loops) interactions.
- Technology labels on edges (e.g., “gRPC”, “HTTP/JSON”, “etcd client”).

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "UI Layer"
    Browser["Browser"]:::frontend
    VueSPA["Vue SPA"]:::frontend
  end
  Browser -->|HTTP/JSON| VueSPA

  subgraph "Client Layer"
    CLI["omnictl CLI"]:::frontend
    SDKPkg["Go Client SDK (pkg)"]:::frontend
    SDKApi["Go Client SDK (api)"]:::frontend
  end
  CLI -->|gRPC/HTTP| GRPC
  SDKPkg -->|gRPC/HTTP| GRPC
  SDKApi -->|gRPC/HTTP| GRPC

  subgraph "API Layer"
    GRPC["gRPC API Server"]:::transport
    HTTPServer["HTTP REST Gateway"]:::transport
  end
  VueSPA -->|HTTP| HTTPServer
  HTTPServer -->|gRPC| GRPC

  subgraph "Authentication Layer"
    OIDCHandler["OIDC Handlers"]:::logic
    AuthPkg["Auth Package"]:::logic
  end
  GRPC -->|OIDC flows| OIDCHandler
  OIDCHandler -->|token/claims| AuthPkg
  AuthPkg -->|OIDC| ExternalIDP

  subgraph "Controller Layer"
    CoreCtrl["Core Controllers"]:::logic
    DiscoveryCtrl["Discovery Controller"]:::logic
    ProvisionCtrl["Machine Provision Ctrl"]:::logic
    ImageFactory["Image Factory"]:::logic
    PowerStage["Power Stage"]:::logic
    EtcdBackupCtrl["Etcd Backup Controller"]:::logic
    WorkloadProxy["Workload Proxy"]:::logic
  end
  GRPC --> CoreCtrl
  CoreCtrl --> DiscoveryCtrl
  CoreCtrl --> ProvisionCtrl
  CoreCtrl --> ImageFactory
  CoreCtrl --> PowerStage
  CoreCtrl --> EtcdBackupCtrl
  CoreCtrl --> WorkloadProxy

  subgraph "Persistence Layer"
    StateEtcd["etcd State Store"]:::persistence
    StateBolt["BoltDB State Store"]:::persistence
  end
  CoreCtrl -->|etcd client| StateEtcd
  CoreCtrl -->|boltdb| StateBolt

  subgraph "Integration Services"
    ExternalIDP["External OIDC Provider"]:::external
    S3Service["S3 Backup Service (S3)"]:::external
    DockerRegistry["Docker Registry"]:::external
  end
  EtcdBackupCtrl -->|backup data| S3Service
  CoreCtrl -->|pull images| DockerRegistry
  OIDCHandler -->|auth requests| ExternalIDP

  subgraph "Runtime Layer"
    K8sProxy["Kubernetes API Proxy"]:::runtime
    RuntimeK8s["Target Clusters API"]:::runtime
    TalosClient["Talos Runtime Client"]:::runtime
  end
  CoreCtrl -->|API calls| K8sProxy
  K8sProxy --> RuntimeK8s
  RuntimeK8s --> TalosClient

  click VueSPA "https://github.com/siderolabs/omni/tree/main/frontend/src"
  click CLI "https://github.com/siderolabs/omni/tree/main/cmd/omnictl"
  click SDKPkg "https://github.com/siderolabs/omni/tree/main/client/pkg"
  click SDKApi "https://github.com/siderolabs/omni/tree/main/client/api"
  click GRPC "https://github.com/siderolabs/omni/tree/main/internal/backend/grpc"
  click HTTPServer "https://github.com/siderolabs/omni/blob/main/internal/backend/services/http_server.go"
  click OIDCHandler "https://github.com/siderolabs/omni/tree/main/internal/backend/oidc"
  click AuthPkg "https://github.com/siderolabs/omni/tree/main/internal/pkg/auth"
  click DiscoveryCtrl "https://github.com/siderolabs/omni/tree/main/internal/backend/discovery"
  click ProvisionCtrl "https://github.com/siderolabs/omni/blob/main/internal/backend/runtime/omni/controllers/omni/machine_provision.go"
  click ImageFactory "https://github.com/siderolabs/omni/tree/main/internal/backend/imagefactory"
  click PowerStage "https://github.com/siderolabs/omni/blob/main/internal/backend/powerstage/watcher.go"
  click EtcdBackupCtrl "https://github.com/siderolabs/omni/blob/main/internal/backend/runtime/omni/controllers/omni/etcd_backup.go"
  click S3Service "https://github.com/siderolabs/omni/blob/main/internal/backend/runtime/omni/controllers/omni/etcdbackup/store/s3store.go"
  click Filestore "https://github.com/siderolabs/omni/blob/main/internal/backend/runtime/omni/controllers/omni/etcdbackup/store/filestore.go"
  click WorkloadProxy "https://github.com/siderolabs/omni/tree/main/internal/backend/services/workloadproxy"
  click StateEtcd "https://github.com/siderolabs/omni/blob/main/internal/backend/runtime/omni/state_etcd.go"
  click StateBolt "https://github.com/siderolabs/omni/blob/main/internal/backend/runtime/omni/state_boltdb.go"
  click K8sProxy "https://github.com/siderolabs/omni/tree/main/internal/backend/k8sproxy"
  click TalosClient "https://github.com/siderolabs/omni/tree/main/internal/backend/runtime/talos"

  classDef frontend fill:#cce5ff,stroke:#339,stroke-width:1px;
  classDef transport fill:#d4edda,stroke:#3a3,stroke-width:1px;
  classDef logic fill:#fff3cd,stroke:#d99f18,stroke-width:1px;
  classDef persistence fill:#E2E3E5,stroke:#6c757d,stroke-width:1px;
  classDef external fill:#f8d7da,stroke:#842029,stroke-width:1px;
  classDef runtime fill:#e5e0ff,stroke:#5a35a5,stroke-width:1px;
```
