# kusionstack/controller-mesh architecture

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

- Interactive diagram: https://gitdiagram.com/kusionstack/controller-mesh
- Repository: https://github.com/kusionstack/controller-mesh

## Overview

##### Project Type and Purpose
- This is an open-source Kubernetes extension tool (“Controller Mesh”) that sits alongside existing controller/operator deployments to provide sharding, canary upgrades, circuit breaking, rate limiting, and fault injection features.
- It consists of two main binaries (ctrlmesh-manager and ctrlmesh-proxy), a set of CRDs, admission webhooks, and integration with the Kubernetes API server.

##### File Structure
- Top-level dirs:
- pkg/cmd/{manager,proxy,cert-generator} – entrypoints for the controller manager, proxy sidecar, and certificate generation tool.
- pkg/manager/controllers – Kubernetes controller logic for CRDs (ShardingConfig, CircuitBreaker, FaultInjection, ManagerState, etc.).
- pkg/proxy – sidecar proxy code handling HTTP/gRPC, caching, lease management, injection logic, and leader election.
- pkg/webhook – mutating/validating admission webhook implementations (namespace, pod, resources, shardingconfig).
- config – Kubernetes YAMLs (CRD definitions, RBAC, webhooks, manager Deployment, Service).
- artifacts, e2e – Dockerfiles, scripts for building images and end-to-end testing.
- Patterns:
- Controller-Manager pattern (built on controller-runtime)
- Sidecar proxy pattern (injected into operator Pods)
- Admission Webhook pattern
- CustomResource definitions for rule configuration

