Quick Start - OVN Topology Generation

IMMEDIATE ACTIONS (follow these steps in order):

1. Detect Cluster: Find the OVN-Kubernetes cluster kubeconfig

   Run: scripts/detect-cluster.sh 2>/dev/null

   The script discovers OVN-Kubernetes clusters:

   • Scans all kubeconfig files: current KUBECONFIG env, ~/.kube/kind-config, ~/ovn.conf, ~/.kube/config
   • Tests ALL contexts in each kubeconfig (not just current-context)
   • Returns parseable list to stdout: index|kubeconfig|cluster_name|node_count|namespace
   • Diagnostics go to stderr
   • Exit code: 0=success, 1=no clusters found

   How to handle the output:

   The script returns pipe-delimited lines to stdout, one per cluster found, e.g.:

   1|/home/user/.kube/kind-config|kind-ovn|3|ovn-kubernetes
   2|/home/user/.kube/config|prod-cluster|12|openshift-ovn-kubernetes
   

   Decision logic:

   • If one cluster found → automatically use it (extract kubeconfig path from column 2)
   • If multiple clusters found → show the list to user and ask them to choose by number
   • After selection, extract the kubeconfig path from column 2 of the chosen line
   • Store the selected kubeconfig path in variable KC for use in subsequent steps

   Example output format parsing:

   • Column 1: Index number (for user selection)
   • Column 2: Kubeconfig file path (this is what you need for $KC)
   • Column 3: Cluster display name
   • Column 4: Number of nodes
   • Column 5: OVN namespace name

   Important: Parse the output using standard text processing. The exact implementation is up to you - use whatever approach works best (awk, Python, inline parsing, etc.).

2. Check Permissions: Verify user's Kubernetes access level and inform about write permissions

   Run: scripts/check_permissions.py "$KC"

   The script returns:

   • Exit 0: Read-only access or user confirmed → proceed
   • Exit 1: Error or user cancelled → stop
   • Exit 2: Write permissions detected → AI must ask user for confirmation

   When exit code 2 is returned:

   1. Parse the stdout to get the list of write permissions
   2. Display the permissions clearly to the user using a formatted message
   3. Explain that:
      • This skill performs ONLY read-only operations
      • No cluster modifications will be made
      • The warning is for transparency about their access level
      • List read-only operations: kubectl get, kubectl exec (ovn-nbctl list), local file writes
      • List forbidden operations: kubectl create/delete/patch, ovn-nbctl modifications
   4. Ask the user explicitly: "You have cluster admin permissions. This command will only perform read-only operations. Do you want to proceed?"
   5. If user says yes → continue, if no → stop

   Example of proper user communication:

   ⚠️  WARNING: Write Permissions Detected
   
   Your kubeconfig has cluster admin permissions:
     • Delete pods, deployments, services
     • Create and modify resources
     • Full cluster access
   
   📋 IMPORTANT:
   This command will ONLY perform read-only operations:
     ✅ kubectl get (pods, nodes)
     ✅ kubectl exec (to run read-only ovn-nbctl list commands)
     ✅ Local file writes (topology diagram)
   
   Operations that will NEVER be performed:
     ❌ kubectl create/delete/patch/apply
     ❌ ovn-nbctl modifications
     ❌ Any cluster state changes
   
   Do you want to proceed with read-only topology generation?
   

   Security Note: This step ensures informed consent. The user must be explicitly aware that their cluster admin credentials are accessible to the AI agent (acting on their behalf), even though only read-only operations will be performed. This transparency is critical for security and trust.

3. Check Output File: Ask user if ovn-topology-diagram.md exists:

   • (1) Overwrite, (2) Custom path, (3) Timestamp, (4) Cancel

4. Create Private Temp Directory: Create a private temporary directory using mkdtemp and use it for all temporary files.

   TMPDIR=$(mktemp -d)
   

