From de03daad36517f3257967e5afe6d3d28d96e9f16 Mon Sep 17 00:00:00 2001
From: Benjamin Ritter <benjamin.ritter@x-cellent.com>
Date: Mon, 20 Apr 2026 15:27:56 +0200
Subject: [PATCH 1/2] docs: WIP add docs refactoring notes

Co-authored-by: Matthias Hartmann <mahartma@mahartma.com>
---
 NOTES.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 89 insertions(+)
 create mode 100644 NOTES.md

diff --git a/NOTES.md b/NOTES.md
new file mode 100644
index 00000000..092417ed
--- /dev/null
+++ b/NOTES.md
@@ -0,0 +1,89 @@
+# Deployment Flow
+
+0. load env variables from release vector
+    - `make env`
+    - runs ./env.sh
+
+1. generate certs
+    - `make gen-certs`
+
+1. Metalstack controlplane
+    - Create kind cluster
+        - `make control-plane-bake`
+        - kind config: ./control-plane/kind.yaml
+    - Create Proxy Registries
+        - `make create-proxy-registries`
+        - docker containers defined in ./compose.yaml
+    - Install Metalstack Control Plane
+        - `make control-plane`
+        -  control-plane in ./compose.yaml
+        - runs ansible playbook ./deploy_control_plane.yaml
+
+
+# Architecture / Concepts / Birds Eye View
+
+
+## Which flavors / how does the setup exactly look like?
+Which problems do those problems solve for the user?
+
+
+### Kamaji
+
+Runs a kind cluster next to a metal-stack partition, with the metal-stack control plane running inside the kind cluster.
+Launches a Kamaji 
+
+- run it from github.com/metal-stack/cluster-api-provider-metal-stack
+- set flavor to "kamaji"
+
+### CAPI
+- run it from github.com/metal-stack/cluster-api-provider-metal-stack
+- set flavor to "capi"
+
+
+# Machines
+
+The machines are OCI containers that run and ipmi_sim to provide a virtual IPMI and launch the machine using QEMU
+
+Access is possible using ipmi_tool. (TODO command)
+
+# Operator
+
+## How to access leafs
+
+Use ssh to access leafs. (We cannot access them via docker, as they run inside the qemu vm)
+```
+ssh -F files/ssh/config leaf01
+```
+
+Use `vtysh` to configure frr.
+
+## Access machines and firewalls
+
+Use the ipmi console to access the machines and firewalls.
+TODO maybe introduce ssh support as well? But this could mean we have to introduce ignition configs and a lot of extra work, so maybe not worth it for now.
+
+```
+# firewalls need a password to be accessed via user metal, skip this one for machines
+make password-machine01
+
+make console-machine01
+```
+
+# Notes
+
+- *-bake naming is confusing. Bake implies that there is something there already
+- the makefile is confusing to understand, maybe move everything possible into ansible
+
+# Troubleshooting
+
+## File descriptors
+
+## Log into ghcr.io and docker hub
+
+## How to the mini-lab with a firewall
+
+## Sonic switches become unavailable after reboot
+
+likely: [roles/sonic/tasks/main.yaml](roles/sonic/tasks/main.yaml)
+
+TODO: make config part of persistent sonic configuration
\ No newline at end of file

From 7d13a08d79342ce9736423e23526d1c5c8cec11e Mon Sep 17 00:00:00 2001
From: Benjamin Ritter <benjamin.ritter@x-cellent.com>
Date: Thu, 23 Apr 2026 09:28:03 +0200
Subject: [PATCH 2/2] fix: docs updates

Signed-off-by: Benjamin Ritter <benjamin.ritter@x-cellent.com>
---
 NOTES.md | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/NOTES.md b/NOTES.md
index 092417ed..60fa042d 100644
--- a/NOTES.md
+++ b/NOTES.md
@@ -24,7 +24,12 @@
 
 
 ## Which flavors / how does the setup exactly look like?
-Which problems do those problems solve for the user?
+Which problems do those setups solve for the user?
+
+- maybe basic containerlab commands and graph?
+
+containerlab graph -t capi-lab/mini-lab/mini-lab.kamaji.yaml
+containerlab inspect --topo capi-lab/mini-lab/mini-lab.kamaji.yaml
 
 
 ### Kamaji
@@ -76,6 +81,8 @@ make console-machine01
 
 # Troubleshooting
 
+- Use the `resize` command inside the IPMI console to resize the terminal, otherwise it will be very small and hard to use.
+
 ## File descriptors
 
 ## Log into ghcr.io and docker hub