How I Reorganized 45 Kubernetes Manifests (And You Should Too)
TL;DR: I took a messy flat structure of 45 manifest files and reorganized them into 8 logical component groups with clear dependencies, reducing confusion and deployment time. Here's how I did it and why it matters.
The Problem: 45 Files in One Directory
Imagine this:
talos/manifests/
├── argocd-applications.yaml
├── argocd.yaml
├── cert_manager.yaml
├── cilium-bgp-config.yaml
├── cilium-ingressclass.yaml
├── cilium-ingress-lb.yaml
├── cilium-ingress-rbac.yaml
├── cilium-l2-ippool.yaml
├── cilium-loadbalancer-ippool.yaml
├── cilium-minimal.yaml
├── cilium-network-policies-examples.yaml
├── cilium-values-minimal.yaml
├── cilium-values.yaml
├── cilium.yaml
├── dns_admin.yaml
├── gateway-api-crds.yaml
├── gateway-api-examples.yaml
├── grafana-hubble-dashboard-configmap.yaml
├── headlamp-token.yaml
├── headlamp.yaml
├── ingress.yaml
├── jenkins.yaml
├── loki.yaml
├── longhorn-grafana-dashboard.yaml
├── longhorn-namespace.yaml
├── longhorn-recurring-jobs.yaml
├── longhorn-storage-classes.yaml
├── longhorn-values-minimal.yaml
├── longhorn-values.yaml
├── longhorn.yaml
├── metallb.yaml
├── minio.yaml
├── namespaces.yaml
├── openebs.yaml
├── portainer-ingress.yaml
├── portainer-traefik-ingress.yaml
├── portainer.yaml
├── prometheus-grafana.yaml
├── rook-ceph-cluster-values.yaml
├── rook-ceph-cluster.yaml
├── rook-ceph-operator-values.yaml
├── rook-ceph-operator.yaml
└── traefik-ingressroutes.yaml
Real talk:
- Finding related files? Good luck.
- Understanding dependencies? Unclear.
- Enabling/disabling components? Confusing.
- New team member onboarding? Nightmare.
The Solution: Organized Component Groups
Here's what I built:
talos/manifests/
├── 00-namespaces/ ← Deploy 1st
├── 10-networking/ ← Cilium, Traefik
├── 20-security/ ← cert-manager, policies
├── 30-storage/ ← Longhorn, MinIO, OpenEBS
├── 40-observability/ ← Prometheus, Grafana, Loki
├── 50-management/ ← Portainer, Headlamp
├── 60-gitops/ ← ArgoCD, Jenkins
└── 70-loadbalancing/ ← MetalLB
Benefits immediately visible:
✅ Related files grouped together
✅ Deployment order clear (00 → 70)
✅ Easy to find what you need
✅ Component dependencies obvious
The Impact: Before vs After
BEFORE
💥 Pain Points:
• 45 files in one directory
• No clear structure
• Hard to find components
• Unclear dependencies
• Confusing Terraform config
• New team members lost
• "Where's the Longhorn config?"
AFTER
✨ Improvements:
✅ 8 organized component groups
✅ Clear naming scheme (00-* through 70-*)
✅ Dependency order built-in
✅ Component READMEs with guides
✅ Easy to enable/disable
✅ New team members productive in minutes
✅ "Longhorn? Check 30-storage/longhorn/"
Deployment Order & Dependencies
START
↓
[00-namespaces] ← Creates namespaces
↓
[10-networking] ← Cilium, Traefik
↓
[20-security] ← cert-manager, policies
↓
[30-storage] ← Longhorn, MinIO, OpenEBS
↓
[40-observability] ← Prometheus, Grafana, Loki
↓
[50-management] ← Portainer, Headlamp
↓
[60-gitops] ← ArgoCD, Jenkins
↓
[70-loadbalancing] ← MetalLB
↓
END
Smart Part: Terraform automatically respects this order because of the numeric prefixes!
Real-World Example: Finding & Enabling Longhorn
BEFORE (Confusing)
$ grep -r "longhorn" .
# 15 results scattered everywhere
# Which one is the main one?
# Are there dependencies?
# Where's the config?
AFTER (Clear)
$ ls talos/manifests/30-storage/longhorn/
longhorn.yaml
longhorn-namespace.yaml
longhorn-values.yaml
longhorn-storage-classes.yaml
longhorn-recurring-jobs.yaml
longhorn-grafana-dashboard.yaml
README.md
To enable Longhorn:
# Edit talos/main.tf
longhorn = "manifests/30-storage/longhorn/longhorn.yaml"
# Deploy
tofu apply
Crystal clear!
The Numbers
What I reorganized:
| Metric | Value |
|---|---|
| Files Reorganized | 45 manifests |
| Component Groups | 8 organized groups |
| Documentation Created | 21 files |
| Lines of Docs | 10,000+ |
| Components Documented | 14 |
| Environments Configured | 4 (local/dev/staging/prod) |
| Time Saved (Long-term) | Hours per month |
Key Learnings
1. Naming Matters
Numeric prefixes (00-, 10-, etc.) enforce deployment order naturally.
2. Documentation is Everything
Each component group has a README explaining what's included, when to use it, how to enable/disable, and common issues.
3. Dependencies Should Be Obvious
By looking at the folder structure, you know what depends on what, what can run independently, and what order to deploy in.
4. Multi-Environment is Essential
Having local/dev/staging/prod configs lets teams test safely, promote changes gradually, and learn without risk.
5. Enable/Disable Should Be Simple
One line in Terraform = deploy or remove a component
# To enable: uncomment
longhorn = "manifests/30-storage/longhorn/longhorn.yaml"
# To disable: comment
# longhorn = "manifests/30-storage/longhorn/longhorn.yaml"
Try It Yourself
My complete reorganized GitOps repo is open source:
You'll find:
- Completely organized manifests
- Multi-environment setup
- 10,000+ lines of clear documentation
- Component status matrix
- Quick start guides
- Real examples
What's Next?
I'm working on Phase 2:
- App Deployment Scaffold - Deploy new apps in 30 seconds
-
Makefile Automation - Common commands via
make - Local Dev Environment - 5-minute Kind cluster setup
- Troubleshooting Runbooks - Self-service operations guide
Check out the GitHub Issues to see what's coming!
The Bottom Line
Organization matters. Especially at scale.
Taking time to organize your infrastructure code:
- Saves hours long-term
- Makes team onboarding faster
- Reduces confusion & errors
- Makes GitOps actually work
- Improves code quality
If you're managing Kubernetes manifests, take a weekend to reorganize. Your future self will thank you. 🚀
Questions?
- How would you organize these manifests differently?
- What's your biggest pain point with Kubernetes management?
- Want help reorganizing your own repo?
Drop a comment below! 👇
Connect with me on GitHub: @beltagyy
Star the repo if you found this helpful! ⭐
Top comments (0)