# liqotech/liqo architecture

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

- Interactive diagram: https://gitdiagram.com/liqotech/liqo
- Repository: https://github.com/liqotech/liqo

## Overview

From the file tree and README, it’s clear that Liqo is an open-source project built in Go that “enables dynamic and seamless Kubernetes multi-cluster topologies.” Its primary purpose is to allow heterogeneous clusters (spanning on-prem, cloud, edge) to peer with each other, offload workloads, and establish a transparent, secure network fabric (with additional support for stateful/storage fabrics). The project consists of multiple Go modules (including extensive CRDs, controllers, and CLI tools) that work together to extend native Kubernetes functionalities for multi-cluster communication.

##### Main Components
– Authentication (handling certificate creation, identity, nonce signing, etc.)
– Networking (handling external network configurations, internal-network fabric, IPAM integrations, firewall, and gateway tunnels [both Geneve and WireGuard])
– Offloading (managing offloaded workloads, namespace offloading, and virtual nodes)
– Additional controllers (e.g., CRD replicator, shadowpod controller, etc.)
- Liqo CLI (liqoctl): The command-line interface that interacts with the cluster to manage installation, offloading policies, and configuration. Mark this as a separate component that communicates with the Liqo controller manager.
- Gateways & Tunnels: Distinct gateway components (Geneve and WireGuard implementations) are built and deployed (as seen in cmd/gateway and pkg/gateway) to set up secured tunnels between clusters.
- Deployment Infrastructure: Include the deployment charts (the “deployments/liqo” folder) which are used to install Liqo in clusters and are part of the overall installation/management architecture.
- Supporting Tools / Infrastructure: Optionally, include build processes (build directory with Dockerfiles, Makefile) and testing (test/e2e) to illustrate the CI/CD pipeline and how changes are validated.

##### Relationships and Interactions
– Within each cluster, show the controller manager interacting with the Kubernetes API server via CRDs.
– Illustrate sub-module interactions inside the controller manager. For example, authentication modules work with identity managers and certificate creation modules, while networking modules interact with IPAM, firewall, and gateway (both client and server) submodules.
– Demonstrate that the custom resources (CRDs) enable registration and management of key Liqo objects representing peerings, offloaded workloads, and networking configurations.

##### Architectural Patterns and Technologies
– Modular design: Each functional area (authentication, networking, offloading) is implemented as separate modules (see the “pkg” and “internal” directories).
– Kubernetes Extension: Emphasize the use of CRDs and controllers to hook into Kubernetes ecosystems, following patterns common in Kubernetes operator frameworks.
– Multi-cluster/Distributed Architecture: Represent distinct clusters that can be on different cloud providers or on-prem, connected via secure tunnels.
– Containerization and CI/CD: Reflect the Docker builds and GitHub workflows that drive image creation and integration tests.
– Use of Go: Indicate that the primary implementation language is Go (as seen from file names like .go, go.mod, etc.), which is critical from a design viewpoint in terms of concurrency and reliability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Components
    LiqoCLI["Liqo CLI (liqoctl)"]:::cli
    DeployInfra["Deployment Infrastructure"]:::deploy
    CICD["CI/CD & Build/Testing"]:::cicd

    %% Cluster 1
    subgraph "Cluster 1"
        LCM1["Liqo Controller Manager"]:::manager
        LCM1Auth["Authentication"]:::submodule
        LCM1Net["Networking"]:::submodule
        LCM1Off["Offloading"]:::submodule
        LCM1Add["Additional Controllers"]:::submodule
        CRDs1["Kubernetes API Server (CRDs)"]:::api

        LCM1 -->|"manages"| CRDs1
        LCM1Auth -->|"auth->net"| LCM1Net
        LCM1Net -->|"net->offload"| LCM1Off
        LCM1Off -->|"offload->extra"| LCM1Add
    end

    %% Cluster 2
    subgraph "Cluster 2"
        LCM2["Liqo Controller Manager"]:::manager
        LCM2Auth["Authentication"]:::submodule
        LCM2Net["Networking"]:::submodule
        LCM2Off["Offloading"]:::submodule
        LCM2Add["Additional Controllers"]:::submodule
        CRDs2["Kubernetes API Server (CRDs)"]:::api

        LCM2 -->|"manages"| CRDs2
        LCM2Auth -->|"auth->net"| LCM2Net
        LCM2Net -->|"net->offload"| LCM2Off
        LCM2Off -->|"offload->extra"| LCM2Add
    end

    %% Gateways & Tunnels
    subgraph "Gateways & Tunnels"
        GatewayGeneve["Gateway (Geneve)"]:::gateway
        GatewayWireguard["Gateway (WireGuard)"]:::gateway
    end

    %% Interactions
    LiqoCLI -->|"APIcommands"| LCM1
    LiqoCLI -->|"APIcommands"| LCM2
    DeployInfra -->|"install"| LCM1
    DeployInfra -->|"install"| LCM2
    CICD -->|"build/test"| DeployInfra
    LCM1Net -->|"tunnel"| GatewayGeneve
    LCM2Net -->|"tunnel"| GatewayWireguard
    LCM1 ---|"secureTunnelTraffic"| LCM2

    %% Click Events
    click LiqoCLI "https://github.com/liqotech/liqo/blob/master/cmd/liqoctl/main.go"
    click DeployInfra "https://github.com/liqotech/liqo/tree/master/deployments/liqo"
    click CICD "https://github.com/liqotech/liqo/tree/master/build"
    
    click LCM1 "https://github.com/liqotech/liqo/blob/master/cmd/liqo-controller-manager/main.go"
    click LCM1Auth "https://github.com/liqotech/liqo/blob/master/cmd/liqo-controller-manager/modules/authentication.go"
    click LCM1Net "https://github.com/liqotech/liqo/blob/master/cmd/liqo-controller-manager/modules/networking.go"
    click LCM1Off "https://github.com/liqotech/liqo/blob/master/cmd/liqo-controller-manager/modules/offloading.go"
    click LCM1Add "https://github.com/liqotech/liqo/blob/master/cmd/crd-replicator/main.go"
    click CRDs1 "https://github.com/liqotech/liqo/tree/master/apis/authentication"
    
    click LCM2 "https://github.com/liqotech/liqo/blob/master/cmd/liqo-controller-manager/main.go"
    click LCM2Auth "https://github.com/liqotech/liqo/blob/master/cmd/liqo-controller-manager/modules/authentication.go"
    click LCM2Net "https://github.com/liqotech/liqo/blob/master/cmd/liqo-controller-manager/modules/networking.go"
    click LCM2Off "https://github.com/liqotech/liqo/blob/master/cmd/liqo-controller-manager/modules/offloading.go"
    click LCM2Add "https://github.com/liqotech/liqo/blob/master/cmd/crd-replicator/main.go"
    click CRDs2 "https://github.com/liqotech/liqo/tree/master/apis/authentication"
    
    click GatewayGeneve "https://github.com/liqotech/liqo/tree/master/cmd/gateway"
    click GatewayWireguard "https://github.com/liqotech/liqo/tree/master/cmd/gateway/wireguard"

    %% Styles
    classDef cli fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef manager fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef submodule fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef api fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef gateway fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef deploy fill:#FFFFE0,stroke:#333,stroke-width:2px;
    classDef cicd fill:#E0FFFF,stroke:#333,stroke-width:2px;
```
