# loft-sh/kiosk architecture

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

- Interactive diagram: https://gitdiagram.com/loft-sh/kiosk
- Repository: https://github.com/loft-sh/kiosk

## Overview

##### Project Type & Purpose
- kiosk is a Kubernetes multi-tenancy extension that adds support for “Accounts”, “Spaces” (which map 1:1 to Namespaces), and additional custom resources (e.g., AccountQuota, Template, TemplateInstance). It extends the Kubernetes API through CRDs and an API server extension to support customized resource views and dynamic access control.
- The project is written in Go (observe directories like cmd/kiosk and pkg/*) and is packaged with a Helm chart (see the chart/ directory) so that it can be easily deployed into a Kubernetes cluster.
- The README makes it clear that the primary purpose is to allow cluster admins to provision multi-tenant clusters, self-service namespace provisioning for tenant users, and application of security templates to initialize namespaced environments.

##### File Structure
- High-level directories such as:
- cmd/ → Contains the main binary (in cmd/kiosk) which is the entry point for the kiosk controller.
- pkg/ → Contains the core logic for API server extensions, admission controllers, client libraries, RBAC and quota management, CRD definitions, template management, and utilities.
- kube/ → Contains Kubernetes-specific implementations, including custom API registrations, controllers, quota evaluators, and plugins that interface with the Kubernetes infrastructure.
- chart/ → Contains the Helm chart used for deploying the kiosk solution (includes Chart.yaml, templates for deployment, ServiceAccount, RoleBindings, etc.).
- examples/ → Provides sample CRs and YAML files which show how to configure Accounts, Spaces, Templates, and Quotas.
- Additional directories (e.g., docs, hack, gen) support documentation, boilerplate code generation, and development scripts.

##### Architectural Insights from the README
- Components include CRDs under the group config.kiosk.sh and the API extension under tenancy.kiosk.sh. The design emphasizes how kiosk translates Kubernetes namespaces into “Spaces” and enhances RBAC.

a. Main Components to Include:
- Kubernetes Cluster: Represents the cluster with its standard components (pods, etcd, API server).
- kiosk Controller/Operator: The main application running (referenced in cmd/kiosk) that interacts with Kubernetes to manage CRDs.
- API Server Extension: Under the tenancy.kiosk.sh API group, which provides a dynamically filtered view (for Spaces and tenancy resources).
- Helm Chart Deployment: Represent the deployment process that instantiates the kiosk operator in the cluster.
- External Actors: Represent Cluster Admins (with full privileges) and Account Users (with restricted access), showing how they interact with the kiosk API/CRDs.
- RBAC Components: Illustrate the role bindings (e.g., kiosk-edit, kiosk-space-admin) that allow or filter user actions.

b. Relationships and Interactions:
- How Cluster Admins configure kiosk through CRs (create/update Account, Template, Quota definitions) and how Account Users then use those settings to create Spaces.

c. Key Architectural Patterns & Design Principles:
- Extension via CRDs and API Server Extension: Emphasize how kiosk leverages Kubernetes custom resources to add multi-tenancy.
- Pluggable & Self-service Model: The separation of roles (Cluster Admin vs. Account User) and the ability to define self-service namespace provisioning.
- Modular Design: The separation between various modules such as quota management, templating engine (supporting both raw manifests and Helm charts), and admission controllers.

d. Relevant Technologies / Frameworks:
- Go programming language (core business logic).
- Helm (for deployment and templating).
- Kubernetes (as the target environment with CRDs, Namespaces, RBAC).
- API Server extensions and admission controllers for dynamic permission evaluation.

##### Elements
- Each component should be clearly labeled, for example:
- “Kubernetes API Server” (backbone).
- “kiosk Controller/Operator” (processing custom resource events).
- “Account (CRD)” and “Space (CRD/Namespace)” components.
- “API Extension: tenancy.kiosk.sh” for dynamic filtered views.
- “Helm Chart Installer” as part of the deployment process.
- Infrastructure components (Kubernetes cluster, etcd, API server)
- Application components (kiosk controller, API Extension)
- External agents (Cluster Admin, Account User)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraph: External Actors
    subgraph "External Actors"
        CA("Cluster Admin"):::external
        AU("Account User"):::external
    end

    %% Subgraph: Deployment & Configuration
    subgraph "Deployment & Configuration"
        HCI("Helm Chart Installer"):::deployment
        RBAC("RBAC Configuration"):::deployment
    end

    %% Subgraph: Kubernetes Cluster
    subgraph "Kubernetes Cluster"
        API("Kubernetes API Server"):::infra
        ETCD("etcd"):::infra
    end

    %% Subgraph: kiosk Core Components
    subgraph "kiosk Core Components"
        OPC("Operator: Main"):::core
        OPCtrl("Operator: Controllers"):::core
        APIExt("API Server Extension"):::core
        AC("Admission Controllers (Quota)"):::core
    end

    %% Subgraph: Custom Resources
    subgraph "Custom Resources"
        CRD("CRDs: Account, AccountQuota, Template, TemplateInstance"):::crd
        Space("CRD: Space"):::crd
    end

    %% Deployment relationships
    HCI -->|deploys| OPC
    HCI -->|deploys| OPCtrl
    HCI -->|deploys| APIExt
    HCI -->|deploys| RBAC

    %% External Actor interactions
    CA -->|"configures"| CRD
    CA -->|"manages"| RBAC
    AU -->|"creates"| Space

    %% kiosk operator interactions
    OPC -->|"watches/updates"| CRD
    OPCtrl -->|"watches/updates"| CRD
    OPC -->|"creates Namespace"| API
    OPCtrl -->|"creates Namespace"| API

    %% API Extension interactions
    APIExt -->|"aggregates views"| API

    %% Admission Controllers interactions
    AC -->|"evaluates quotas"| API

    %% Kubernetes internal interactions
    API -->|"stores data"| ETCD

    %% Click Events
    click OPC "https://github.com/loft-sh/kiosk/blob/master/cmd/kiosk/main.go"
    click OPCtrl "https://github.com/loft-sh/kiosk/tree/master/pkg/manager/controllers/"
    click APIExt "https://github.com/loft-sh/kiosk/tree/master/pkg/apiserver/"
    click CRD "https://github.com/loft-sh/kiosk/tree/master/pkg/apis/config/v1alpha1/"
    click Space "https://github.com/loft-sh/kiosk/blob/master/pkg/apis/tenancy/v1alpha1/space_types.go"
    click HCI "https://github.com/loft-sh/kiosk/tree/master/chart/"
    click RBAC "https://github.com/loft-sh/kiosk/tree/master/chart/templates/rbac/"
    click AC "https://github.com/loft-sh/kiosk/tree/master/kube/plugin/pkg/admission/resourcequota/"

    %% Styles 
    classDef external fill:#f6d6ad,stroke:#e78a00,stroke-width:2px;
    classDef deployment fill:#ffefba,stroke:#f39c12,stroke-width:2px;
    classDef infra fill:#d0e6f8,stroke:#3498db,stroke-width:2px;
    classDef core fill:#d5f5e3,stroke:#28b463,stroke-width:2px;
    classDef crd fill:#f9e79f,stroke:#f1c40f,stroke-width:2px;
```
