🚀 Kubernetes GitOps Lab

A comprehensive hands-on laboratory for learning GitOps, Kubernetes, and DevOps best practices using a real-world TODO application. This project demonstrates modern cloud-native development workflows with automated CI/CD, infrastructure as code, and declarative deployment strategies.

📖 Table of Contents

• Overview
• Architecture
• Features
• Prerequisites
• Quick Start
• Project Structure
• GitOps Workflow
• Demo Scenarios
• Technology Stack
• Learning Path
• Troubleshooting
• Contributing
• Resources

🌟 Overview

This project implements a production-ready GitOps workflow using a simple TODO application to demonstrate:

• Cloud-native development with containerized microservices
• GitOps principles with ArgoCD for automated deployments
• Multi-environment management (development, staging)
• Security-first approach with sealed secrets and vulnerability scanning
• Observability with metrics, health checks, and monitoring
• Scalability with Horizontal Pod Autoscaler (HPA)
• Infrastructure as Code with Helm charts and Kubernetes manifests

What You'll Learn

✅ GitOps Fundamentals - Declarative, Git-driven operations
✅ Kubernetes Orchestration - Container deployment and management
✅ CI/CD Automation - Automated testing, building, and deployment
✅ Security Best Practices - Secret management and vulnerability scanning
✅ Monitoring & Observability - Metrics collection and health monitoring
✅ Infrastructure as Code - Reproducible infrastructure deployment

🏗️ Architecture

graph TB
    subgraph "Developer Workflow"
        DEV[👨‍💻 Developer] --> GIT[📦 GitHub Repository]
        GIT --> CI[🔄 GitHub Actions]
        CI --> REG[📋 Container Registry]
    end
    
    subgraph "GitOps Workflow"
        GITOPS[📚 GitOps Repository] --> ARGO[🎯 ArgoCD]
        ARGO --> K8S[☸️ Kubernetes Cluster]
    end
    
    subgraph "Kubernetes Cluster (k3d)"
        subgraph "Infrastructure"
            TRAEFIK[🌐 Traefik Ingress]
            METRICS[📊 Metrics Server]
            SEALED[🔐 Sealed Secrets]
        end
        
        subgraph "Applications"
            DEV_ENV[🔧 Development Environment]
            STG_ENV[🚀 Staging Environment]
        end
    end
    
    CI --> ARGO
    REG --> K8S
    TRAEFIK --> DEV_ENV
    TRAEFIK --> STG_ENV

Loading

Key Components

• Application Repository (todo-app/): Node.js/Express REST API with Redis
• GitOps Repository (todo-gitops/): ArgoCD applications and Kubernetes manifests
• Infrastructure: k3d cluster with Traefik, ArgoCD, and monitoring

✨ Features

🎯 Core Application Features

• RESTful TODO API with full CRUD operations
• Redis persistence for data storage
• Health checks and Prometheus metrics
• Input validation and error handling
• Security hardening (non-root containers, read-only filesystem)

🔄 GitOps & CI/CD

• ArgoCD app-of-apps pattern for multi-application management
• Automated deployments to development environment
• Manual approval workflow for staging deployments
• GitHub Actions CI/CD with testing and security scanning
• Dependency management with Renovate Bot

☸️ Kubernetes Features

• Helm charts with environment-specific configurations
• Horizontal Pod Autoscaler (HPA) for automatic scaling
• Ingress routing with Traefik
• ConfigMaps and Secrets management
• Resource limits and security contexts
• Rolling deployments with zero downtime

🔐 Security & Compliance

• Sealed Secrets for encrypted secret management
• Vulnerability scanning with Trivy
• SBOM generation for supply chain security
• Container security best practices
• Network policies ready

📊 Observability

• Prometheus metrics collection
• Health monitoring endpoints
• Resource usage tracking
• Application performance metrics
• Scaling events monitoring

🔧 Prerequisites

System Requirements

Component	Version	Purpose
Docker	20.10+	Container runtime
k3d	5.4+	Local Kubernetes cluster
kubectl	1.25+	Kubernetes CLI
Helm	3.8+	Package manager
Git	2.30+	Version control

Platform Support

• ✅ Linux (Ubuntu 20.04+, Debian 11+)
• ✅ macOS (Intel & Apple Silicon)
• ✅ Windows (WSL2 + Docker Desktop)

Installation Scripts

Choose your platform and run the appropriate setup:

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

Windows (PowerShell):

