Skip to content

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

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

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

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

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 to understand the system
  2. Follow Developer Guide - Prerequisites to set up your environment
  3. Deploy your first application using Deploying Your First Application

For Platform Engineers

  1. Understand the architecture in GitOps Architecture
  2. Learn cluster bootstrap in Operations Runbook - Cluster Bootstrap
  3. Review Day-to-Day Operations procedures

For Troubleshooting

  1. Check Developer Guide - Troubleshooting for common developer issues
  2. Check Operations Runbook - Troubleshooting for operational issues
  3. Consult Technical Reference 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
  2. GitOps Architecture - GitOps Workflow
  3. Developer Guide - Understanding the Workflow
  4. Developer Guide - Deploying Your First Application
  5. Developer Guide - Troubleshooting

Path 2: Experienced Developer (Has K8s Experience)

  1. GitOps Architecture - Repository Structure
  2. Developer Guide - Local Development Setup
  3. Developer Guide - Deploying Your First Application
  4. Technical Reference - Helm Chart Reference

Path 3: Platform Engineer / SRE

  1. GitOps Architecture (entire document)
  2. Operations Runbook - Cluster Bootstrap
  3. Operations Runbook - Day-to-Day Operations
  4. Operations Runbook - Troubleshooting
  5. Technical Reference (as needed)

Path 4: Quick Reference

  1. Developer Guide - Quick Reference
  2. Technical Reference - Configuration Reference
  3. Technical Reference - Glossary

🔍 Finding Information

How do I...?

Task Documentation
Deploy a new application Developer Guide - Deploying Your First Application
Update an existing application Developer Guide - Updating an Existing Application
Create and seal secrets Developer Guide - Working with Secrets
Troubleshoot deployment issues Developer Guide - Troubleshooting
Bootstrap a new cluster Operations Runbook - Cluster Bootstrap
Scale an application Operations Runbook - Scaling Applications
Roll back a deployment Operations Runbook - Rolling Back Deployments
Manage monitoring Operations Runbook - Monitoring & Alerting
Understand ArgoCD config Technical Reference - ArgoCD Configuration
Look up Helm values Technical Reference - Helm Chart Reference
Find component versions Technical Reference - 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

# 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

# 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
  2. Troubleshooting: Developer Guide - Troubleshooting or Operations Runbook - Troubleshooting
  3. Technical Details: Technical Reference
  4. Architecture Context: GitOps Architecture

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:

Welcome to the team! 🚀