homelab/cluster/platform/portworx-csi/INDEX.md

Portworx CSI for Pure Storage FlashArray - File Index

Quick navigation guide for Portworx CSI deployment files.

Quick Start

1. Start here: Read IMPLEMENTATION-SUMMARY.md for complete overview
2. Before deployment: Review DEPLOYMENT-CHECKLIST.md
3. Deploy: Follow instructions in README.md
4. Daily ops: Use QUICKREF.md for common commands

File Descriptions

Kubernetes Manifests (GitOps)

File	Purpose	ArgoCD Synced
application.yaml	ArgoCD Application definition for Portworx CSI	✅ Yes
operator-values.yaml	Helm values for Portworx Operator chart	✅ Yes (via Helm)
storagecluster.yaml	StorageCluster CR that triggers PX-CSI deployment	✅ Yes
externalsecret.yaml	Syncs FlashArray credentials from 1Password	✅ Yes
storageclass-block.yaml	StorageClass for FlashArray block volumes (iSCSI)	✅ Yes
storageclass-file.yaml	StorageClass for FlashArray File Services (NFS)	✅ Yes

Reference & Configuration

File	Purpose	Type
talos-config-reference.yaml	Talos node configuration patches (NOT a K8s resource)	⚠️ Reference only

IMPORTANT: talos-config-reference.yaml must be applied via talhelper or talosctl, not kubectl.

Documentation

File	Size	Purpose	When to Read
IMPLEMENTATION-SUMMARY.md	12KB	Complete implementation overview	First
README.md	17KB	Full deployment guide with architecture	Before deployment
DEPLOYMENT-CHECKLIST.md	12KB	Step-by-step deployment checklist	During deployment
QUICKREF.md	9KB	Quick reference for common operations	After deployment
INDEX.md	2KB	This file - navigation guide	Anytime

Tools

File	Type	Purpose
validate-prereqs.sh	Bash script	Pre-deployment validation (checks prerequisites)

File Dependencies

┌─────────────────────────────────────────────────────────────────┐
│ Git Repository (homelab)                                        │
│                                                                  │
│  ┌────────────────────────────────────────────────────────┐    │
│  │ application.yaml                                       │    │
│  │   ↓ references                                         │    │
│  │   ├→ operator-values.yaml (Helm values)                │    │
│  │   └→ All other manifests in this directory            │    │
│  └────────────────────────────────────────────────────────┘    │
│                                                                  │
│  ┌────────────────────────────────────────────────────────┐    │
│  │ storagecluster.yaml                                    │    │
│  │   ↓ references                                         │    │
│  │   └→ px-pure-secret (created by externalsecret.yaml)  │    │
│  └────────────────────────────────────────────────────────┘    │
│                                                                  │
│  ┌────────────────────────────────────────────────────────┐    │
│  │ externalsecret.yaml                                    │    │
│  │   ↓ syncs from                                         │    │
│  │   └→ 1Password: homelab/pure-flasharray-fastpass      │    │
│  └────────────────────────────────────────────────────────┘    │
│                                                                  │
│  ┌────────────────────────────────────────────────────────┐    │
│  │ storageclass-block.yaml                                │    │
│  │ storageclass-file.yaml                                 │    │
│  │   ↓ used by                                            │    │
│  │   └→ PVCs in application namespaces                   │    │
│  └────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ Talos Node Configuration (NOT in K8s)                           │
│                                                                  │
│  talos-config-reference.yaml → talconfig.yaml → talosctl       │
└─────────────────────────────────────────────────────────────────┘

Deployment Workflow

Phase 1: Pre-deployment

1. Read IMPLEMENTATION-SUMMARY.md
2. Read README.md → Prerequisites section
3. Configure FlashArray (create user, API token)
4. Add credentials to 1Password
5. Apply Talos patches (see talos-config-reference.yaml)
6. Run validate-prereqs.sh

Phase 2: Deployment

Follow DEPLOYMENT-CHECKLIST.md exactly.

Phase 3: Post-deployment

Use QUICKREF.md for daily operations.

Typical Reading Order

For First-Time Deployment

1. IMPLEMENTATION-SUMMARY.md - Understand what was created and why
2. README.md - Learn architecture and prerequisites
3. DEPLOYMENT-CHECKLIST.md - Follow deployment steps
4. validate-prereqs.sh - Run before deploying
5. QUICKREF.md - Bookmark for later reference

For Troubleshooting

1. QUICKREF.md - Common issues and commands
2. README.md → Troubleshooting section
3. DEPLOYMENT-CHECKLIST.md → Verify each step

For Maintenance

1. QUICKREF.md - Most operations are here
2. README.md - Deep dive if needed

File Sizes

• Total: 12 files, ~96KB on disk
• Documentation: 5 files, ~62KB (README, checklists, guides)
• Kubernetes Manifests: 6 files, ~11KB (YAML)
• Talos Reference: 1 file, ~5.4KB
• Tools: 1 file, ~7KB (validation script)

GitOps Integration

All Kubernetes manifests (.yaml files except talos-config-reference.yaml) are managed by ArgoCD:

• Application: portworx-csi in namespace argocd
• Sync Wave: 2 (after External Secrets, before applications)
• Auto-sync: Enabled
• Self-heal: Enabled
• Prune: Enabled

Changes to manifest files are automatically synced to the cluster.

External Dependencies

From Git Repository

• None - this is a platform component

From Upstream

• Helm Chart: https://raw.githubusercontent.com/portworx/px-operator/main/deploy/helm/charts
• Chart: px-operator version 25.0.0
• Image: portworx/px-csi:3.2.0

From Cluster

• External Secrets Operator (namespace: external-secrets)
• ClusterSecretStore (onepassword)
• ArgoCD (namespace: argocd)

From External Systems

• Pure Storage FlashArray (iSCSI endpoints, management API)
• 1Password (via External Secrets Operator)

Version Information

• Portworx Operator: 25.0.0
• PX-CSI Driver: 3.2.0
• Talos Linux: Any version with iSCSI support
• Kubernetes: 1.32.3 (fastpass cluster)

Support Resources

Internal Documentation

• This directory: Complete deployment guide
• Homelab repo: ~/git/homelab
• Talos config: talos/talhelper/talconfig.yaml

External Documentation

• Portworx CSI Docs
• FlashArray Prep Guide
• Talos Storage
• Pure Support

Quick Commands

# Validate prerequisites
./validate-prereqs.sh

# Check deployment status
kubectl get application -n argocd portworx-csi
kubectl get pods -n portworx

# View logs
kubectl logs -n portworx -l app=px-csi-controller --tail=50

# List volumes
kubectl get pvc --all-namespaces -o wide | grep pure

# Sync via ArgoCD
argocd app sync portworx-csi

Notes

• ⚠️ talos-config-reference.yaml is NOT a Kubernetes resource
• 📝 All secrets managed via External Secrets Operator (1Password)
• 🔄 ArgoCD auto-syncs changes from Git
• 📊 Prometheus metrics enabled by default
• 🚫 No default StorageClass (apps must opt-in)

Questions?

Refer to the appropriate documentation:

• What/Why: IMPLEMENTATION-SUMMARY.md
• How: README.md
• Step-by-step: DEPLOYMENT-CHECKLIST.md
• Quick help: QUICKREF.md

---

Last Updated: June 18, 2026
Cluster: fastpass (Talos Linux, K8s 1.32.3)
Status: Ready for deployment (pending FlashArray configuration)