(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 ;)

docs/architecture/management.md

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

qmonnet · 2025-06-27T10:16:48Z

I note this PR has been open for a while, what's the status? Is it still pending reviews from the three of us? 🙈

pau-hedgehog · 2025-06-27T13:26:30Z

I note this PR has been open for a while, what's the status? Is it still pending reviews from the three of us? 🙈

I addressed all comments a few weeks ago. But I understand we have more pressing priorities. Thus I didn't chase anyone

qmonnet

Nice document!

My high-level comment would be that it's not super-clear how it relates to the “Architecture” section, as it's somewhat of a mix of an architectural-ish description of the management processes and a command reference, with an intro and some headings that might make one believe it will be some user guide to manage the Fabric.

Just to be clear, I do agree your page is in the right section 🙂, but I'd try to rework it a little bit to orient it even more towards the architecture-description aspect, not sure how, maybe by making clear you introduce the different “actors” from your first Mermaid diagram, and explaining their different interactions - and keep the “reference” parts to a minimum. Maybe run your doc through some LLM, to see if it's got some useful input?

qmonnet · 2025-06-30T13:31:37Z

docs/architecture/management.md

+
+This section focuses on operational aspects of Hedgehog Fabric, explaining available tools and typical workflows for administrators. It builds upon the architectural concepts explained in the [Overview](overview.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/).


Suggested change

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

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

For consistency with kubectl formatting.

qmonnet · 2025-06-30T13:36:14Z

docs/architecture/management.md

