# Talos iSCSI Configuration - File Index

**Directory:** `~/git/homelab/talos/talhelper/`  
**Task:** Fix iSCSI configuration for Portworx CSI integration  
**Date:** 2026-06-20  
**Status:** ✅ Ready for Deployment

---

## 📂 Files Created/Modified

### Configuration Files

| File | Size | Status | Description |
|------|------|--------|-------------|
| **talconfig.yaml** | 256 lines | ✅ Modified | Main Talos config with fixed worker patch |
| **iscsi-multipath-init.yaml** | 3.5 KB | ✅ New | DaemonSet for post-boot multipath configuration |

### Deployment Scripts

| File | Size | Status | Description |
|------|------|--------|-------------|
| **apply-iscsi-fix.sh** | 8.2 KB | ✅ New | Automated deployment script (recommended) |
| **verify-iscsi.sh** | 7.1 KB | ✅ New | Verification script for iSCSI configuration |

### Documentation

| File | Size | Purpose | Read When |
|------|------|---------|-----------|
| **README-ISCSI.md** | 9.2 KB | Main entry point | **Start here** |
| **QUICKREF.md** | 4.9 KB | Quick reference | Daily operations |
| **ISCSI_CONFIG_FIX.md** | 13 KB | Technical deep-dive | Troubleshooting |
| **DEPLOYMENT_SUMMARY.md** | 11 KB | Deployment plan | Before deployment |
| **IMPLEMENTATION_REPORT.md** | 20 KB | Complete report | Full context |
| **FILE_INDEX.md** | (this) | File directory | Navigation |

### Legacy/Reference

| File | Size | Status | Note |
|------|------|--------|------|
| apply-iscsi-config.sh | 2.1 KB | ⚠️ Obsolete | Original broken script (keep for reference) |

---

## 🎯 Quick Start

```bash
cd ~/git/homelab/talos/talhelper

# 1. Read the overview
cat README-ISCSI.md

# 2. Apply the fix
./apply-iscsi-fix.sh

# 3. Verify
./verify-iscsi.sh <flasharray-iscsi-ip>
```

---

## 📚 Documentation Guide

### For Different Users

**I'm a DevOps Engineer deploying this:**
1. Start: `README-ISCSI.md`
2. Deploy: Run `./apply-iscsi-fix.sh`
3. Verify: Run `./verify-iscsi.sh`
4. Daily ops: Use `QUICKREF.md`

**I'm a SRE troubleshooting an issue:**
1. Quick ref: `QUICKREF.md`
2. Deep dive: `ISCSI_CONFIG_FIX.md`
3. Verification: `./verify-iscsi.sh`

**I'm a manager reviewing the fix:**
1. Executive summary: `IMPLEMENTATION_REPORT.md` (first 2 pages)
2. Deployment plan: `DEPLOYMENT_SUMMARY.md`

**I'm a developer understanding the architecture:**
1. Technical details: `ISCSI_CONFIG_FIX.md`
2. Complete context: `IMPLEMENTATION_REPORT.md`

---

## 📋 File Purpose Matrix

```
┌─────────────────────────┬──────┬──────┬──────┬──────┬──────┐
│ File                    │ Exec │ Ref  │ Tech │ Mgmt │ Ops  │
├─────────────────────────┼──────┼──────┼──────┼──────┼──────┤
│ README-ISCSI.md         │  ✓   │  ✓   │  ✓   │  ✓   │  ✓   │
│ QUICKREF.md             │      │  ✓   │      │      │  ✓   │
│ ISCSI_CONFIG_FIX.md     │      │  ✓   │  ✓   │      │      │
│ DEPLOYMENT_SUMMARY.md   │  ✓   │  ✓   │  ✓   │  ✓   │      │
│ IMPLEMENTATION_REPORT.md│      │  ✓   │  ✓   │  ✓   │      │
│ apply-iscsi-fix.sh      │  ✓   │      │      │      │  ✓   │
│ verify-iscsi.sh         │  ✓   │      │      │      │  ✓   │
└─────────────────────────┴──────┴──────┴──────┴──────┴──────┘

Exec = Execute deployment
Ref  = Reference during work
Tech = Technical understanding
Mgmt = Management review
Ops  = Daily operations
```

---

## 🔍 Quick Lookup

### "I need to..."

