# kubernetes-sigs/nfs-ganesha-server-and-external-provisioner architecture

> Architecture diagram of the GitHub repository kubernetes-sigs/nfs-ganesha-server-and-external-provisioner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kubernetes-sigs/nfs-ganesha-server-and-external-provisioner
- Repository: https://github.com/kubernetes-sigs/nfs-ganesha-server-and-external-provisioner

## Overview

##### Overall project type and purpose
- This is a Kubernetes storage provisioner that dynamically creates NFS-backed PersistentVolumes when persistent volume claims (PVCs) are issued in a Kubernetes cluster. It acts in a similar capacity to in-tree provisioners (like those for GCE or AWS) but is implemented as an external, out-of-tree solution.
- The README explains that it watches for PVCs matching a custom StorageClass configuration (via the “-provisioner” flag) and then provisions corresponding NFS volumes.

##### Key components based on the file structure
- The cmd directory (cmd/nfs-provisioner/main.go) is the entry point for the NFS provisioner’s container. This is where the main orchestration logic is found.
- The pkg directory (with subdirectories “server” and “volume”) contains the core business logic—handling provisioning, deletion, exporting, and quota management.
- The deploy/kubernetes folder hosts the YAML files required for deploying the provisioner in a Kubernetes environment (deployment, RBAC, StorageClass, etc.).
- The charts directory provides Helm charts for packaging and deploying the provisioner, which is useful for automation and easing installation in clusters.
- Additional folders (e.g., release-tools, test/e2e) and files (Dockerfile, Makefile, cloudbuild.yaml, GitHub workflows) indicate that automated building, testing, and release processes are part of the complete system.

##### Core components
a. Kubernetes Cluster Components:
- API Server—which registers StorageClass, PVC, and PV objects.
- RBAC objects (roles, rolebindings, service accounts) that secure the provisioner’s operations.
- Deployment of the provisioner using a StatefulSet or Deployment (from deploy/kubernetes/deployment.yaml) that mounts the storage volume (e.g., /export).
- StorageClass and PVC/PV resources that trigger the dynamic provisioning process.
b. Provisioner Application:
- The NFS Provisioner container (represented by the cmd/nfs-provisioner component) that actively watches the Kubernetes API.
- Internal modules from the pkg folder for processing volume lifecycle events.
- Communication between the provisioner and the Kubernetes API.
c. External Tools and Infrastructure:
- Helm charts for installation (from charts/nfs-server-provisioner).
- CI/CD pipelines (e.g., GitHub workflows and cloudbuild.yaml scripts) for automated builds, testing, and release.
- Docker images (built from Dockerfile(s) located at the top level and under deploy) which are deployed on the cluster.

##### Relationships and data flow
- The Kubernetes API sends events (like new PVC creation) to the provisioner application.
- The provisioner uses its internal packages (pkg/server, pkg/volume) to interact with the underlying NFS storage system.
- Deployment artifacts (from deploy/kubernetes) ensure that all Kubernetes-specific resources (service accounts, RBAC permissions, deployments, and storage classes) are correctly set up.
- CI/CD tools manage how container images are built and deployed, linking with the repository’s automated test suites and release processes.

##### Important architectural patterns and design principles
- Separation of concerns – clear division between the command line application (cmd), core business logic (pkg), deployment manifests (deploy), and packaging via Helm (charts).
- Kubernetes Operator pattern – though not a full operator, the provisioner continuously watches for PVC events, acting on these events as per dynamic provisioning guidelines.
- Automation and integration – with CI/CD workflows integrated into the GitHub and cloudbuild directories, and extensive use of configuration via YAML manifests.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Kubernetes Infrastructure"
        K8sAPI["Kubernetes API Server"]:::k8s
        RBAC["RBAC & Resource Definitions"]:::k8s
        PVC["PersistentVolumeClaim&StorageClass"]:::k8s
        K8sDeploy["Kubernetes Deployment (Provisioner)"]:::k8s
        PV["PersistentVolume (NFS)"]:::k8s
    end

    subgraph "Provisioner Application"
        NPContainer["NFS Provisioner Container (Entry Point)"]:::provisioner
        ServerModule["Server Module"]:::provisioner
        VolumeMgmt["Volume Management"]:::provisioner
    end

    subgraph "External Tools & CI/CD"
        Helm["Helm Chart Deployment"]:::cicd
        CICD["CI/CD & Automated Builds"]:::cicd
        Docker["Docker Image Build"]:::cicd
    end

    %% Kubernetes Infrastructure flows
    PVC -->|"creates"| K8sAPI
    K8sAPI -->|"sendsPVCEvent"| NPContainer
    K8sDeploy -->|"deploys"| NPContainer
    RBAC -->|"secures"| K8sDeploy
    NPContainer -->|"updatesStatus"| K8sAPI

    %% Provisioner Application internal interactions
    NPContainer -->|"invokes"| ServerModule
    NPContainer -->|"invokes"| VolumeMgmt
    VolumeMgmt -->|"provisionsVolume"| PV

    %% External CI/CD interactions
    CICD -->|"triggersBuild"| Docker
    Docker -->|"buildsImageFor"| K8sDeploy
    CICD -->|"triggersHelmRelease"| Helm
    Helm -->|"deploysResources"| K8sDeploy

    %% Click Events
    click NPContainer "https://github.com/kubernetes-sigs/nfs-ganesha-server-and-external-provisioner/blob/master/cmd/nfs-provisioner/main.go"
    click ServerModule "https://github.com/kubernetes-sigs/nfs-ganesha-server-and-external-provisioner/blob/master/pkg/server/server.go"
    click VolumeMgmt "https://github.com/kubernetes-sigs/nfs-ganesha-server-and-external-provisioner/tree/master/pkg/volume"
    click K8sDeploy "https://github.com/kubernetes-sigs/nfs-ganesha-server-and-external-provisioner/tree/master/deploy/kubernetes"
    click Helm "https://github.com/kubernetes-sigs/nfs-ganesha-server-and-external-provisioner/tree/master/charts/nfs-server-provisioner"
    click CICD "https://github.com/kubernetes-sigs/nfs-ganesha-server-and-external-provisioner/tree/master/.github/workflows"
    click CICD "https://github.com/kubernetes-sigs/nfs-ganesha-server-and-external-provisioner/blob/master/cloudbuild.yaml"

    %% Styles
    classDef k8s fill:#aaffaa,stroke:#333,stroke-width:2px;
    classDef provisioner fill:#ffcc99,stroke:#333,stroke-width:2px;
    classDef cicd fill:#ccffff,stroke:#333,stroke-width:2px;
```