+- **Uses [`kubectl`](https://kubernetes.io/docs/reference/kubectl/) and `kubectl fabric`** to interact with the Kubernetes API for fabric resource management.
+    - Can use their **own `kubectl` installation** or the one pre-installed on the control node as part of [k3s](https://k3s.io).
+
+### Kubernetes API Server (K8S)
+- Part of [Kubernetes](https://kubernetes.io).
+- Manages Fabric Custom Resources (CRs) and interacts with the **Fabric Controller**.
+
+### kubectl & kubectl fabric
+- [`kubectl`](https://kubernetes.io/docs/reference/kubectl/) is the standard CLI tool for [Kubernetes](https://kubernetes.io).


Nit: I wouldn't keep all the web links to kubectl, k3s, Kubernetes this far down in the document, I find them more distracting than useful. Having them mentioned at the top is enough. Seeing the link to “k3s”, I'd rather expect it to link to a section of our docs that tells how k3s is used and what for, rather than to redirect me to the k3s website.

qmonnet · 2025-06-30T13:38:11Z

docs/architecture/management.md

+    - **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


This looks like a mix between the architectural description (rest of the doc) and a command reference. Do we need these here to understand the operational aspects? Should it link to a command reference instead?

qmonnet · 2025-06-30T13:39:56Z

docs/architecture/management.md

@@ -0,0 +1,127 @@
+# Fabric Management
+
+This section focuses on operational aspects of Hedgehog Fabric, explaining available tools and typical workflows for administrators. It builds upon the architectural concepts explained in the [Overview](overview.md).


If it's about operational aspects and typical workflows, then why is this located in the “Architecture” section, and not in “Use guides” for example?

qmonnet · 2025-06-30T13:40:38Z

docs/architecture/management.md

+### Fabricator
+- Using the **hhfab** CLI you can **SSH** the control node and use **K9s** or **kubectl** and **kubectl fabric** to manage or monitor Fabric API objects.


No need for a list?

Suggested change

### Fabricator

- Using the **hhfab** CLI you can **SSH** the control node and use **K9s** or **kubectl** and **kubectl fabric** to manage or monitor Fabric API objects.

### Fabricator

Using the **hhfab** CLI you can **SSH** the control node and use **K9s** or **kubectl** and **kubectl fabric** to manage or monitor Fabric API objects.

qmonnet · 2025-06-30T13:42:51Z

docs/architecture/management.md

+### K9s
+- K9s is a terminal based Kubernetes UI that provides visibility and control over Kubernetes resources, allowing you to manage pods, nodes, services, logs, and Fabric resources efficiently. It includes some helper plugins:


It includes some helper plugins

I'd mention they're specific to the Open Network Fabric (to make it explicit it's not some random plug-ins available on the web that we've only packaged).

qmonnet · 2025-06-30T13:43:12Z

docs/architecture/management.md

+    - **Power Reset** Perform a power reset on a fabric switch in the NOS
+    - **Reinstall** – Reinstall a fabric switch
+
+---


(Why the rule?)

qmonnet · 2025-06-30T13:44:44Z

docs/architecture/management.md

+
+- **User Responsibilities:**
+    - Define Fabric Custom Resources (CRs) in YAML.
+    - Commit and push these CRs to a [Git repository](https://git-scm.com) for version control and collaboration.


Do we really need to provide a link for Git? 😄

qmonnet · 2025-06-30T13:46:03Z

docs/architecture/management.md

+FC -->|Watches CRs| K8S
+```
+
+---


(why the rule?)

qmonnet · 2025-06-30T14:02:57Z

docs/architecture/management.md

+
+---
+
+## GitOps Integration


This might deserve a one-line transition to better tie it to the rest of the document? I don't know, maybe something like: “Given that the Fabric configuration heavily relies on Custom Definitions, users often rely on Git-centric workflows to manage them. GitOps is ...”

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 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

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

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

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

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

pau-hedgehog added 6 commits May 27, 2025 16:50

(architecture): add Fabric Management page

83d1e38

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

chore: refine and deduplicate architecture pages

2a88681

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

chore: expand kubectl fabric commands

fccedac

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

chore: clarify workflows and diagrams

3776f85

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

chore: remove incorrect fabricator workflows

1c2857f

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

chore: add clarification about kubectl

cc32af6

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

pau-hedgehog force-pushed the fabric_management branch from 857ac1d to cc32af6 Compare May 27, 2025 14:51

github-actions bot temporarily deployed to pull request May 27, 2025 14:51 Inactive

github-actions bot temporarily deployed to pull request May 27, 2025 14:57 Inactive

chore: remove heading text formatting

7c25e26

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

pau-hedgehog force-pushed the fabric_management branch from fc41353 to 7c25e26 Compare May 27, 2025 15:04

pau-hedgehog requested review from qmonnet and edipascale May 27, 2025 15:05

github-actions bot temporarily deployed to pull request May 27, 2025 15:05 Inactive

fix: k8s controller and API server workflow

2a57442

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

github-actions bot temporarily deployed to pull request May 27, 2025 15:12 Inactive

qmonnet requested changes Jun 30, 2025

View reviewed changes


		This section focuses on operational aspects of Hedgehog Fabric, explaining available tools and typical workflows for administrators. It builds upon the architectural concepts explained in the [Overview](overview.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/).

		@@ -0,0 +1,127 @@
		# Fabric Management

		This section focuses on operational aspects of Hedgehog Fabric, explaining available tools and typical workflows for administrators. It builds upon the architectural concepts explained in the [Overview](overview.md).

		### Fabricator
		- Using the hhfab CLI you can SSH the control node and use K9s or kubectl and kubectl fabric to manage or monitor Fabric API objects.

		### K9s
		- K9s is a terminal based Kubernetes UI that provides visibility and control over Kubernetes resources, allowing you to manage pods, nodes, services, logs, and Fabric resources efficiently. It includes some helper plugins:

(architecture): add Fabric Management page #71

Are you sure you want to change the base?

(architecture): add Fabric Management page #71

Uh oh!

Conversation

pau-hedgehog commented Mar 5, 2025

Uh oh!

github-actions bot commented Mar 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

edipascale commented Mar 21, 2025

Uh oh!

mrbojangles3 commented Mar 21, 2025

Uh oh!

pau-hedgehog commented Mar 24, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

qmonnet commented Jun 27, 2025

Uh oh!

pau-hedgehog commented Jun 27, 2025

Uh oh!

qmonnet left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Mar 5, 2025 •

edited

Loading