# kubeovn/kube-ovn architecture

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

- Interactive diagram: https://gitdiagram.com/kubeovn/kube-ovn
- Repository: https://github.com/kubeovn/kube-ovn

## Overview

##### Main System Components
- Controller & CRD Management:
– Represent the central Kube-OVN controller (found in cmd/controller and pkg/controller). This component watches changes to K8s Custom Resources (CRDs under pkg/apis/kubeovn) and adjusts network configuration accordingly.
- CNI Plugin/Node Agent:
– Show the CNI components (located under cmd/cni and pkg/daemon), which run on worker nodes, handle pod network setups, manage IPAM, update network namespaces, and interact with OVN/OVS.
- OVN Integration and Datapath Management:
- Webhook and External Interfaces:
– Include the webhook service (cmd/webhook and pkg/webhook) that helps manage admission control and network policies.
- Monitoring and Troubleshooting:
– Note the support for Prometheus and Grafana (as described in the README and found in the “dist/monitoring” directory). This part of the system exports metrics for network quality, connectivity, and performance.
- Deployment & Installation:
– Incorporate the Helm chart components (in the charts/kube-ovn directory), which are used to deploy these various components on a Kubernetes cluster.

##### Relationships and Data Flows
- Controller to the node-level daemons (the CNI server, gateway/speaker, and OVN monitoring components) to demonstrate that it orchestrates network state changes across the cluster.
- Interactions between the various node-level components (CNI plugin, daemon processes, and OVN agents) indicating that they work collectively to establish connections, manage IPAM allocations, and update OVS flows.
- If desired, include external components (like a BGP router, physical underlay network, or cloud provider resources) to capture integration points that support external connectivity.

##### Architectural Patterns and Technologies
- Modular Microservices: Each executable (controller, daemon, cni, webhook, pinger, etc.) is deployed independently, allowing scalability and fault isolation.
- Client-Server and Reconciliation Pattern: The controller watches CRDs using informers (client/informers) and triggers reconciliation loops to enforce the desired network state.
- Distributed and Scalable Design: Emphasize that key functions (like ovn scheduler, gateway functions, and monitoring) are distributed across all nodes—this avoids a single point of failure.
- Infrastructure as Code: The existence of Helm charts and extensive configuration files points to an architecture that is deployed and configured in a declarative fashion.
- Cross-Platform Support: Note the distinctions in the source code for Linux and Windows (files with “_windows.go”), which underline the support for mixed OS clusters, as well as ARM and x86 images in the “dist/images” directory.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Kubernetes API Server"]:::external
    subgraph "Kubernetes Cluster"
        subgraph "Control Plane"
            K["Kube-OVN Controller"]:::controlPlane
            W["Webhook Service"]:::controlPlane
        end
        subgraph "Node-Level Services"
            C["CNI Plugin/Node Agent"]:::nodeAgent
            subgraph "OVN Integration"
                OI["OVN IC Controller"]:::ovnComp
                LC["Leader Checker"]:::ovnComp
                S["Speaker"]:::ovnComp
                P["Pinger"]:::ovnComp
                OVU["OVN/OVS Utilities"]:::ovnComp
            end
        end
    end
    M["Monitoring (Prometheus/Grafana)"]:::monitoring
    H["Helm Deployment"]:::external

    %% Data and Control Flows
    A -->|"CRD-events"| K
    K -->|"config-changes"| C
    K -->|"admission"| W
    C -->|"network-config"| OI
    C -->|"state-sync"| LC
    C -->|"state-sync"| S
    C -->|"state-sync"| P
    C -->|"flows-update"| OVU
    M -->|"feedback"| K
    H -->|"deploys"| K
    H -->|"deploys"| C
    H -->|"deploys"| W

    %% Click Events for Component Mapping
    click K "https://github.com/kubeovn/kube-ovn/tree/master/cmd/controller"
    click K "https://github.com/kubeovn/kube-ovn/tree/master/pkg/controller"
    click K "https://github.com/kubeovn/kube-ovn/tree/master/pkg/apis/kubeovn"
    
    click C "https://github.com/kubeovn/kube-ovn/tree/master/cmd/cni"
    click C "https://github.com/kubeovn/kube-ovn/tree/master/pkg/daemon"
    
    click OI "https://github.com/kubeovn/kube-ovn/tree/master/cmd/ovn_ic_controller"
    click OI "https://github.com/kubeovn/kube-ovn/tree/master/pkg/ovn_ic_controller"
    
    click LC "https://github.com/kubeovn/kube-ovn/tree/master/cmd/ovn_leader_checker"
    
    click S "https://github.com/kubeovn/kube-ovn/tree/master/cmd/speaker"
    click S "https://github.com/kubeovn/kube-ovn/tree/master/pkg/speaker"
    
    click P "https://github.com/kubeovn/kube-ovn/tree/master/cmd/pinger"
    click P "https://github.com/kubeovn/kube-ovn/tree/master/pkg/pinger"
    
    click OVU "https://github.com/kubeovn/kube-ovn/tree/master/pkg/ovs"
    click OVU "https://github.com/kubeovn/kube-ovn/tree/master/pkg/ovsdb"
    
    click W "https://github.com/kubeovn/kube-ovn/tree/master/cmd/webhook"
    click W "https://github.com/kubeovn/kube-ovn/tree/master/pkg/webhook"
    
    click M "https://github.com/kubeovn/kube-ovn/tree/master/dist/monitoring"
    
    click H "https://github.com/kubeovn/kube-ovn/tree/master/charts/kube-ovn"

    %% Styles
    classDef controlPlane fill:#f9c,stroke:#333,stroke-width:2px;
    classDef nodeAgent fill:#ccf,stroke:#333,stroke-width:2px;
    classDef ovnComp fill:#cfc,stroke:#333,stroke-width:2px;
    classDef external fill:#fcf,stroke:#333,stroke-width:2px;
    classDef monitoring fill:#ffc,stroke:#333,stroke-width:2px;
```
