(architecture): add Fabric Management page #71

pau-hedgehog · 2025-03-05T22:53:33Z

No description provided.

github-actions · 2025-03-05T22:54:11Z

🚀 Deployed on https://preview-71--hedgehog-docs.netlify.app

docs/architecture/management.md

edipascale · 2025-03-21T10:38:36Z

this looks good @pau-hedgehog, my only concern is that I feel there's a big overlap between the first section in this PR and what you previously added in the architecture overview section, and I wonder whether we should just collapse the two sections into one. That being said, having more documentation is never a bad thing, so I'm not against adding this if you / other people feel that they're better kept separate.

mrbojangles3 · 2025-03-21T20:00:04Z

I support adding it. I can see that a user might say, what happens when I do X, Y or Z. They would have those questions answered in the Fabric Management Workflow.

pau-hedgehog · 2025-03-24T10:35:09Z

I've made some amendments to try to make both @edipascale and @mrbojangles3 happy ;)

Frostman · 2025-03-24T16:33:51Z

docs/architecture/management.md

+
+### **kubectl & kubectl fabric**
+- [`kubectl`](https://kubernetes.io/docs/reference/kubectl/) is the standard CLI tool for [Kubernetes](https://kubernetes.io).
+- `kubectl fabric` is a plugin that extends `kubectl` with fabric-specific commands and interacts with the Kubernetes API Server.


As you're going into that details in k9s section it would be good to describe fabric plugin capability to do inspects, ssh/reboot/reinstall here as well to avoid creating an impression that it's only available through the k9s

I'm adding:

It supports the following commands:
- vpc – Manage VPCs: create, attach, peer, or wipe all related resources
- switch – Manage switches: get IP, SSH, serial, reboot, reinstall
- connection – View connections: management, fabric, vpc-loopback
- switchgroup – Create SwitchGroups
- external – Manage external BGP peers and VPC peering
- wiring – Export fabric wiring diagrams
- inspect – Inspect and troubleshoot fabric resources:
- fabric – Overview of control nodes and switches
- switch, port – Status, counters, and usage
- server, connection – VPC/external attachments and link details
- vpc – Subnet attachments and reachability
- bgp, lldp – Neighbor status checks
- ip, mac – Lookup usage across the fabric
- access – Check reachability between VPCs, servers, and IPs

Frostman · 2025-03-24T16:35:15Z

docs/architecture/management.md

+
+---
+
+## **GitOps Functionality (ArgoCD)**


It's a bit misleading this way. Please explain GitOps in general and that it could be used with any tools that supports K8s (e.g. ArgoCD, Flux, etc.)

Good point. Changing to:

GitOps Integration

GitOps is a continuous deployment approach where the desired state of a Kubernetes cluster is stored in Git. A GitOps controller monitors this repository and ensures the actual cluster state matches the declared state, using the Kubernetes API.

Hedgehog Fabric is fully compatible with GitOps workflows and can be managed declaratively using any GitOps-compatible tool such as ArgoCD or Flux.

User Responsibilities:

Define Fabric Custom Resources (CRs) in YAML.

Commit and push these CRs to a Git repository for version control and collaboration.

GitOps Tool Responsibilities:

Monitor the Git repository for updates.

Apply changes to the cluster automatically via the Kubernetes API Server.

This enables seamless integration of Hedgehog Fabric into modern CI/CD pipelines and Git-centric workflows.

Frostman · 2025-03-24T16:35:56Z

docs/architecture/management.md

+
+GitOps workflows can be leveraged using [ArgoCD](https://argo-cd.readthedocs.io/en/stable/). This is an alternative approach to show that a Fabric can be used with industry standard tools seamlessly.
+
+- **User Actions:**


Could go as an example workflow with ArgoCD

refactored the GitOps section. See comment above

Frostman · 2025-03-24T16:37:32Z

docs/architecture/management.md

+
+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/).
+
+In this workflow, the Kubernetes API Server processes the Fabric Custom Resources (CRs) and forwards them to the Fabric Controller. The Fabric Controller then translates these high-level network intents into concrete network configurations and manages their application to the underlying infrastructure. The Controller continuously monitors the state of the network resources, ensuring they match the desired state defined in the CRs.


API Server isn't forwarding CRs, controllers watches API for CR changes

Frostman · 2025-03-24T16:37:57Z

docs/architecture/management.md

+Fabricator -->|Applies CRs| K8S
+KubectlFabric -->|Interacts with| K8S
+K9s -->|UI Manages| K8S
+K8S -->|Sends CRDs| FC


API Server isn't forwarding CRs, controllers watches API for CR changes

Frostman · 2025-03-24T16:38:23Z

docs/architecture/management.md

+User -.->|CLI| Fabricator
+User -.->|CLI| Kubectl
+Kubectl -.->|Plugin| KubectlFabric
+Fabricator -->|SSH access| K9s


Not sure what is represented by this, could you please elaborate?

This is how you usually access k9s, but maybe it's too detailed for what we want to display

hhfab vlab ssh -n control-1 k9s

Frostman · 2025-03-24T16:39:14Z

docs/architecture/management.md

+
+### **User**
+- **Creates Fabric CR YAMLs** and applies them through standard Kubernetes resource management.
+- **Directly interacts with SONiC switches** via the Fabricator CLI.


I guess it's about hhfab vlab ssh helper so it should be removed from here. Additionally, we don't allow users to do the changes on the switches

Frostman · 2025-03-24T16:39:56Z

docs/architecture/management.md

+- `kubectl fabric` is a plugin that extends `kubectl` with fabric-specific commands and interacts with the Kubernetes API Server.
+
+### **Fabricator**
+- CLI tool that provides direct interaction with the Kubernetes API.


It doesn't provide it, what do you mean?

At that time I was thinking of hhfab init -w but it's not the expected workflow. I'm removing it

Frostman · 2025-03-24T16:40:16Z

docs/architecture/management.md

+
+### **Fabricator**
+- CLI tool that provides direct interaction with the Kubernetes API.
+- Can apply configurations via **SSH access** (using **K9s**) or by directly managing Fabric CRs with YAML files.


Kinda same - I guess you're talking about hhfab vlab ssh which shouldn't be mentioned outside of the vlab section of the docs

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

qmonnet · 2025-04-22T11:00:24Z

docs/architecture/management.md

+
+---
+
+## **Management Workflow Overview**


I didn't go through the whole page, this is just a note in passing - I'd strongly recommend against manually formatting all section/subsection headings in bold. The formatting from the theme should be enough already, no need to add manual formatting; if we decided it's not enough, this is something we should change by tuning the CSS for the whole website, for consistency.

pau-hedgehog self-assigned this Mar 5, 2025

github-actions bot temporarily deployed to pull request March 5, 2025 22:54 Inactive

pau-hedgehog force-pushed the fabric_management branch from d74cb91 to 92c9af4 Compare March 7, 2025 14:39

github-actions bot temporarily deployed to pull request March 7, 2025 14:40 Inactive

pau-hedgehog force-pushed the fabric_management branch from 92c9af4 to c5b059c Compare March 7, 2025 15:11

github-actions bot temporarily deployed to pull request March 7, 2025 15:12 Inactive

pau-hedgehog force-pushed the fabric_management branch from c5b059c to 25c0ab0 Compare March 21, 2025 10:09

github-actions bot temporarily deployed to pull request March 21, 2025 10:10 Inactive

pau-hedgehog marked this pull request as ready for review March 21, 2025 10:24

pau-hedgehog requested a review from a team as a code owner March 21, 2025 10:24

pau-hedgehog requested a review from edipascale March 21, 2025 10:24

edipascale reviewed Mar 21, 2025

View reviewed changes

docs/architecture/management.md Outdated Show resolved Hide resolved

github-actions bot temporarily deployed to pull request March 24, 2025 10:26 Inactive

pau-hedgehog force-pushed the fabric_management branch from 3aa7d55 to 84a529a Compare March 24, 2025 10:29

github-actions bot temporarily deployed to pull request March 24, 2025 10:29 Inactive

pau-hedgehog force-pushed the fabric_management branch from 84a529a to 6c99034 Compare March 24, 2025 10:34

github-actions bot temporarily deployed to pull request March 24, 2025 10:35 Inactive

edipascale previously approved these changes Mar 24, 2025

View reviewed changes

Frostman requested changes Mar 24, 2025

View reviewed changes

pau-hedgehog added 3 commits April 15, 2025 18:05

(architecture): add Fabric Management page

471df45

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

chore: refine and deduplicate architecture pages

3b76341

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

chore: expand kubectl fabric commands

88b640e

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

pau-hedgehog dismissed edipascale’s stale review via 88b640e April 15, 2025 16:07

pau-hedgehog force-pushed the fabric_management branch from 6c99034 to 88b640e Compare April 15, 2025 16:07

github-actions bot temporarily deployed to pull request April 15, 2025 16:08 Inactive

chore: clarify workflows and diagrams

6c1492b

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

github-actions bot temporarily deployed to pull request April 16, 2025 08:18 Inactive

pau-hedgehog requested review from Frostman April 16, 2025 08:18

chore: remove incorrect fabricator workflows

ca4a1fc

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

github-actions bot temporarily deployed to pull request April 16, 2025 08:29 Inactive

github-actions bot temporarily deployed to pull request April 16, 2025 08:50 Inactive

pau-hedgehog force-pushed the fabric_management branch from 44fe910 to 77b16ea Compare April 16, 2025 08:54

github-actions bot temporarily deployed to pull request April 16, 2025 08:54 Inactive

pau-hedgehog force-pushed the fabric_management branch from 77b16ea to 103bfe4 Compare April 16, 2025 08:55

github-actions bot temporarily deployed to pull request April 16, 2025 08:55 Inactive

chore: add clarification about kubectl

857ac1d

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

pau-hedgehog force-pushed the fabric_management branch from 103bfe4 to 857ac1d Compare April 16, 2025 09:55

github-actions bot temporarily deployed to pull request April 16, 2025 09:56 Inactive

qmonnet reviewed Apr 22, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

(architecture): add Fabric Management page #71

(architecture): add Fabric Management page #71

pau-hedgehog commented Mar 5, 2025

github-actions bot commented Mar 5, 2025 •

edited

Loading

edipascale commented Mar 21, 2025

mrbojangles3 commented Mar 21, 2025

pau-hedgehog commented Mar 24, 2025

Frostman Mar 24, 2025

pau-hedgehog Apr 16, 2025

Frostman Mar 24, 2025

pau-hedgehog Apr 16, 2025

Frostman Mar 24, 2025

pau-hedgehog Apr 16, 2025

Frostman Mar 24, 2025

Frostman Mar 24, 2025

Frostman Mar 24, 2025

pau-hedgehog Apr 16, 2025 •

edited

Loading

Frostman Mar 24, 2025

Frostman Mar 24, 2025

pau-hedgehog Apr 16, 2025 •

edited

Loading

Frostman Mar 24, 2025

qmonnet Apr 22, 2025


		GitOps workflows can be leveraged using [ArgoCD](https://argo-cd.readthedocs.io/en/stable/). This is an alternative approach to show that a Fabric can be used with industry standard tools seamlessly.

		- User Actions:


		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/).

		In this workflow, the Kubernetes API Server processes the Fabric Custom Resources (CRs) and forwards them to the Fabric Controller. The Fabric Controller then translates these high-level network intents into concrete network configurations and manages their application to the underlying infrastructure. The Controller continuously monitors the state of the network resources, ensuring they match the desired state defined in the CRs.

(architecture): add Fabric Management page #71

Are you sure you want to change the base?

(architecture): add Fabric Management page #71

Conversation

pau-hedgehog commented Mar 5, 2025

github-actions bot commented Mar 5, 2025 • edited Loading

edipascale commented Mar 21, 2025

mrbojangles3 commented Mar 21, 2025

pau-hedgehog commented Mar 24, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

GitOps Integration

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pau-hedgehog Apr 16, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pau-hedgehog Apr 16, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Mar 5, 2025 •

edited

Loading

pau-hedgehog Apr 16, 2025 •

edited

Loading

pau-hedgehog Apr 16, 2025 •

edited

Loading