Skip to content

Commit 92c9af4

Browse files
pau-hedgehogpau-hedgehog
committed
(architecture): add Fabric Management page
Signed-off-by: Pau Capdevila <pau@githedgehog.com>
1 parent 3260f8b commit 92c9af4

File tree

2 files changed

+119
-0
lines changed

2 files changed

+119
-0
lines changed

‎docs/architecture/.pages

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
nav:
22
- Overview: overview.md
3+
- Fabric Management: management.md
34
- Fabric Implementation: fabric.md
45
- ...

‎docs/architecture/management.md

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
```markdown
2+
# Fabric Management
3+
4+
The installation of a Hedgehog Fabric deployment is carried out using Fabricator (hhfab CLI). Once deployed, ongoing operations are managed via the [Kubernetes](https://kubernetes.io) CLI, [`kubectl`](https://kubernetes.io/docs/reference/kubectl/).
5+
6+
In this workflow, the Kubernetes API Server processes the Fabric Custom Resources (CRs) and forwards them to the Fabric Controller. The Fabric Controller then generates the required SONiC configurations and dispatches them to the Fabric Agent, which applies these configurations to the SONiC Config DB via gNMI. Simultaneously, Alloy collects metrics and logs from the SONiC switches, sending this information to the monitoring tools for continuous monitoring.
7+
8+
The diagram below illustrates the general workflow for fabric management as well as the interactions between control plane components and the SONiC switches that form the underlay.
9+
10+
```mermaid
11+
graph TD
12+
13+
%% Define the nodes (General Workflow excludes Git & ArgoCD)
14+
User[User]
15+
Kubectl[kubectl]
16+
Fabricator[Fabricator]
17+
18+
%% Control Node components
19+
subgraph ControlNode["Control Node"]
20+
K8S[Kubernetes API Server]
21+
FC[Fabric Controller]
22+
K9s[K9s]
23+
KubectlFabric["kubectl fabric"]
24+
end
25+
26+
%% SONiC Switch components
27+
subgraph SONiCSwitch["SONiC Switch"]
28+
FA[Fabric Agent]
29+
Alloy[Alloy]
30+
DB[SONiC Config DB]
31+
end
32+
33+
%% External monitoring
34+
Monitoring[Loki/Grafana/Tempo/Mimir]
35+
36+
%% Define the relationships
37+
Kubectl -.->|Direct kubectl commands| K8S
38+
User -.->|CLI| Fabricator
39+
User -.->|CLI| Kubectl
40+
Kubectl -.->|Plugin| KubectlFabric
41+
Fabricator -->|SSH access| K9s
42+
Fabricator -->|Applies CRs| K8S
43+
KubectlFabric -->|Interacts with| K8S
44+
K9s -->|UI Manages| K8S
45+
K8S -->|Sends CRDs| FC
46+
FC -->|Generates SONiC Configs| FA
47+
FA -->|Applies Config via gNMI| DB
48+
FA -->|Reports Metrics| Alloy
49+
Alloy -->|Sends Logs & Metrics| Monitoring
50+
```
51+
52+
---
53+
54+
## **Component Overview**
55+
56+
### **User**
57+
- **Creates Fabric CR YAMLs** and commits them to version control.
58+
- **Directly interacts with SONiC switches** via the Fabricator CLI.
59+
- **Uses [`kubectl`](https://kubernetes.io/docs/reference/kubectl/) and `kubectl fabric`** to interact with the Kubernetes API for fabric resource management.
60+
61+
### **Kubernetes API Server (K8S)**
62+
- Part of [Kubernetes](https://kubernetes.io).
63+
- Manages Fabric Custom Resources (CRs) and interacts with the **Fabric Controller (FC)**.
64+
65+
### **kubectl & kubectl fabric**
66+
- [`kubectl`](https://kubernetes.io/docs/reference/kubectl/) is the standard CLI tool for [Kubernetes](https://kubernetes.io).
67+
- `kubectl fabric` is a plugin that extends `kubectl` with fabric-specific commands and interacts with the Kubernetes API Server.
68+
69+
### **Fabricator**
70+
- CLI tool that provides direct interaction with the Kubernetes API.
71+
- Can apply configurations via **SSH access** (using **K9s**) or by directly managing Fabric CRs with YAML files.
72+
73+
### **K9s**
74+
- A Kubernetes UI that provides visibility and control over Kubernetes resources.
75+
76+
### **SONiC Switch Components**
77+
- **Fabric Agent:** Receives configurations from the Fabric Controller and applies them to the SONiC switches via gNMI.
78+
- **Alloy:** Monitors SONiC and reports metrics.
79+
- **SONiC Config DB:** Stores and manages switch configuration data.
80+
81+
### **Monitoring**
82+
- Logs and metrics from SONiC are collected and sent to [Loki](https://grafana.com/oss/loki/), [Grafana](https://grafana.com), [Tempo](https://grafana.com/oss/tempo/), and [Mimir](https://grafana.com/oss/mimir/) for visualization and analysis.
83+
84+
---
85+
86+
## **GitOps Functionality (ArgoCD)**
87+
88+
All explanations related to GitOps using [ArgoCD](https://argo-cd.readthedocs.io/en/stable/) are provided in this section.
89+
90+
- **User Actions:**
91+
- The user **creates Fabric CR YAMLs** and pushes them to a [Git repository](https://git-scm.com) for version control.
92+
- **ArgoCD Actions:**
93+
- [ArgoCD](https://argo-cd.readthedocs.io/en/stable/) monitors the Git repository.
94+
- ArgoCD **pulls the CRs from Git** and applies them to [Kubernetes](https://kubernetes.io) via the Kubernetes API Server.
95+
96+
```mermaid
97+
graph TD
98+
99+
%% Define the nodes (GitOps includes Git & ArgoCD)
100+
User[User]
101+
Kubectl[kubectl]
102+
Git[Git Repository]
103+
ArgoCD[ArgoCD]
104+
105+
%% Control Node components
106+
subgraph ControlNode["Control Node"]
107+
K8S[Kubernetes API Server]
108+
FC[Fabric Controller]
109+
end
110+
111+
%% Define the relationships
112+
User -->|Fabric CR YAMLs| Git
113+
Kubectl -.->|Direct kubectl commands| K8S
114+
User -.->|CLI| Kubectl
115+
Git -.->|ArgoCD pulls| ArgoCD
116+
ArgoCD -->|Applies CRs| K8S
117+
K8S -->|Sends CRDs| FC
118+
```

0 commit comments

Comments
 (0)