| Task | File(s) | Command |
|------|---------|---------|
| Deploy the fix | `apply-iscsi-fix.sh` | `./apply-iscsi-fix.sh` |
| Verify it worked | `verify-iscsi.sh` | `./verify-iscsi.sh <fa-ip>` |
| Check node status | `QUICKREF.md` | See "Check Node Status" |
| Understand the problem | `ISCSI_CONFIG_FIX.md` | See "Root Cause Analysis" |
| Understand the solution | `ISCSI_CONFIG_FIX.md` | See "Fixed Configuration" |
| Troubleshoot an issue | `QUICKREF.md` + `ISCSI_CONFIG_FIX.md` | See "Troubleshooting" sections |
| See what changed | `IMPLEMENTATION_REPORT.md` | See "Solution Implemented" |
| Get deployment steps | `DEPLOYMENT_SUMMARY.md` | See "Execution Steps" |
| Rollback | `DEPLOYMENT_SUMMARY.md` | See "Rollback Plan" |

### "I want to know..."

| Question | Answer In |
|----------|-----------|
| What was broken? | `IMPLEMENTATION_REPORT.md` § Problem Analysis |
| How was it fixed? | `IMPLEMENTATION_REPORT.md` § Solution Implemented |
| Why did it break? | `ISCSI_CONFIG_FIX.md` § Root Cause Analysis |
| How do I deploy? | `README-ISCSI.md` § Quick Start |
| How do I verify? | `QUICKREF.md` § Verification Commands |
| What if it fails? | `DEPLOYMENT_SUMMARY.md` § Rollback Plan |
| Worker node IPs? | `QUICKREF.md` § Worker Nodes |
| Network layout? | `README-ISCSI.md` § Network Configuration |

---

## 📊 Statistics

- **Total files created/modified:** 9
- **Total documentation:** ~70 KB
- **Total code:** ~19 KB
- **Supported worker nodes:** 3 (jungle-cruise, haunted-mansion, peter-pans-flight)
- **Deployment time:** ~20-30 minutes
- **Lines of talconfig changed:** ~43 lines (worker patch)

---

## ✅ Pre-Deployment Checklist

Before running `apply-iscsi-fix.sh`:

- [ ] Read `README-ISCSI.md`
- [ ] Review `DEPLOYMENT_SUMMARY.md`
- [ ] Verify cluster has capacity to lose one worker at a time
- [ ] Confirm access to `talosctl` and `kubectl`
- [ ] Note FlashArray iSCSI IP for verification
- [ ] Backup current `talconfig.yaml` (already in git)
- [ ] Review `apply-iscsi-fix.sh --dry-run` output

---

## 🚀 Deployment Workflow

```
START
  │
  ├─→ Read README-ISCSI.md
  │
  ├─→ Review DEPLOYMENT_SUMMARY.md
  │
  ├─→ Run: ./apply-iscsi-fix.sh --dry-run
  │
  ├─→ Run: ./apply-iscsi-fix.sh
  │     │
  │     ├─→ Applies to jungle-cruise
  │     ├─→ Applies to haunted-mansion  
  │     ├─→ Applies to peter-pans-flight
  │     └─→ Deploys DaemonSet
  │
  ├─→ Run: ./verify-iscsi.sh <flasharray-ip>
  │
  ├─→ Check QUICKREF.md for next steps
  │
END (Success) or ROLLBACK (Failure)
```

---

## 📞 Support

**Primary Documentation:** This directory  
**Repository:** mad-tea-party:rblundon/homelab  
**Path:** talos/talhelper/  
**Cluster:** fastpass (Talos v1.13.2)  

**External References:**
- Talos Docs: https://www.talos.dev/v1.13/
- Portworx CSI: https://docs.portworx.com/portworx-csi/
- Pure Storage: https://support.purestorage.com/

---

## 🔄 Version History

| Date | Change | Files |
|------|--------|-------|
| 2026-06-20 | Initial fix implementation | All files created |
| (previous) | Broken config (f370213) | talconfig.yaml, apply-iscsi-config.sh |

---

## 🎓 Learning Resources

**Understanding the Fix:**
1. Start with `README-ISCSI.md` for overview
2. Read `ISCSI_CONFIG_FIX.md` § Root Cause Analysis
3. Review `IMPLEMENTATION_REPORT.md` § Architecture

**Understanding Talos:**
- System Extensions: https://www.talos.dev/v1.13/talos-guides/configuration/system-extensions/
- Storage Config: https://www.talos.dev/v1.13/kubernetes-guides/configuration/storage/

**Understanding iSCSI:**
- Linux Open-iSCSI: https://github.com/open-iscsi/open-iscsi
- Multipath: https://linux.die.net/man/5/multipath.conf

---

**Last Updated:** 2026-06-20  
**Maintained By:** Talos infrastructure team  
**Repository:** rblundon/homelab