Add tech_docs/netbox.md

tech_docs/netbox.md

@@ -0,0 +1,121 @@
+NetBox is frequently mentioned in network automation discussions (including ours) because it’s the **de facto "source of truth" (SoT)** for network engineers automating with Jinja2. Here’s why it’s so critical—and how it supercharges your Jinja2 workflows:
+
+---
+
+### **1. What NetBox Solves for Network Automation**
+#### **Problem Before NetBox:**
+- Device data (IPs, VLANs, interfaces) lives in **spreadsheets, random docs, or people’s heads**.
+- Jinja2 templates need structured input (YAML/JSON), but manually maintaining variable files is unsustainable at scale.
+
+#### **NetBox’s Role:**
+- Acts as a **centralized, API-driven database** for all network metadata:
+  - Devices, racks, cables
+  - IPAM (IP addresses, prefixes)
+  - VLANs, VRFs, tenants
+  - Even circuit mappings
+- **Jinja2’s perfect partner**: NetBox exports structured data (via API) → feeds directly into your templates.
+
+---
+
+### **2. Concrete Examples: NetBox + Jinja2**
+#### **A. Auto-Generate Device Configs**
+**Without NetBox:**  
+You manually create YAML files like this for each device:
+```yaml
+# vars/switch01.yml
+device:
+  name: "switch01"
+  mgmt_ip: "10.0.0.1"
+  vlans: [100, 200]
+```
+
+**With NetBox:**  
+Python fetches device data from NetBox’s API → Jinja2 renders it:
+```python
+# fetch_netbox.py
+import requests
+device = requests.get("https://netbox/api/dcim/devices/?name=switch01").json()
+# Pass 'device' directly to Jinja2
+```
+
+**Jinja2 Template:**  
+```jinja
+hostname {{ device.name }}
+interface vlan1
+ ip address {{ device.primary_ip.address | split('/') | first }}
+```
+
+---
+
+#### **B. Dynamic Documentation (Always Updated)**
+NetBox tracks **device relationships** (e.g., "CoreSwitch1 connects to FirewallA via port Eth1/1").  
+Jinja2 can auto-generate diagrams or runbooks:
+```jinja
+{# templates/doc.j2 #}
+## Connections for {{ device.name }}
+{% for cable in device.cables %}
+- {{ cable.port }} → {{ cable.peer_device }} ({{ cable.peer_port }})
+{% endfor %}
+```
+
+---
+
+### **3. Why NetBox > Spreadsheets/Manual YAML**
+| Feature | NetBox | Manual YAML/Sheets |
+|---------|--------|---------------------|
+| **Single Source of Truth** | ✅ API-driven, always up-to-date | ❌ Fragmented copies |
+| **Data Validation** | ✅ Enforces formats (e.g., valid IPs) | ❌ Human errors creep in |
+| **Relationships** | ✅ Tracks device/port/cable links | ❌ Manual cross-referencing |
+| **Scalability** | ✅ Handles 10 or 10,000 devices | ❌ Falls apart at scale |
+| **Audit Logs** | ✅ Tracks who changed what | ❌ No history |
+
+---
+
+### **4. NetBox + Jinja2 Workflow**
+1. **Design in NetBox:**  
+   - Define devices, IPs, VLANs in the web UI/API.
+2. **Fetch Data:**  
+   - Use Python’s `requests` or Ansible’s `uri` module to pull NetBox data.
+3. **Template It:**  
+   - Feed NetBox’s JSON/YAML into Jinja2.
+4. **Deploy:**  
+   - Push rendered configs via Ansible/SSH.
+
+**Example Ansible Playbook:**
+```yaml
+- name: "Generate configs from NetBox"
+  hosts: localhost
+  tasks:
+    - name: "Query NetBox API"
+      uri:
+        url: "https://netbox/api/dcim/devices/?name={{ inventory_hostname }}"
+        headers: { "Authorization": "Token YOUR_API_TOKEN" }
+      register: netbox_data
+
+    - name: "Render config"
+      template:
+        src: "templates/cisco.j2"
+        dest: "configs/{{ inventory_hostname }}.cfg"
+      vars:
+        device: "{{ netbox_data.json.results[0] }}"
+```
+
+---
+
+### **5. When NetBox Isn’t Needed**
+- **Small networks** (<20 devices): YAML files might suffice.
+- **One-off configs**: Manual templates work.
+- **No API access**: Use CSV exports as a middle ground.
+
+---
+
+### **6. Getting Started with NetBox**
+1. **Deploy NetBox**: [Official docs](https://netbox.readthedocs.io/) (Docker/Python).
+2. **Populate Data**: Start with devices, IPs, VLANs.
+3. **Integrate**:  
+   - **Python**: `pip install pynetbox`  
+   - **Ansible**: Use `community.netbox.nb_lookup` plugin.
+
+**Key Takeaway:** NetBox turns Jinja2 from a templating tool into a **scalable network automation engine**. The combo lets you manage network state as code—no more guessing if your spreadsheets match reality.  
+
+Want a step-by-step guide to linking NetBox + Jinja2? I can break down a real-world example (e.g., auto-generating BGP configs from NetBox data).