# monimesl/istio-virtualservice-merger architecture

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

- Interactive diagram: https://gitdiagram.com/monimesl/istio-virtualservice-merger
- Repository: https://github.com/monimesl/istio-virtualservice-merger

## Overview

##### Project Type and Purpose
- This is a single binary Kubernetes Operator written in Go.
- Purpose: watch custom resources (`VirtualServiceMerge` CRDs), merge their patches into existing Istio `VirtualService` resources, and update the target VirtualService in the cluster.
- It uses the controller-runtime (Kubebuilder style) reconciliation loop.

##### File Structure
Top-level files & directories:
- main.go – entry point, sets up manager & controllers
- api/… – Go types for the CRD (group: istiomerger.monime.sl, version: v1alpha1), `VirtualServiceMergeSpec` & status types, deep-copy boilerplate.
- controller/… – Controller implementation: watches CRs, reconciler logic, tests.
- manifest/… – YAML for CRD (`crd.yaml`) and Operator Deployment (`operator.yaml`).
- hack/… – license boilerplate.
- tests/… – unit tests and test data, mocks for k8s and Istio client interfaces.
- Dockerfile, Makefile, GitHub Actions workflow for build & push.

##### Extract Architectural Insights from README
- Single operator process deployed in-cluster.
- Installs a CRD, then listens for `VirtualServiceMerge` objects.
- On each reconcile: fetch target VirtualService, apply patch(s), update resource.
- Uses controller-runtime manager for leader election, caching, and event handling.

##### Main Components & Relationships
a. Kubernetes Cluster
– API Server & etcd storing built-in and custom resources.
– Istio Control Plane (already deployed separately) which reverberates VirtualService CRDs.
b. Custom Resource Definition (CRD)
– Defines `VirtualServiceMerge` kind.
c. Operator Deployment/Pod
– Container running the compiled Go binary.
– Contains:
- Manager (controller-runtime)
- `VirtualServiceMerge` Controller
- Reconciler Loop
d. Go Modules & Code
– `api/v1alpha1`: CRD types
– `controller/`: reconciliation logic & tests
– `main.go`: wire up the manager, register scheme, start controllers
e. External Clients & Tools
– `kubectl` (end user) to apply CRD, operator manifest, and create `VirtualServiceMerge` objects.
– Istio’s CRDs (`VirtualService`) which the operator merges into.

Interaction Flow:
1. User applies CRD YAML → Kubernetes API server stores CRD.
2. User deploys operator manifest → StatefulSet/Deployment Pod is scheduled.
3. Operator’s manager connects to API server, registers watches on `VirtualServiceMerge` & `VirtualService`.
4. User creates one or more `VirtualServiceMerge` CR instances.
5. Controller is triggered → Reconciler reads the CR spec, fetches the target `VirtualService`, applies patch logic, writes back the merged VirtualService update.
6. Kubernetes propagates the updated VirtualService to the Istio control plane, effecting new routing.

##### Architectural Patterns & Technologies
- Controller Pattern (Reconciliation Loop)
- Kubernetes Custom Resource Definitions (CRDs)
- Go & controller-runtime (Kubebuilder) Framework
- Testing with mock clientsets (unit tests under `tests/mocks`).
- Containerization (Dockerfile) & CI/CD via GitHub Actions.

## Diagram (Mermaid)