5. Collect OVN Data: Get full topology data from the cluster

   Run: scripts/collect_ovn_data.py "$KC" "$TMPDIR"

   Detail files written to $TMPDIR:

   • ovn_switches_detail.txt - node|uuid|name|other_config
   • ovn_routers_detail.txt - node|uuid|name|external_ids|options
   • ovn_lsps_detail.txt - node|name|addresses|type|options
   • ovn_lrps_detail.txt - node|name|mac|networks|options
   • ovn_pods_detail.txt - namespace|name|ip|node

6. Analyze Placement: Determine per-node vs cluster-wide components

   Run: scripts/analyze_placement.py "$TMPDIR"

   Placement results written to $TMPDIR:

   • ovn_switch_placement.txt - name|placement (per-node|cluster-wide|cluster-wide-visual)
   • ovn_router_placement.txt - name|placement (per-node|cluster-wide|cluster-wide-visual)

7. Generate Diagram: Create Mermaid graph BT diagram

   • Read $TMPDIR/ovn_switch_placement.txt to determine where each switch goes
   • Read $TMPDIR/ovn_router_placement.txt to determine where each router goes
   • Read detail files directly (ovn_switches_detail.txt, ovn_routers_detail.txt, etc.)
   • Skip UUID column when parsing switches/routers detail files
   • If placement is per-node → put inside node subgraph
   • If placement is cluster-wide or cluster-wide-visual → put outside subgraphs

8. Save & Report: Write diagram to file, show summary, clean up temporary files

CRITICAL RULES:

• ❌ NO codebase searching for IPs/MACs
• ❌ NO synthetic/example data
• ❌ NO inline multi-line bash (use helper scripts)
• ❌ NO direct kubectl commands (must use helper scripts only)
• ✅ Use helper scripts for all kubectl interactions and architecture discovery
• ✅ For helper scripts only: If kubectl is required, use KUBECONFIG="$KC" kubectl --kubeconfig="$KC"
• ✅ SECURITY: Create private temp directory with TMPDIR=$(mktemp -d) - never use /tmp directly
• ✅ Temporary files use $TMPDIR (private directory created with mkdtemp)
• ✅ Clean up temporary files when done: rm -rf "$TMPDIR"

Safety & Security Guarantees

🔒 Read-Only Operations

This skill performs ONLY read-only operations against your Kubernetes cluster. No cluster state is modified.

Allowed Operations:

• ✅ kubectl get - Query resources
• ✅ kubectl exec ... ovn-nbctl list - Query OVN database (read-only)
• ✅ Local file writes (temporary files in $TMPDIR, output diagram)

Forbidden Operations (NEVER used):

• ❌ kubectl create/apply/delete/patch - No resource modifications
• ❌ kubectl scale/drain/cordon - No cluster operations
• ❌ ovn-nbctl create/set/add/remove/destroy - No OVN modifications
• ❌ No pod restarts or service disruptions

Privacy Consideration: The generated diagram contains network topology information. Control sharing appropriately based on your security policies.

Architecture Concepts

Interconnect Mode (Distributed NBDB)

In interconnect mode, each node runs its own NBDB with local copies of components:

Per-Node Components (different UUIDs on each node):

• ovn_cluster_router - Each node has its own cluster router instance
• join switch - Each node has its own join switch instance
• transit_switch - Each node has its own transit switch instance
• Node switches (e.g., ovn-control-plane, ovn-worker)
• External switches (e.g., ext_ovn-control-plane)
• Gateway routers (e.g., GR_ovn-control-plane)

Visualization Overrides:

• transit_switch: PER-NODE in reality → shown CLUSTER-WIDE for visualization clarity
• join: PER-NODE → kept PER-NODE (no override)

Helper Scripts

All helper scripts are in the scripts/ directory.

Diagram Generation Rules

Structure