##### README for Additional Insights
- Key components: ctrlmesh-proxy (injected into each operator Pod to intercept requests), ctrlmesh-manager (central dispatcher of sharding & routing rules).
- Proxy uses iptables NAT or fake kubeconfig to intercept Apiserver traffic.
- ShardingConfig CRD holds all routing and limit rules.
- Manager applies labels and pushes config to proxies; proxies enforce flow control on HTTP/gRPC.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Kubernetes Cluster"
        direction TB
        CU["External Clients (kubectl)"]:::external
        API["K8s API Server"]:::api
        ETCD["etcd"]:::storage
        CU -->|"apply CRDs"| API
        API -->|"store state"| ETCD
    end

    subgraph "ctrlmesh-manager (Controller Manager)"
        direction TB
        MGR["ctrlmesh-manager"]:::controller
        subgraph "Controllers"
            CB["CircuitBreaker Controller"]:::controller
            FI["FaultInjection Controller"]:::controller
            MS["ManagerState Controller"]:::controller
            RO["Rollout Controller"]:::controller
            PR["PatchRunnable Controller"]:::controller
            SC["ShardingConfigServer Controller"]:::controller
        end
        MGR -->|watches CRDs| CB
        MGR --> FI
        MGR --> MS
        MGR --> RO
        MGR --> PR
        MGR --> SC
        MGR -->|"push config"| Proxy
    end

    subgraph "Operator Pod"
        direction TB
        OP["Application Controller"]:::controller
        Proxy["ctrlmesh-proxy sidecar"]:::proxy
        OP -->|calls API| Proxy
        Proxy -->|intercept via iptables/fake kubeconfig| API
        Proxy -->|cache refresh| MGR
        Proxy -->|enforce rules| OP
    end

    subgraph "Admission Webhooks"
        direction TB
        WS["Webhook Server"]:::api
        NS["Namespace Webhook"]:::controller
        PD["Pod Webhook"]:::controller
        RS["Resources Webhook"]:::controller
        SCW["ShardingConfig Webhook"]:::controller
        API -->|mutate/validate| WS
        WS --> NS
        WS --> PD
        WS --> RS
        WS --> SCW
    end

    subgraph "CRD Definitions"
        direction TB
        CR1["ShardingConfig CRD"]:::crd
        CR2["CircuitBreaker CRD"]:::crd
        CR3["FaultInjection CRD"]:::crd
        CR4["ManagerState CRD"]:::crd
    end

    subgraph "Proxy Core Modules"
        direction TB
        PC1["apiserver"]:::proxy
        PC2["cache"]:::proxy
        PC3["circuitbreaker"]:::proxy
        PC4["faultinjection"]:::proxy
        PC5["filters"]:::proxy
        PC6["grpcserver"]:::proxy
        PC7["http"]:::proxy
        PC8["leaderelection"]:::proxy
        PC9["proto"]:::proxy
    end

    subgraph "Utilities"
        direction TB
        CG["cert-generator"]:::controller
    end

    %% Click Events
    click MGR "https://github.com/kusionstack/controller-mesh/blob/main/pkg/cmd/manager/main.go"
    click CB "https://github.com/kusionstack/controller-mesh/tree/main/pkg/manager/controllers/circuitbreaker"
    click FI "https://github.com/kusionstack/controller-mesh/tree/main/pkg/manager/controllers/faultinjection"
    click MS "https://github.com/kusionstack/controller-mesh/tree/main/pkg/manager/controllers/managerstate"
    click RO "https://github.com/kusionstack/controller-mesh/tree/main/pkg/manager/controllers/rollout"
    click PR "https://github.com/kusionstack/controller-mesh/tree/main/pkg/manager/controllers/patchrunnable"
    click SC "https://github.com/kusionstack/controller-mesh/tree/main/pkg/manager/controllers/shardingconfigserver"
    click Proxy "https://github.com/kusionstack/controller-mesh/blob/main/pkg/cmd/proxy/main.go"
    click NS "https://github.com/kusionstack/controller-mesh/tree/main/pkg/webhook/ns"
    click PD "https://github.com/kusionstack/controller-mesh/tree/main/pkg/webhook/pod"
    click RS "https://github.com/kusionstack/controller-mesh/tree/main/pkg/webhook/resources"
    click SCW "https://github.com/kusionstack/controller-mesh/tree/main/pkg/webhook/shardingconfig"
    click WS "https://github.com/kusionstack/controller-mesh/blob/main/pkg/webhook/server.go"
    click CR1 "https://github.com/kusionstack/controller-mesh/blob/main/config/crd/bases/ctrlmesh.kusionstack.io_shardingconfigs.yaml"
    click CR2 "https://github.com/kusionstack/controller-mesh/blob/main/config/crd/bases/ctrlmesh.kusionstack.io_circuitbreakers.yaml"
    click CR3 "https://github.com/kusionstack/controller-mesh/blob/main/config/crd/bases/ctrlmesh.kusionstack.io_faultinjections.yaml"
    click CR4 "https://github.com/kusionstack/controller-mesh/blob/main/config/crd/bases/ctrlmesh.kusionstack.io_managerstates.yaml"
    click PC1 "https://github.com/kusionstack/controller-mesh/tree/main/pkg/proxy/apiserver"
    click PC2 "https://github.com/kusionstack/controller-mesh/tree/main/pkg/proxy/cache"
    click PC3 "https://github.com/kusionstack/controller-mesh/tree/main/pkg/proxy/circuitbreaker"
    click PC4 "https://github.com/kusionstack/controller-mesh/tree/main/pkg/proxy/faultinjection"
    click PC5 "https://github.com/kusionstack/controller-mesh/tree/main/pkg/proxy/filters"
    click PC6 "https://github.com/kusionstack/controller-mesh/tree/main/pkg/proxy/grpcserver"
    click PC7 "https://github.com/kusionstack/controller-mesh/tree/main/pkg/proxy/http"
    click PC8 "https://github.com/kusionstack/controller-mesh/tree/main/pkg/proxy/leaderelection"
    click PC9 "https://github.com/kusionstack/controller-mesh/tree/main/pkg/proxy/proto"
    click CG "https://github.com/kusionstack/controller-mesh/blob/main/pkg/cmd/cert-generator/main.go"

    classDef controller fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef proxy fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef api fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef crd fill:#F0E68C,stroke:#333,stroke-width:1px;
    classDef storage fill:#D3D3D3,stroke:#333,stroke-width:1px;
    classDef external fill:#FFFFFF,stroke:#333,stroke-width:1px;
```