```mermaid
graph TB
    %% User and CLI
    Kubectl["User / kubectl"]:::external

    %% Kubernetes Core
    subgraph "Kubernetes Cluster" 
        direction TB
        APIServer["API Server & etcd"]:::core
        CRDDef["CRD Definition\n(VirtualServiceMerge)"]:::custom
        CRInstance["Custom Resource\n(VirtualServiceMerge)"]:::custom
        VSResource["Target CR\n(VirtualService)"]:::custom
    end

    %% Istio
    IstioCP["Istio Control Plane"]:::external

    %% Operator Pod and internal components
    subgraph "Operator Pod" 
        direction TB
        EntryPoint["main.go"]:::operator
        Manager["Controller-runtime Manager"]:::operator
        Controller["VirtualServiceMerge Controller"]:::operator
        Reconciler["Reconciler Loop"]:::operator
    end

    %% Manifests and Code Repos
    subgraph "Source & Manifests" 
        direction TB
        APITypes["api/v1alpha1"]:::operator
        ControllerLogic["controller/"]:::operator
        ControllerTests["controller/ (tests)"]:::operator
        CRDManifest["manifest/crd.yaml"]:::custom
        OperatorManifest["manifest/operator.yaml"]:::core
        TestData["tests/data/"]:::operator
        Mocks["tests/mocks/"]:::operator
        Dockerfile["Dockerfile"]:::operator
        Dockerignore[".dockerignore"]:::operator
        Makefile["Makefile"]:::operator
        CI[".github/workflows/docker-build-push.yaml"]:::operator
        License["LICENSE"]:::operator
        Boilerplate["hack/boilerplate.go.txt"]:::operator
    end

    %% Flows
    Kubectl -->|"apply CRD"| CRDDef
    Kubectl -->|"apply Operator Manifest"| OperatorManifest
    Kubectl -->|"create CR instance"| CRInstance

    CRDManifest -->|"+ CRD YAML"| CRDDef
    OperatorManifest -->|"+ Deployment YAML"| EntryPoint

    APIServer -->|"watch CRD & CR"| Manager
    Manager -->|"start Controller"| Controller
    Controller -->|"enqueue event"| Reconciler
    Reconciler -->|"client-go GET VirtualService"| APIServer
    Reconciler -->|"client-go UPDATE VirtualService"| APIServer

    APIServer -->|"propagate VS update"| IstioCP

    %% Code to components
    EntryPoint -->|imports| APITypes
    EntryPoint -->|sets up| ControllerLogic
    ControllerLogic -->|uses| Mocks
    ControllerTests -->|tests| ControllerLogic
    TestData -->|fixtures| ControllerTests
    Dockerfile -->|build image| EntryPoint
    Makefile -->|build & push| CI

    %% Click events
    click EntryPoint "https://github.com/monimesl/istio-virtualservice-merger/blob/main/main.go"
    click APITypes "https://github.com/monimesl/istio-virtualservice-merger/tree/main/api/v1alpha1/"
    click ControllerLogic "https://github.com/monimesl/istio-virtualservice-merger/blob/main/controller/controller.go"
    click ControllerTests "https://github.com/monimesl/istio-virtualservice-merger/blob/main/controller/reconciler_tests.go"
    click CRDManifest "https://github.com/monimesl/istio-virtualservice-merger/blob/main/manifest/crd.yaml"
    click OperatorManifest "https://github.com/monimesl/istio-virtualservice-merger/blob/main/manifest/operator.yaml"
    click TestData "https://github.com/monimesl/istio-virtualservice-merger/blob/main/tests/data/vs-merge-1.yaml"
    click Mocks "https://github.com/monimesl/istio-virtualservice-merger/blob/main/tests/mocks/mock_client.go"
    click Dockerfile "https://github.com/monimesl/istio-virtualservice-merger/tree/main/Dockerfile"
    click Dockerignore "https://github.com/monimesl/istio-virtualservice-merger/blob/main/.dockerignore"
    click Makefile "https://github.com/monimesl/istio-virtualservice-merger/tree/main/Makefile"
    click CI "https://github.com/monimesl/istio-virtualservice-merger/blob/main/.github/workflows/docker-build-push.yaml"
    click License "https://github.com/monimesl/istio-virtualservice-merger/tree/main/LICENSE"
    click Boilerplate "https://github.com/monimesl/istio-virtualservice-merger/blob/main/hack/boilerplate.go.txt"

    %% Styles
    classDef core fill:#FDE74C,stroke:#333,stroke-width:1px
    classDef custom fill:#A7C957,stroke:#333,stroke-width:1px
    classDef operator fill:#4ECDC4,stroke:#333,stroke-width:1px
    classDef external fill:#FF6B6B,stroke:#333,stroke-width:1px
```