graph BT
    subgraph node1["<b style='color:black'>Node: name (node_ip)</b>"]
        direction BT

        %% LAYER 1 (Bottom): Pods and Management Ports
        POD_example["Pod: pod-name<br/>Namespace: ns<br/>IP: x.x.x.x"]
        MGMT["Management Port: k8s-node<br/>IP: x.x.x.x"]

        %% LAYER 2: Pod LSPs
        LSP_pod["LSP: namespace_pod-name<br/>MAC: xx:xx:xx:xx:xx:xx<br/>IP: x.x.x.x"]
        LSP_mgmt["LSP: k8s-node<br/>MAC: xx:xx:xx:xx:xx:xx<br/>IP: x.x.x.x"]

        %% LAYER 3: Node Switch
        LS_node["Logical Switch: node-name<br/>Subnet: x.x.x.x/24"]

        %% LAYER 4: Node Switch LSPs
        LSP_stor["LSP: stor-node<br/>Type: router"]

        %% LAYER 5: Cluster Router
        LR_cluster["Logical Router: ovn_cluster_router"]
        LRP_rtos["LRP: rtos-node<br/>MAC: xx:xx<br/>IP: x.x.x.x/24"]
        LRP_rtoj["LRP: rtoj-ovn_cluster_router<br/>IP: x.x.x.x/16"]
        LRP_rtots["LRP: rtots-node<br/>IP: x.x.x.x/16"]

        %% LAYER 6: Join Switch
        LS_join["Logical Switch: join"]
        LSP_jtor_cr["LSP: jtor-ovn_cluster_router<br/>Type: router"]
        LSP_jtor_gr["LSP: jtor-GR_node<br/>Type: router"]

        %% LAYER 7: Gateway Router
        LR_gr["Gateway Router: GR_node"]
        LRP_rtoj_gr["LRP: rtoj-GR_node<br/>IP: x.x.x.x/16"]
        LRP_rtoe["LRP: rtoe-GR_node<br/>IP: x.x.x.x/24"]

        %% LAYER 8: External Switch
        LS_ext["Logical Switch: ext_node"]
        LSP_etor["LSP: etor-GR_node<br/>Type: router"]
        LSP_breth0["LSP: breth0_node<br/>Type: localnet"]

        %% LAYER 9 (Top): External Network
        EXT_NET["External Network<br/>Physical bridge: breth0<br/>Node IP: x.x.x.x"]

        %% Connections (bottom-to-top flow)
        POD_example --> LSP_pod --> LS_node
        MGMT --> LSP_mgmt --> LS_node
        LS_node --> LSP_stor
        LSP_stor -.->|peer| LRP_rtos --> LR_cluster
        LR_cluster --> LRP_rtoj -.->|peer| LSP_jtor_cr --> LS_join
        LS_join --> LSP_jtor_gr -.->|peer| LRP_rtoj_gr --> LR_gr
        LR_gr --> LRP_rtoe -.->|peer| LSP_etor --> LS_ext
        LS_ext --> LSP_breth0 -.->|physical| EXT_NET
        LR_cluster --> LRP_rtots
    end

    %% Cluster-wide components (AFTER nodes to appear on top)
    %% Only include components with placement=cluster-wide or cluster-wide-visual
    %% Example: transit_switch in interconnect mode
    LS_cluster_component["Component Name<br/>Details"]

    %% Connections from nodes to cluster-wide components
    LRP_from_node -.->|connects to| LSP_cluster_port --> LS_cluster_component

Key Requirements

1. Graph Direction: Always graph BT (bottom-to-top)

2. Component Placement: Determined by $TMPDIR/ovn_*_placement.txt

   • per-node → INSIDE node subgraph
   • cluster-wide or cluster-wide-visual → OUTSIDE all subgraphs, defined AFTER all node subgraphs
   • CRITICAL: Define ALL cluster-wide components AFTER all nodes to position them at the TOP
     • Prevents connection lines from overlapping with node subgraphs
     • Applies to ANY component with cluster-wide or cluster-wide-visual placement

