# 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 Clusters (UpCloud, AWS, Azure, GCP)       │
│  ┌──────────────────────────────────────────────────────┐    │
│  │  Infrastructure: Traefik, Cert-Manager, Kyverno     │    │
│  ├──────────────────────────────────────────────────────┤    │
│  │  Monitoring: Prometheus, Grafana, Loki, Fluent-Bit  │    │
│  ├──────────────────────────────────────────────────────┤    │
│  │  Applications: mcp10x, musicman, dot-ai-stack       │    │
│  └──────────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────────────┘
```

### Key Technologies

- **GitOps**: ArgoCD
- **Kubernetes**: Multi-cloud (UpCloud, AWS EKS, Azure AKS, GCP GKE)
- **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-04-22
**Maintained By**: Platform Team

### Changelog

- **v1.1.0 (2026-04-22)**: Multi-cloud support
  - Cloud-agnostic base values (storage, LB, pricing moved to per-cluster overlays)
  - Added AWS EKS, Azure AKS, GCP GKE configurations
  - Per-cloud backup scripts
  - Updated all documentation
- **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! 🚀**