docs

2026-03-16 11:00:42 +01:00
parent 275c100af5
commit d02da33700
6 changed files with 4766 additions and 109 deletions
--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,327 @@
+# Kubernetes Cluster Documentation
+
+Welcome to the comprehensive documentation for our Kubernetes cluster GitOps setup. This documentation covers architecture, development workflows, operations, and technical references.
+
+## 📚 Documentation Index
+
+### 1. [GitOps Architecture & Repository Guide](GITOPS-ARCHITECTURE.md)
+**Start here to understand the system**
+
+Learn about:
+- Overall architecture and design decisions
+- Repository structure and relationships
+- GitOps workflow and deployment patterns
+- CI/CD pipeline integration
+- Security model and best practices
+
+**Best for**: Understanding how everything fits together, architectural decisions, and the big picture.
+
+---
+
+### 2. [Developer Onboarding Guide](DEVELOPER-GUIDE.md)
+**For developers deploying and maintaining applications**
+
+Learn how to:
+- Set up your local development environment
+- Deploy your first application
+- Update existing applications
+- Manage secrets securely
+- Troubleshoot common issues
+- Follow development best practices
+
+**Best for**: New developers joining the team, deploying applications, day-to-day development workflows.
+
+---
+
+### 3. [Operations Runbook](OPERATIONS-RUNBOOK.md)
+**For platform engineers and operators**
+
+Learn how to:
+- Bootstrap a new cluster
+- Monitor and maintain applications
+- Manage infrastructure components
+- Handle secrets and credentials
+- Troubleshoot production issues
+- Perform disaster recovery
+- Execute maintenance procedures
+
+**Best for**: Platform team members, SRE tasks, incident response, cluster maintenance.
+
+---
+
+### 4. [Technical Reference](REFERENCE.md)
+**Detailed technical specifications**
+
+Reference for:
+- Component specifications and versions
+- Helm chart templates and values
+- ArgoCD configuration options
+- Kyverno policy definitions
+- API endpoints and interfaces
+- Configuration schemas
+- Complete glossary
+
+**Best for**: Looking up specific configuration options, understanding component details, API references.
+
+---
+
+## 🚀 Quick Start
+
+### For New Developers
+1. Read [GitOps Architecture](GITOPS-ARCHITECTURE.md#overview) to understand the system
+2. Follow [Developer Guide - Prerequisites](DEVELOPER-GUIDE.md#prerequisites) to set up your environment
+3. Deploy your first application using [Deploying Your First Application](DEVELOPER-GUIDE.md#deploying-your-first-application)
+
+### For Platform Engineers
+1. Understand the architecture in [GitOps Architecture](GITOPS-ARCHITECTURE.md)
+2. Learn cluster bootstrap in [Operations Runbook - Cluster Bootstrap](OPERATIONS-RUNBOOK.md#cluster-bootstrap)
+3. Review [Day-to-Day Operations](OPERATIONS-RUNBOOK.md#day-to-day-operations) procedures
+
+### For Troubleshooting
+1. Check [Developer Guide - Troubleshooting](DEVELOPER-GUIDE.md#troubleshooting) for common developer issues
+2. Check [Operations Runbook - Troubleshooting](OPERATIONS-RUNBOOK.md#troubleshooting) for operational issues
+3. Consult [Technical Reference](REFERENCE.md) for configuration details
+
+---
+
+## 🗺️ Documentation Map
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    GITOPS ARCHITECTURE                      │
+│  (System Overview, Repositories, Workflows, Security)       │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                ┌───────────┴───────────┐
+                │                       │
+                ▼                       ▼
+    ┌──────────────────┐    ┌──────────────────────┐
+    │ DEVELOPER GUIDE  │    │ OPERATIONS RUNBOOK   │
+    │ (Development)    │    │ (Operations)         │
+    └──────────────────┘    └──────────────────────┘
+                │                       │
+                └───────────┬───────────┘
+                            ▼
+                 ┌────────────────────┐
+                 │ TECHNICAL REFERENCE│
+                 │ (Specifications)   │
+                 └────────────────────┘
+```
+
+---
+
+## 📖 Reading Paths
+
+### Path 1: New Developer (No K8s Experience)
+1. [GitOps Architecture - Overview](GITOPS-ARCHITECTURE.md#overview)
+2. [GitOps Architecture - GitOps Workflow](GITOPS-ARCHITECTURE.md#gitops-workflow)
+3. [Developer Guide - Understanding the Workflow](DEVELOPER-GUIDE.md#understanding-the-workflow)
+4. [Developer Guide - Deploying Your First Application](DEVELOPER-GUIDE.md#deploying-your-first-application)
+5. [Developer Guide - Troubleshooting](DEVELOPER-GUIDE.md#troubleshooting)
+
+### Path 2: Experienced Developer (Has K8s Experience)
+1. [GitOps Architecture - Repository Structure](GITOPS-ARCHITECTURE.md#repository-structure)
+2. [Developer Guide - Local Development Setup](DEVELOPER-GUIDE.md#local-development-setup)
+3. [Developer Guide - Deploying Your First Application](DEVELOPER-GUIDE.md#deploying-your-first-application)
+4. [Technical Reference - Helm Chart Reference](REFERENCE.md#helm-chart-reference)
+
+### Path 3: Platform Engineer / SRE
+1. [GitOps Architecture](GITOPS-ARCHITECTURE.md) (entire document)
+2. [Operations Runbook - Cluster Bootstrap](OPERATIONS-RUNBOOK.md#cluster-bootstrap)
+3. [Operations Runbook - Day-to-Day Operations](OPERATIONS-RUNBOOK.md#day-to-day-operations)
+4. [Operations Runbook - Troubleshooting](OPERATIONS-RUNBOOK.md#troubleshooting)
+5. [Technical Reference](REFERENCE.md) (as needed)
+
+### Path 4: Quick Reference
+1. [Developer Guide - Quick Reference](DEVELOPER-GUIDE.md#quick-reference)
+2. [Technical Reference - Configuration Reference](REFERENCE.md#configuration-reference)
+3. [Technical Reference - Glossary](REFERENCE.md#glossary)
+
+---
+
+## 🔍 Finding Information
+
+### How do I...?
+
+| Task | Documentation |
+|------|---------------|
+| **Deploy a new application** | [Developer Guide - Deploying Your First Application](DEVELOPER-GUIDE.md#deploying-your-first-application) |
+| **Update an existing application** | [Developer Guide - Updating an Existing Application](DEVELOPER-GUIDE.md#updating-an-existing-application) |
+| **Create and seal secrets** | [Developer Guide - Working with Secrets](DEVELOPER-GUIDE.md#working-with-secrets) |
+| **Troubleshoot deployment issues** | [Developer Guide - Troubleshooting](DEVELOPER-GUIDE.md#troubleshooting) |
+| **Bootstrap a new cluster** | [Operations Runbook - Cluster Bootstrap](OPERATIONS-RUNBOOK.md#cluster-bootstrap) |
+| **Scale an application** | [Operations Runbook - Scaling Applications](OPERATIONS-RUNBOOK.md#scaling-applications) |
+| **Roll back a deployment** | [Operations Runbook - Rolling Back Deployments](OPERATIONS-RUNBOOK.md#rolling-back-deployments) |
+| **Manage monitoring** | [Operations Runbook - Monitoring & Alerting](OPERATIONS-RUNBOOK.md#monitoring--alerting) |
+| **Understand ArgoCD config** | [Technical Reference - ArgoCD Configuration](REFERENCE.md#argocd-configuration) |
+| **Look up Helm values** | [Technical Reference - Helm Chart Reference](REFERENCE.md#helm-chart-reference) |
+| **Find component versions** | [Technical Reference - Version Matrix](REFERENCE.md#version-matrix) |
+
+---
+
+## 📊 System Overview
+
+### Cluster Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                      GitHub Repositories                      │
+│  ┌────────────┐  ┌────────────┐  ┌────────────────────────┐  │
+│  │   Config   │  │   Charts   │  │   Values               │  │
+│  │  (ArgoCD)  │  │ (Templates)│  │ (Environment Config)   │  │
+│  └────────────┘  └────────────┘  └────────────────────────┘  │
+└──────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌──────────────────────────────────────────────────────────────┐
+│                   ArgoCD (GitOps Engine)                      │
+│                    Sync every 60 seconds                      │
+└──────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌──────────────────────────────────────────────────────────────┐
+│               Kubernetes Cluster (UpCloud)                    │
+│  ┌──────────────────────────────────────────────────────┐    │
+│  │  Infrastructure: Traefik, Cert-Manager, Kyverno     │    │
+│  ├──────────────────────────────────────────────────────┤    │
+│  │  Monitoring: Prometheus, Grafana, Loki, Fluent-Bit  │    │
+│  ├──────────────────────────────────────────────────────┤    │
+│  │  Applications: mcp10x, musicman, dot-ai-stack       │    │
+│  └──────────────────────────────────────────────────────┘    │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### Key Technologies
+
+- **GitOps**: ArgoCD
+- **Kubernetes**: UpCloud Managed Kubernetes
+- **Ingress**: Traefik v2
+- **Certificates**: Cert-Manager + Let's Encrypt
+- **Policies**: Kyverno
+- **Secrets**: Sealed Secrets
+- **Monitoring**: Prometheus + Grafana
+- **Logging**: Loki + Fluent-Bit
+
+---
+
+## 🛠️ Common Tasks
+
+### Development Tasks
+
+```bash
+# Deploy new application
+cd ~/dev/k8s/launchpad
+# Create apps/myapp.yaml and helm-prod-values/myapp/values.yaml
+git add apps/myapp.yaml
+git commit -m "Add myapp"
+git push
+
+# Update application
+cd ~/dev/k8s/helm-prod-values
+vim myapp/values.yaml
+git commit -am "Update myapp config"
+git push
+
+# Create secret
+kubeseal --format=yaml --cert=pub-cert.pem \
+  < private/secret.yaml > secrets/secret-sealed.yaml
+git add secrets/secret-sealed.yaml
+git push
+```
+
+### Operations Tasks
+
+```bash
+# Check application status
+kubectl get applications -n argocd
+
+# View application details
+kubectl describe application myapp -n argocd
+
+# Force sync
+kubectl patch application myapp -n argocd \
+  --type merge -p '{"metadata":{"annotations":{"argocd.argoproj.io/refresh":"hard"}}}'
+
+# Check pod logs
+kubectl logs -n myapp <pod-name>
+
+# Restart deployment
+kubectl rollout restart deployment myapp -n myapp
+```
+
+---
+
+## 🆘 Getting Help
+
+### Documentation Search Order
+
+1. **Quick Reference**: [Developer Guide - Quick Reference](DEVELOPER-GUIDE.md#quick-reference)
+2. **Troubleshooting**: [Developer Guide - Troubleshooting](DEVELOPER-GUIDE.md#troubleshooting) or [Operations Runbook - Troubleshooting](OPERATIONS-RUNBOOK.md#troubleshooting)
+3. **Technical Details**: [Technical Reference](REFERENCE.md)
+4. **Architecture Context**: [GitOps Architecture](GITOPS-ARCHITECTURE.md)
+
+### Support Channels
+
+- **Slack**: #platform-support
+- **Issues**: Platform team
+- **Emergencies**: Escalate via Slack
+
+---
+
+## 📝 Document Maintenance
+
+### Updating Documentation
+
+If you find:
+- Outdated information
+- Missing procedures
+- Errors or typos
+- Areas needing clarification
+
+Please:
+1. Create an issue or PR in the repository
+2. Notify the platform team
+3. Update the relevant documentation file
+
+### Documentation Structure
+
+```
+docs/
+├── README.md                    # This file (index)
+├── GITOPS-ARCHITECTURE.md       # Architecture overview
+├── DEVELOPER-GUIDE.md           # Developer workflows
+├── OPERATIONS-RUNBOOK.md        # Operations procedures
+└── REFERENCE.md                 # Technical specifications
+```
+
+---
+
+## 🔄 Documentation Versions
+
+**Current Version**: 1.0.0
+**Last Updated**: 2026-03-16
+**Maintained By**: Platform Team
+
+### Changelog
+
+- **v1.0.0 (2026-03-16)**: Initial comprehensive documentation release
+  - GitOps Architecture guide
+  - Developer Onboarding guide
+  - Operations Runbook
+  - Technical Reference
+  - Documentation index
+
+---
+
+## 🎯 Next Steps
+
+Choose your path:
+
+- 👨‍💻 **New Developer?** Start with [Developer Guide](DEVELOPER-GUIDE.md)
+- 🔧 **Platform Engineer?** Read [Operations Runbook](OPERATIONS-RUNBOOK.md)
+- 🏗️ **Architect?** Explore [GitOps Architecture](GITOPS-ARCHITECTURE.md)
+- 🔍 **Need Details?** Check [Technical Reference](REFERENCE.md)
+
+---
+
+**Welcome to the team! 🚀**