3. Node Subgraphs: Each physical node gets a subgraph with direction BT

   • Node Ordering: ALWAYS order nodes as: control-plane node first, then worker nodes sorted alphabetically by name
   • Title format: "<b style='color:black'>Node: {node_name} ({external_ip})</b>"
   • Get external IP from rtoe-GR_{node} router port network field
   • Use different background colors for each node for visual distinction
   • CRITICAL: Define components in BOTTOM-TO-TOP order (matches packet flow):
     1. Bottom Layer: Pods and Management Ports (traffic originates here)
     2. Layer 2: Pod LSPs
     3. Layer 3: Node Switch (where pods connect)
     4. Layer 4: Node Switch LSPs (stor, breth0)
     5. Layer 5: Cluster Router + Router Ports (rtos, rtoj, rtots)
     6. Layer 6: Join Switch + Join LSPs
     7. Layer 7: Gateway Router + Router Ports (rtoj, rtoe)
     8. Layer 8: External Switch + External LSPs (etor, breth0)
     9. Top Layer: External Network (physical bridge)

4. Pod Representation:

   • CRITICAL: Show ALL pods from $TMPDIR/ovn_pods_detail.txt as SEPARATE entities
   • DO NOT discover pods from LSPs - many pods (host-network) don't have individual LSPs
   • Pod format: POD_{id}["Pod: {name}<br/>Namespace: {ns}<br/>IP: {ip}"]
   • Connect pods to their respective LSPs:
     • Host-network pods (IP == node IP): POD_{id} --> MGMT_{node} --> LSP_k8s_{node}
     • Pod-network pods (IP in 10.244.x.x): POD_{id} --> LSP_{namespace}_{podname}

5. Physical Network Layer:

   • Show explicit external network entities per node
   • Format: EXT_NET_{node}["External Network<br/>Physical bridge: breth0<br/>Node IP: {external_ip}"]
   • Connect localnet LSPs to external network: LSP_breth0_{node} -.->|physical| EXT_NET_{node}

