# spidernet-io/spiderpool architecture

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

- Interactive diagram: https://gitdiagram.com/spidernet-io/spiderpool
- Repository: https://github.com/spidernet-io/spiderpool

## Overview

##### Main Components
- KUBERNETES CLUSTER – Represent the cluster environment where Spiderpool’s components are deployed. Nodes host various pods and interact with the Kubernetes API (managed via CRDs).
- SPIDERPOOL AGENT – Deployed on every node (see cmd/spiderpool-agent). This component provides underlay network connectivity, performs health checks, exposes REST API endpoints (e.g., connectivity, runtime liveness/readiness), manages IPAM tasks on a per‑node basis, and communicates with underlying network interfaces (including support for MACVLAN, IPVLAN, SR‑IOV, and RDMA devices).
- SPIDERPOOL CONTROLLER – A central component (see cmd/spiderpool-controller) responsible for aggregating state from multiple nodes, managing CRDs, orchestrating IPAM allocation as well as performing garbage collection and IP reclamation. It interacts with the Kubernetes control plane using informers and manages key CRDs (for example, Spidercoordinator, Spiderendpoint, Spiderippool, etc.).
- SPIDERPOOL INIT & CLI TOOLS – (“spiderpool‑init”, “spiderpoolctl”) for installation, initial configuration, and troubleshooting as guided by the charts and installation docs.
- HELM CHARTS & DEPLOYMENT CONFIGURATION – The “charts/” directory shows the available Helm charts (with CRD manifests, daemonset, deployment, etc.) that are used to deploy Spiderpool in the Kubernetes cluster.

##### Relationships and Data Flow
- The Spiderpool Agent on each node monitors local network configurations (interfaces, RDMA resources) and interacts directly with the Kubernetes Pod network layers. It exposes REST endpoints (connectivity and runtime checks) and communicates with the controller.
- The Spiderpool Controller centrally monitors and reconciles the CRDs in the Kubernetes API. It communicates with agents by issuing commands and processing data regarding IP pool usage, reservation status, and garbage collection.
- Both components rely on the standardized API/CRD layer (defined in the “api” directory) for reliable communication and maintain a consistent state.
- A CI/CD and build/deployment pipeline (visible in the .github/workflows, Makefiles, and charts) supports continuous integration testing, image building, and version releases, which can be represented as an external “Deployment Pipeline” component.
- External consumers like “spiderpoolctl” interact with the API endpoints (or via direct kubectl interactions with CRDs) to perform administrative or diagnostic operations.

##### Architectural Patterns & Design Principles
- MODULAR DESIGN – The project cleanly separates concerns between node‑level agents, central controllers, and supporting libraries.
- CLIENT‑SERVER MODEL – The Spiderpool agent and controller communicate via REST APIs defined in the project’s API layer.
- CRD‑DRIVEN OPERATION – Leveraging Kubernetes’s extensibility with custom resource definitions to manage IPAM state and coordination.
- CI/CD INTEGRATION – Automated workflows, testing, and Helm chart deployments (as indicated by the extensive .github/workflows and charts directories).
- CLOUD‑NATIVE & CONTAINER‑ORCHESTRATED – Being developed as a Kubernetes “pod” based solution, the project fully embraces cloud‑native architectures.

##### Relevant Technologies and Frameworks
- Golang – The entire code is written in Go.
- Kubernetes – Uses CRDs, informers, and clientset libraries.
- Helm – For chart-based installations.
- Underlay CNI Plugins – Integration with Macvlan, Ipvlan, and SR‑IOV, plus RDMA support.
- CI/CD Workflows – GitHub Actions for building, testing, and releasing images.
- Networking Libraries – Custom packages for IPAM allocation, network configuration, and metrics.

- Clear labels for each major component: “Kubernetes Cluster”, “Spiderpool Agent”, “Spiderpool Controller”, “API/CRD Layer”, “CLI/Init Tools”, and “CI/CD Pipeline”.
- Annotations or call-outs for key processes like “IPAM allocation”, “health checking”, and “network connectivity”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Kubernetes Cluster and Internal Components
    subgraph "Kubernetes Cluster"
        K8s_API["Kubernetes API Server/CRDs"]:::k8s
        subgraph "Spiderpool Internal Components"
            Controller["Spiderpool Controller"]:::internal
            Agent["Spiderpool Agent"]:::internal
            API["API/CRD Layer"]:::internal
            InternalLibs["Internal Modules"]:::internal
        end
    end

    %% External Components
    CLI["CLI & Init Tools"]:::external
    Helm["Helm Charts & Deployment Config"]:::external
    CICD["CI/CD Pipeline"]:::external
    Network["Underlying Network Hardware/RDMA"]:::external

    %% Connections within Cluster
    K8s_API -->|"CRD_events"| Controller
    Controller -->|"Config_updates"| Agent
    Controller -->|"Uses"| API
    Agent -->|"APICalls"| API
    Agent -->|"Network_connectivity"| Network
    InternalLibs --> Controller
    InternalLibs --> Agent

    %% External Interactions
    CLI -->|"Admin_calls"| API
    Helm -->|"Deploys"| K8s_API
    CICD -->|"CI/CD_trigger"| Helm

    %% Style Definitions
    classDef k8s fill:#AEDFF7,stroke:#000,stroke-width:2px;
    classDef internal fill:#FFEDB6,stroke:#000,stroke-width:2px;
    classDef external fill:#C7F9CC,stroke:#000,stroke-width:2px;

    %% Click Events for Component Mapping
    click Agent "https://github.com/spidernet-io/spiderpool/tree/main/cmd/spiderpool-agent"
    click Agent "https://github.com/spidernet-io/spiderpool/tree/main/api/v1/agent"
    click Agent "https://github.com/spidernet-io/spiderpool/tree/main/images/spiderpool-agent"

    click Controller "https://github.com/spidernet-io/spiderpool/tree/main/cmd/spiderpool-controller"
    click Controller "https://github.com/spidernet-io/spiderpool/tree/main/api/v1/controller"
    click Controller "https://github.com/spidernet-io/spiderpool/tree/main/images/spiderpool-controller"

    click CLI "https://github.com/spidernet-io/spiderpool/tree/main/cmd/spiderpool-init"
    click CLI "https://github.com/spidernet-io/spiderpool/tree/main/cmd/spiderpoolctl"

    click API "https://github.com/spidernet-io/spiderpool/tree/main/api"

    click Helm "https://github.com/spidernet-io/spiderpool/tree/main/charts/spiderpool"

    click InternalLibs "https://github.com/spidernet-io/spiderpool/tree/main/pkg"

    click CICD "https://github.com/spidernet-io/spiderpool/tree/main/.github/workflows"
```
