# togethercomputer/cluster-api-provider-kubevirt architecture

> Architecture diagram of the GitHub repository togethercomputer/cluster-api-provider-kubevirt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/togethercomputer/cluster-api-provider-kubevirt
- Repository: https://github.com/togethercomputer/cluster-api-provider-kubevirt

## Overview

##### Main Components

a. Core Components:
- Cluster API Controller Manager
- KubeVirt Infrastructure Provider
- Webhook Server
- Custom Resource Definitions (CRDs)
- clusterkubevirtadm CLI tool

b. Custom Resources:
- KubeVirtCluster
- KubeVirtMachine
- KubeVirtClusterTemplate
- KubeVirtMachineTemplate

##### Key Relationships to Highlight

- Control flow from CLI/API to controllers
- Controller interaction with KubeVirt
- Webhook validation flow
- Resource relationship between Clusters and Machines

##### Specific Implementation Details

Key packages as components:
**controllers/**
- KubeVirtCluster Controller
- KubeVirtMachine Controller

**pkg/**
- infracluster/
- kubevirt/
- loadbalancer/
- ssh/
- webhookhandler/
- workloadcluster/

##### Important Elements

a. Control Flow:
- How the controllers reconcile the custom resources
- Webhook validation points
- Infrastructure provisioning flow

b. Resource Management:
- Relationship between templates and instances
- Where load balancing occurs
- SSH key management flow

Create distinct sections for:

##### Documentation Integration

Reference key documentation locations:
- API definitions (/api/v1alpha1)
- Configuration templates (/templates)
- E2E test coverage

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "User Interface Layer"
        CLI["clusterkubevirtadm CLI"]:::cli
        K8sAPI["Kubernetes API"]:::api
    end

    subgraph "Control Plane Layer"
        CAPICTL["Cluster API Controller Manager"]:::controller
        WEBHOOK["Webhook Server"]:::security
        KVCTL["KubeVirt Infrastructure Provider"]:::controller
        
        subgraph "Controllers"
            KVCLUSTERCTL["KubeVirtCluster Controller"]:::controller
            KVMACHINECTL["KubeVirtMachine Controller"]:::controller
        end
    end

    subgraph "Resource Layer"
        subgraph "Custom Resource Definitions"
            KVCLUSTERCRD["KubeVirtCluster CRD"]:::crd
            KVMACHINECRD["KubeVirtMachine CRD"]:::crd
            KVCLUSTERTEMPCRD["KubeVirtClusterTemplate CRD"]:::crd
            KVMACHINETEMPCRD["KubeVirtMachineTemplate CRD"]:::crd
        end
        
        subgraph "Resource Types"
            KVCLUSTER["KubeVirtCluster"]:::resource
            KVMACHINE["KubeVirtMachine"]:::resource
            KVCLUSTERTEMP["KubeVirtClusterTemplate"]:::resource
            KVMACHINETEMP["KubeVirtMachineTemplate"]:::resource
        end
    end

    subgraph "Infrastructure Layer"
        INFRACLUSTER["Infrastructure Cluster"]:::infra
        KVMACHINE_MGMT["KubeVirt Machine Management"]:::infra
        LB["Load Balancer"]:::infra
        SSH["SSH Management"]:::security
        WORKLOAD["Workload Cluster"]:::infra
    end

    %% Relationships
    CLI --> K8sAPI
    K8sAPI --> WEBHOOK
    WEBHOOK --> CAPICTL
    CAPICTL --> KVCTL
    KVCTL --> KVCLUSTERCTL
    KVCTL --> KVMACHINECTL
    
    KVCLUSTERCTL --> KVCLUSTER
    KVMACHINECTL --> KVMACHINE
    
    KVCLUSTER --> INFRACLUSTER
    KVMACHINE --> KVMACHINE_MGMT
    INFRACLUSTER --> LB
    INFRACLUSTER --> SSH
    KVMACHINE_MGMT --> WORKLOAD

    %% Click Events
    click CLI "https://github.com/togethercomputer/cluster-api-provider-kubevirt/blob/main/clusterkubevirtadm/main.go"
    click WEBHOOK "https://github.com/togethercomputer/cluster-api-provider-kubevirt/blob/main/pkg/webhookhandler/validator.go"
    click KVCLUSTERCTL "https://github.com/togethercomputer/cluster-api-provider-kubevirt/blob/main/controllers/kubevirtcluster_controller.go"
    click KVMACHINECTL "https://github.com/togethercomputer/cluster-api-provider-kubevirt/blob/main/controllers/kubevirtmachine_controller.go"
    click KVCLUSTERCRD "https://github.com/togethercomputer/cluster-api-provider-kubevirt/blob/main/config/crd/bases/infrastructure.cluster.x-k8s.io_kubevirtclusters.yaml"
    click KVMACHINECRD "https://github.com/togethercomputer/cluster-api-provider-kubevirt/blob/main/config/crd/bases/infrastructure.cluster.x-k8s.io_kubevirtmachines.yaml"
    click KVCLUSTERTEMPCRD "https://github.com/togethercomputer/cluster-api-provider-kubevirt/blob/main/config/crd/bases/infrastructure.cluster.x-k8s.io_kubevirtclustertemplates.yaml"
    click KVMACHINETEMPCRD "https://github.com/togethercomputer/cluster-api-provider-kubevirt/blob/main/config/crd/bases/infrastructure.cluster.x-k8s.io_kubevirtmachinetemplates.yaml"
    click KVCLUSTER "https://github.com/togethercomputer/cluster-api-provider-kubevirt/blob/main/api/v1alpha1/kubevirtcluster_types.go"
    click KVMACHINE "https://github.com/togethercomputer/cluster-api-provider-kubevirt/blob/main/api/v1alpha1/kubevirtmachine_types.go"
    click KVCLUSTERTEMP "https://github.com/togethercomputer/cluster-api-provider-kubevirt/blob/main/api/v1alpha1/kubevirtclustertemplate_types.go"
    click KVMACHINETEMP "https://github.com/togethercomputer/cluster-api-provider-kubevirt/blob/main/api/v1alpha1/kubevirtmachinetemplate_types.go"
    click INFRACLUSTER "https://github.com/togethercomputer/cluster-api-provider-kubevirt/blob/main/pkg/infracluster/infracluster.go"
    click KVMACHINE_MGMT "https://github.com/togethercomputer/cluster-api-provider-kubevirt/blob/main/pkg/kubevirt/machine.go"
    click LB "https://github.com/togethercomputer/cluster-api-provider-kubevirt/blob/main/pkg/loadbalancer/loadbalancer.go"
    click SSH "https://github.com/togethercomputer/cluster-api-provider-kubevirt/blob/main/pkg/ssh/cluster_node_ssh_keys.go"
    click WORKLOAD "https://github.com/togethercomputer/cluster-api-provider-kubevirt/blob/main/pkg/workloadcluster/workloadcluster.go"

    %% Styling
    classDef controller fill:#90EE90,stroke:#333,stroke-width:2px
    classDef security fill:#DDA0DD,stroke:#333,stroke-width:2px
    classDef api fill:#87CEEB,stroke:#333,stroke-width:2px
    classDef cli fill:#FFB6C1,stroke:#333,stroke-width:2px
    classDef crd fill:#98FB98,stroke:#333,stroke-width:2px
    classDef resource fill:#87CEFA,stroke:#333,stroke-width:2px
    classDef infra fill:#FFA07A,stroke:#333,stroke-width:2px
```
