Forte/launchpad
6
0
Fork 0
Code Issues Pull Requests Actions Packages Wiki Activity
Files
723072bd1e23449d0778d311e46b5498024be38c
launchpad/docs/README.md
Danijel Simeunovic 03a0d7c9ae
Some checks failed
Deploy Gitea Pages / build-and-deploy (push) Failing after 5s
Details
feature/multicluster 
Co-authored-by: Danijel Simeunovic <danijel.simeunovic@trumf.no>
Reviewed-on: #4
Reviewed-by: gitea_admin <admin@forteapps.net>
2026-04-18 18:14:00 +00:00

328 lines
14 KiB
Markdown
Raw Blame History

# 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: upc-dev, upc-prod) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 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 (multi-cluster: upc-dev, upc-prod)
- **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! 🚀**
Reference in New Issue View Git Blame Copy Permalink