# Install using Chocolatey
choco install kubernetes-cli helm k3d

# Or use Scoop
scoop install kubectl helm k3d

🚀 Quick Start

1. Clone and Setup

# Clone the repository
git clone <your-repo-url>
cd k8s-gitops-lab

# Navigate to GitOps directory
cd todo-gitops

# Run the bootstrap script
chmod +x bootstrap/setup.sh
./bootstrap/setup.sh

The setup script will:

• ✅ Create a local k3d Kubernetes cluster
• ✅ Install ArgoCD, Traefik, and essential components
• ✅ Configure GitOps applications
• ✅ Set up local development environment

2. Verify Installation

# Check cluster status
kubectl get nodes

# Check ArgoCD applications
kubectl get applications -n argocd

# Check all pods
kubectl get pods -A

3. Access Services

Service	URL	Credentials
ArgoCD UI	https://localhost:30443	admin / (from setup output)
TODO App (Dev)	http://todo-dev.local:8080	None
Kubernetes API	https://localhost:6550	kubectl context

4. Build and Deploy Application

# Navigate to application directory
cd ../todo-app

# Build and push to local registry
docker build -t k3d-registry.localhost:5001/todo-app:latest .
docker push k3d-registry.localhost:5001/todo-app:latest

# ArgoCD will automatically detect and deploy!

📁 Project Structure

k8s-gitops-lab/
├── 📱 todo-app/                    # Application Repository
│   ├── 🐳 Dockerfile              # Multi-stage container build
│   ├── 📦 package.json            # Node.js dependencies
│   ├── 🎯 src/server.js           # Express.js application
│   ├── ⚙️ .github/workflows/      # CI/CD pipelines
│   └── ⛵ charts/todo/            # Helm chart
│       ├── 📋 values.yaml         # Default configuration
│       ├── 🔧 values-dev.yaml     # Development settings
│       ├── 🚀 values-stg.yaml     # Staging settings
│       └── 📄 templates/          # Kubernetes manifests
├── 🔄 todo-gitops/                # GitOps Repository
│   ├── 🎯 app-of-apps.yaml        # ArgoCD app-of-apps
│   ├── 📚 applications/           # ArgoCD app definitions
│   ├── 🌍 environments/           # Environment configurations
│   ├── 🔨 bootstrap/              # Setup scripts
│   └── 📖 docs/                   # Architecture documentation
├── 📋 PROJECT_SUMMARY.md          # Detailed project overview
└── 📖 README.md                   # This file

Repository Purposes

Repository	Purpose	Key Components
todo-app/	Application source code	Source code, Dockerfile, Helm charts, CI/CD
todo-gitops/	GitOps configuration	ArgoCD apps, environment configs, secrets

🔄 GitOps Workflow

Development Flow

sequenceDiagram
    participant Dev as 👨‍💻 Developer
    participant App as 📱 todo-app
    participant CI as 🔄 GitHub Actions
    participant Reg as 📋 Registry
    participant GitOps as 📚 todo-gitops
    participant ArgoCD as 🎯 ArgoCD
    participant K8s as ☸️ Kubernetes

    Dev->>App: 1. Push code changes
    App->>CI: 2. Trigger CI/CD pipeline
    CI->>CI: 3. Run tests & security scans
    CI->>Reg: 4. Build & push container image
    CI->>GitOps: 5. Update image tag (optional)
    GitOps->>ArgoCD: 6. Detect configuration changes
    ArgoCD->>K8s: 7. Deploy to cluster
    K8s-->>Dev: 8. Application updated

Loading

Environment Strategy

Environment	Sync Policy	Purpose	Namespace
Development	Auto-sync	Continuous integration testing	todo-dev
Staging	Manual approval	Pre-production validation	todo-staging
Production	Manual approval	Live application	todo-prod

🎬 Demo Scenarios

Scenario 1: Application Development Cycle

# 1. Make code changes
cd todo-app/src
# Edit server.js

# 2. Build and push
docker build -t k3d-registry.localhost:5001/todo-app:v1.1.0 .
docker push k3d-registry.localhost:5001/todo-app:v1.1.0

# 3. Watch ArgoCD auto-deploy
kubectl get pods -n todo-dev -w

Scenario 2: Autoscaling Demo

# Run the interactive autoscaling demonstration
cd todo-gitops/bootstrap
chmod +x demo.sh
./demo.sh

