homelab/talos/talhelper/FILE_INDEX.md

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

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