(architecture): add Fabric Management page

Signed-off-by: Pau Capdevila <[email protected]>

Author: pau-hedgehog

docs/architecture/.pages

@@ -1,4 +1,5 @@
 nav:
   - Overview: overview.md
+  - Fabric Management: management.md
   - Fabric Implementation: fabric.md
   - ...

docs/architecture/management.md

@@ -0,0 +1,107 @@
+# Fabric Management
+
+This document describes the architecture for managing Hedgehog Fabric deployments using Kubernetes, `kubectl`, and supporting tools. The diagram below illustrates the interactions between components in the control plane and the SONiC switches.
+
+```mermaid
+graph TD
+
+%% Define the nodes
+User[User]
+Kubectl[kubectl]
+Fabricator[Fabricator]
+Git[Git Repository]
+ArgoCD[ArgoCD]
+
+%% Control Node components
+subgraph ControlNode["Control Node"]
+  K8S[Kubernetes API Server]
+  FC[Fabric Controller]
+  K9s[K9s]
+  KubectlFabric["kubectl fabric"]
+end
+
+%% SONiC Switch components
+subgraph SONiCSwitch["SONiC Switch"]
+  FA[Fabric Agent]
+  Alloy[Alloy]
+  DB[SONiC Config DB]
+end
+
+%% External monitoring
+Monitoring[Loki/Grafana/Tempo/Mimir]
+
+%% Define the relationships
+User -->|Fabric CR YAMLs| Git
+Kubectl -.->|Direct kubectl commands| K8S
+User -.->|CLI| Fabricator
+User -.->|CLI| Kubectl
+Kubectl -.->|Plugin| KubectlFabric
+Fabricator -->|SSH access| K9s
+Fabricator -->|Applies CRs| K8S
+KubectlFabric -->|Interacts with| K8S
+K9s -->|UI Manages| K8S
+Git -.->|ArgoCD pulls| ArgoCD
+ArgoCD -->|Applies CRs| K8S
+K8S -->|Sends CRDs| FC
+FC -->|Generates SONiC Configs| FA
+FA -->|Applies Config via gNMI| DB
+FA -->|Reports Metrics| Alloy
+Alloy -->|Sends Logs & Metrics| Monitoring
+
+%% Styling
+classDef ourComponent fill:#F4E1C1,stroke:#B38A56,stroke-width:2px
+classDef thirdParty fill:#e6e6e6,stroke:#999999,stroke-width:1px
+
+%% Apply styles
+class User,Git,ArgoCD,DB,Monitoring,Alloy,K9s,Kubectl,K8S thirdParty
+class FC,FA,Fabricator,KubectlFabric ourComponent
+```
+
+---
+
+## **Component Overview**
+
+### **User**
+The user interacts with the system via multiple interfaces:
+- **Creates Fabric CR YAMLs** and commits them to **Git** for version control and automation.
+- **Directly interacts with SONiC switches** via the Fabricator CLI.
+- **Uses `kubectl` and `kubectl fabric`** to interact with Kubernetes for fabric resource management.
+
+### **Git & ArgoCD**
+ArgoCD is not part of the Fabric but shown as an example on how to manage a fabric with standard GitOps tools:
+- Users **push Fabric Custom Resources (CRs) to Git**.
+- ArgoCD **pulls CRs from Git** and applies them to Kubernetes.
+
+### **Kubernetes API Server (K8S)**
+- Manages Fabric CRs and interacts with the **Fabric Controller (FC)**.
+- FC processes CRs and generates necessary SONiC configurations.
+
+### **kubectl & kubectl fabric**
+- `kubectl` is the standard CLI for Kubernetes.
+- `kubectl fabric` is a **plugin** that extends `kubectl` with fabric-specific commands.
+- `kubectl fabric` interacts with the **Kubernetes API Server** to manage Fabric resources.
+
+### **Fabricator**
+- CLI tool that provides direct interaction with the kubernetes API.
+- Can apply configurations via **SSH access to the control node and invoking K9s** or **directly manage fabric CRs** with YAML input files.
+
+### **K9s**
+- A Kubernetes UI that provides visibility and control over Kubernetes resources.
+
+### **SONiC Switch Components**
+- **Fabric Agent:** Receives configurations from the Fabric Controller and and applies them to the SONiC via gNMI.
+- **Alloy:** Monitors SONiC and reports metrics.
+- **SONiC Config DB:** Stores and manages switch configuration.
+
+### **Monitoring**
+- Logs and metrics from SONiC are collected and sent to **Loki, and Mimir** for visualization and analysis through **Grafana**.
+
+---
+
+## **Flow of Operations**
+1. **User defines Fabric CRs** and pushes them to **Git**.
+2. **ArgoCD syncs the CRs** and applies them to **Kubernetes**.
+3. **The Kubernetes API Server processes the CRs** and passes them to the **Fabric Controller**.
+4. **The Fabric Controller generates SONiC configurations** and sends them to the **Fabric Agent**.
+5. **The Fabric Agent applies configurations** to the **SONiC Config DB** via gNMI.
+6. **Alloy collects metrics and logs** from SONiC and sends them to **monitoring tools**.