# Watch HPA in action
kubectl get hpa -n todo-dev -w

Scenario 3: Secret Management

# Create a sealed secret
echo -n 'super-secret-password' | kubeseal --raw \
  --from-file=/dev/stdin \
  --name my-secret \
  --namespace todo-dev

# Deploy via GitOps
git add . && git commit -m "Add new secret" && git push

Scenario 4: Environment Promotion

# Tag stable version
git tag v1.2.0
git push origin v1.2.0

# Update staging environment via ArgoCD UI
# Manual sync staging application

🛠️ Technology Stack

Application Stack

Technology	Purpose	Version
Node.js	Runtime environment	18+
Express.js	Web framework	^4.18
Redis	Data persistence	Alpine
Joi	Input validation	^17.11

Infrastructure Stack

Technology	Purpose	Version
Kubernetes	Container orchestration	1.25+
k3d	Local K8s clusters	5.4+
ArgoCD	GitOps operator	2.8+
Traefik	Ingress controller	Latest
Helm	Package manager	3.8+

DevOps Tools

Tool	Purpose	Integration
GitHub Actions	CI/CD automation	Automated testing, building
Trivy	Vulnerability scanning	Security pipeline
Renovate	Dependency management	Automated updates
Sealed Secrets	Secret encryption	Secure GitOps

📚 Learning Path

Beginner Track (Week 1-2)

1. Setup Environment - Run quick start guide
2. Explore Application - Understand TODO API
3. GitOps Basics - Learn ArgoCD interface
4. Deploy Changes - Make simple code modifications

Intermediate Track (Week 3-4)

1. Helm Customization - Modify chart values
2. Multi-Environment - Deploy to staging
3. Secret Management - Create sealed secrets
4. Monitoring Setup - Configure metrics

Advanced Track (Week 5-6)

1. Security Hardening - Implement policies
2. Custom Operators - Extend functionality
3. Production Setup - Real cluster deployment
4. Disaster Recovery - Backup strategies

🐛 Troubleshooting

Common Issues

🔴 Cluster Creation Fails

# Check Docker status
docker info

# Clean up existing clusters
k3d cluster delete todo-local

# Retry with verbose logging
k3d cluster create todo-local --verbose

🔴 ArgoCD Not Accessible

# Check ArgoCD pods
kubectl get pods -n argocd

# Port forward as backup
kubectl port-forward svc/argocd-server -n argocd 8080:80

🔴 Application Sync Issues

# Force refresh application
argocd app get todo-dev --refresh

# Check application logs
kubectl logs -f deployment/todo -n todo-dev

🔴 Registry Push Fails

# Verify registry is running
docker ps | grep registry

# Test registry connectivity
curl -k http://k3d-registry.localhost:5001/v2/_catalog

Getting Help

1. Check Logs: kubectl logs -f deployment/todo -n todo-dev
2. Describe Resources: kubectl describe pod <pod-name> -n todo-dev
3. ArgoCD Status: argocd app get todo-dev
4. Health Checks: curl http://todo-dev.local:8080/healthz

For detailed troubleshooting, see: todo-gitops/docs/TROUBLESHOOTING.md

🤝 Contributing

We welcome contributions! Here's how to get started:

Development Process

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Test locally using the setup scripts
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

Contribution Areas

• 📚 Documentation improvements
• 🐛 Bug fixes and issue resolution
• ✨ New feature development
• 🔧 Infrastructure enhancements
• 🧪 Additional demo scenarios
• 🔐 Security improvements

Code Standards

• ✅ Follow existing code style
• ✅ Add appropriate tests
• ✅ Update documentation
• ✅ Ensure security best practices

📖 Resources

Official Documentation

• 📘 Kubernetes Documentation
• 📗 ArgoCD Documentation
• 📙 Helm Documentation
• 📕 k3d Documentation

Learning Resources

• 🎓 GitOps Principles
• 📺 CNCF YouTube Channel
• 📚 Kubernetes Learning Path
• 🏆 Certified Kubernetes Administrator (CKA)

Community

• 💬 Kubernetes Slack
• 🐦 CNCF Twitter
• 📝 GitOps Working Group

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Cloud Native Computing Foundation (CNCF) for the amazing ecosystem
• ArgoCD Team for the excellent GitOps platform
• Kubernetes Community for the robust orchestration platform
• All Contributors who helped improve this project

---

⭐ Star this repository if you found it helpful!

Happy GitOps-ing! 🚀