6. Colors (apply using classDef with color:#000 for black text):

   • Pods: fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#000
   • Switches: fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#000
   • Routers: fill:#fff9c4,stroke:#f57f17,stroke-width:2px,color:#000
   • LSPs (ALL types): fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#000
   • LRPs: fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px,color:#000
   • External Network: fill:#e0e0e0,stroke:#424242,stroke-width:2px,color:#000
   • Management Ports (MGMT entities only, not LSPs): fill:#fff8e1,stroke:#f57c00,stroke-width:2px,color:#000
   • Node Subgraph Backgrounds (use style statements, NOT classDef): Apply at END of diagram after all class assignments. Rotate through these 3 colors:
     • Node 1 (index 0): style node1 fill:#e8f5e9,stroke:#2e7d32,stroke-width:3px,stroke-dasharray: 5 5,color:#000 (green)
     • Node 2 (index 1): style node2 fill:#e1f5fe,stroke:#0277bd,stroke-width:3px,stroke-dasharray: 5 5,color:#000 (blue)
     • Node 3 (index 2): style node3 fill:#fff3e0,stroke:#ef6c00,stroke-width:3px,stroke-dasharray: 5 5,color:#000 (orange)
     • Node 4+ repeats: Use index % 3 to rotate colors (0=green, 1=blue, 2=orange)

7. Required Info:

   • Pods: Name, Namespace, IP
   • Switches: Name, Subnet (from other_config), Gateway (optional)
   • LSPs: Name, MAC, IP (or Type + Router Port for router ports)
   • LRPs: Name, MAC, Network (IP/CIDR)
   • Routers: Name, Description
   • External Network: Physical bridge name (breth0), Node IP

8. Connections:

   • Solid arrows: Layer connections
   • Dashed arrows with |peer|: Peer port relationships

Pod Discovery

CRITICAL: Discover pods from $TMPDIR/ovn_pods_detail.txt, NOT from LSPs

The file $TMPDIR/ovn_pods_detail.txt contains ALL running pods in the cluster (populated by collect_ovn_data.py). Format: namespace|pod_name|pod_ip|node_name

Pod-to-LSP Mapping Logic:

1. Read ALL pods from $TMPDIR/ovn_pods_detail.txt

2. For each pod, determine which LSP it connects to:

   a. Host-Network Pods (pod IP == node IP, e.g., 10.89.0.10):

   • Connect to management port LSP: k8s-{node}
   • These pods share the management port's IP address
   • MUST be included in diagram despite not having individual LSPs

   b. Pod-Network Pods (pod IP in pod network range, e.g., 10.244.x.x):

   • Connect to individual LSP: {namespace}_{pod-name-with-hash}
   • LSP name format: kube-system_coredns-674b8bbfcf-qhfrq
   • Filter LSPs where type="" (empty string)
   • Extract MAC and IP from LSP addresses field

3. Diagram representation:

   POD_id["Pod: {name}<br/>Namespace: {ns}<br/>IP: {ip}"]
   POD_id --> LSP_id
   

Special LSPs (NOT pods, treat as infrastructure):

• k8s-{node}: Management port LSP (multiple host-network pods connect to this)
• stor-{node}: Router port (type="router")
• breth0_{node}: LocalNet port (type="localnet")
• jtor-*, etor-*, tstor-*: Router ports (type="router")

Example: Control Plane Node with Host-Network Pods

%% 8 host-network pods sharing management port
POD_etcd["Pod: etcd-ovn-control-plane<br/>Namespace: kube-system<br/>IP: 10.89.0.10"]
POD_apiserver["Pod: kube-apiserver-ovn-control-plane<br/>Namespace: kube-system<br/>IP: 10.89.0.10"]
POD_controller["Pod: kube-controller-manager-ovn-control-plane<br/>Namespace: kube-system<br/>IP: 10.89.0.10"]
POD_scheduler["Pod: kube-scheduler-ovn-control-plane<br/>Namespace: kube-system<br/>IP: 10.89.0.10"]
POD_ovnkube_cp["Pod: ovnkube-control-plane-ovn-control-plane<br/>Namespace: ovn-kubernetes<br/>IP: 10.89.0.10"]
POD_ovnkube_id["Pod: ovnkube-identity-ovn-control-plane<br/>Namespace: ovn-kubernetes<br/>IP: 10.89.0.10"]
POD_ovnkube_node["Pod: ovnkube-node-xyz<br/>Namespace: ovn-kubernetes<br/>IP: 10.89.0.10"]
POD_ovs_node["Pod: ovs-node-xyz<br/>Namespace: ovn-kubernetes<br/>IP: 10.89.0.10"]

%% Management port LSP (shared by all host-network pods)
MGMT_cp["Management Port: k8s-ovn-control-plane<br/>IP: 10.89.0.10"]
LSP_mgmt["LSP: k8s-ovn-control-plane<br/>MAC: xx:xx:xx:xx:xx:xx<br/>IP: 10.244.0.2"]

%% All host-network pods connect to same management port
POD_etcd --> MGMT_cp
POD_apiserver --> MGMT_cp
POD_controller --> MGMT_cp
POD_scheduler --> MGMT_cp
POD_ovnkube_cp --> MGMT_cp
POD_ovnkube_id --> MGMT_cp
POD_ovnkube_node --> MGMT_cp
POD_ovs_node --> MGMT_cp

MGMT_cp --> LSP_mgmt --> LS_node

Final Steps

1. Generate complete Mermaid diagram following structure above
2. Save to file chosen by user
3. Show summary: nodes, switches, routers, ports, mode
4. Clean up temporary directory:

   rm -rf "$TMPDIR"
   

5. Tell user to open file in IDE to view rendered diagram