# 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](IMPLEMENTATION-SUMMARY.md) for complete overview
2. **Before deployment**: Review [DEPLOYMENT-CHECKLIST.md](DEPLOYMENT-CHECKLIST.md)
3. **Deploy**: Follow instructions in [README.md](README.md)
4. **Daily ops**: Use [QUICKREF.md](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](IMPLEMENTATION-SUMMARY.md)
2. Read [README.md](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](talos-config-reference.yaml))
6. Run [validate-prereqs.sh](validate-prereqs.sh)

### Phase 2: Deployment
Follow [DEPLOYMENT-CHECKLIST.md](DEPLOYMENT-CHECKLIST.md) exactly.

### Phase 3: Post-deployment
Use [QUICKREF.md](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](https://docs.portworx.com/portworx-csi/)
- [FlashArray Prep Guide](https://docs.portworx.com/portworx-csi/install/prepare/flash-array)
- [Talos Storage](https://www.talos.dev/latest/kubernetes-guides/configuration/storage/)
- [Pure Support](https://support.purestorage.com/)

## Quick Commands

```bash
# 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](IMPLEMENTATION-SUMMARY.md)
- **How**: [README.md](README.md)
- **Step-by-step**: [DEPLOYMENT-CHECKLIST.md](DEPLOYMENT-CHECKLIST.md)
- **Quick help**: [QUICKREF.md](QUICKREF.md)

---

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