Kubernetes Deployment Manager

Professional-grade progressive deployment management for Kubernetes environments

A comprehensive, enterprise-ready platform for managing safe, controlled software deployments across Kubernetes clusters with real-time monitoring, multiple rollout strategies, and instant rollback capabilities.

🏗️ Architecture Overview

graph TB
    subgraph "External Clients"
        CLI[CLI Tool<br/>cli/client.py]
        WebUI[Web Dashboard<br/>dashboard/ota_dashboard.py]
        API_Client[External API Client<br/>CI/CD Systems]
    end
    
    subgraph "Core Platform"
        API[FastAPI Backend<br/>backend/main.py<br/>Port: 8000]
        JobRunner[Job Runner<br/>cli/job_runner.py<br/>Background Processing]
        DB[(SQLite Database<br/>deployment.db)]
    end
    
    subgraph "Kubernetes Cluster"
        K8S_API[Kubernetes API Server]
        Pods[Application Pods<br/>k8s/application.yaml]
        Services[Services & Deployments<br/>k8s/deployment.yaml]
    end
    
    subgraph "Monitoring & Metrics"
        Prometheus[Prometheus Server<br/>Port: 9090]
        Grafana[Grafana Dashboard<br/>Port: 3000]
        Metrics[Metrics Endpoint<br/>/metrics]
        Logs[Application Logs<br/>Structured Logging]
    end
    
    %% Client connections
    CLI -->|HTTP Requests| API
    WebUI -->|Streamlit Server| API
    API_Client -->|REST API| API
    
    %% Core platform flow
    API -->|Job Queue| DB
    DB -->|Pending Jobs| JobRunner
    JobRunner -->|kubectl Operations| K8S_API
    
    %% Kubernetes operations
    K8S_API -->|Manage| Pods
    K8S_API -->|Deploy| Services
    
    %% Monitoring flow
    API -->|Expose| Metrics
    Metrics -->|Scrape| Prometheus
    Prometheus -->|Data Source| Grafana
    JobRunner -->|Generate| Logs
    K8S_API -->|Status Updates| JobRunner
    
    %% Deployment strategies
    JobRunner -.->|Canary<br/>1 Pod| Pods
    JobRunner -.->|Blue<br/>Subset| Pods
    JobRunner -.->|Green<br/>All Pods| Pods
    
    %% Rollback flow
    JobRunner -.->|Rollback<br/>Previous Version| Pods
    
    style CLI fill:#e1f5fe
    style WebUI fill:#e8f5e8
    style API fill:#fff3e0
    style JobRunner fill:#fce4ec
    style K8S_API fill:#f3e5f5
    style Prometheus fill:#e0f2f1

🎯 Why Choose Kubernetes Deployment Manager?

For DevOps Teams:

Reduce deployment risks with progressive rollout strategies
Gain instant visibility into deployment status across all environments
Automate complex deployment workflows with simple CLI commands
Integrate seamlessly with existing CI/CD pipelines

For Platform Engineers:

Enterprise-grade observability with Prometheus metrics
Kubernetes-native integration with no external dependencies
Scalable architecture supporting clusters of any size
Production-tested rollback mechanisms for instant recovery

For Development Teams:

Simple, intuitive interface for deployment management
Real-time dashboard for monitoring application health
Consistent deployment processes across all environments
Reduced time-to-production with automated workflows

✨ Key Features

🚀 Progressive Deployment Strategies

Canary: Test with minimal risk (1 pod)
Blue: Controlled subset rollout (configurable)
Green: Full cluster deployment
Custom: Define your own deployment patterns

🔄 Instant Rollback

One-command rollback to any previous version
Granular rollback control (canary, blue, green scopes)
Automated failure detection and recovery
Zero-downtime rollback operations

📊 Enterprise Observability

Prometheus-compatible metrics out of the box
Real-time deployment status tracking
Comprehensive logging and audit trails
Grafana dashboard templates included

🎛️ Multiple Interfaces

CLI: Perfect for CI/CD integration and automation
Web Dashboard: Visual monitoring and management
REST API: Programmatic access for custom integrations
Kubernetes Native: Direct kubectl compatibility

🚀 Quick Start

Prerequisites

Kubernetes cluster (v1.20+)
Python 3.8+
kubectl configured and connected
Docker (for containerized deployment)

1. Installation

Option A: Quick Setup (Recommended)

# Clone the repository
git clone https://github.com/sylvester-francis/ota-deploy-tracker.git
cd ota-deploy-tracker

# Install dependencies
pip install -r requirements.txt

# Deploy sample applications with logging
kubectl apply -f k8s/application.yaml

# Start the system
docker-compose up -d

Option B: Local Development

# Clone and setup virtual environment
git clone https://github.com/sylvester-francis/ota-deploy-tracker.git
cd ota-deploy-tracker
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Start components separately
uvicorn backend.main:app --reload &
streamlit run dashboard/ota_dashboard.py &
python -m cli.job_runner &

2. Access Your Dashboard

Web Dashboard: http://localhost:8501
API Documentation: http://localhost:8000/docs
Metrics Endpoint: http://localhost:8000/metrics

3. Start Monitoring (Optional)

# Launch Prometheus + Grafana monitoring stack
./start-monitoring.sh

# Access monitoring:
# - Prometheus: http://localhost:9090
# - Grafana: http://localhost:3000 (admin/admin)

4. Your First Deployment

# Deploy version 2.0.0 using canary strategy
python -m cli.client deploy 2.0.0 --wave canary

# Monitor deployment status
python -m cli.client list

# Scale to blue wave (partial rollout)
python -m cli.client deploy 2.0.0 --wave blue

# Full deployment
python -m cli.client deploy 2.0.0 --wave green

# Rollback if needed
python -m cli.client rollback 1.0.0 --wave green

💻 Usage Examples

CLI Operations

# Deployment Management
python -m cli.client deploy 3.1.4 --wave canary    # Canary deployment
python -m cli.client deploy 3.1.4 --wave blue      # Partial rollout
python -m cli.client deploy 3.1.4 --wave green     # Full deployment

# Monitoring
python -m cli.client list                           # List all jobs

# Rollback Operations
python -m cli.client rollback 3.1.3 --wave canary  # Canary rollback
python -m cli.client rollback 3.1.3 --wave green   # Full rollback

# Direct Pod Updates (Advanced)
python -m cli.client update 3.1.4 --wave blue      # Direct update

Docker Operations

# Production deployment
docker-compose up -d

# View logs
docker-compose logs -f api
docker-compose logs -f dashboard
docker-compose logs -f job-runner

# Execute CLI commands
docker-compose exec api python -m cli.client deploy 1.5.0 --wave canary
docker-compose exec api python -m cli.client list
docker-compose exec api python -m cli.client rollback 1.4.0

# Scale services
docker-compose up -d --scale job-runner=3

🧪 Development & Testing

Running Tests

# Install test dependencies
pip install pytest pytest-cov

# Run all tests
pytest

# Run with coverage
pytest --cov=backend --cov=cli --cov=dashboard --cov-report=html

# Run specific test categories
pytest tests/test_api.py          # API tests
pytest tests/test_cli.py          # CLI tests
pytest tests/test_job_runner.py   # Job runner tests

Code Quality

# Linting and formatting
ruff check --fix backend/ cli/ dashboard/ tests/
ruff format backend/ cli/ dashboard/ tests/

🧪 Sample Applications

The platform includes sample applications (app-1 and app-2) that demonstrate deployment management capabilities:

Application Features

Realistic Logging: Continuous application logs with startup sequences and health checks
Simulated Metrics: Random memory usage and connection statistics
Version Tracking: Applications tagged with sw_version labels for deployment tracking
Health Monitoring: Periodic health check logs every 30 seconds

Sample Log Output

Mon Jun 16 06:23:20 UTC 2025 [INFO] Application app-1 starting up...
Mon Jun 16 06:23:20 UTC 2025 [INFO] Loading configuration for version 1.0.0
Mon Jun 16 06:23:20 UTC 2025 [INFO] Database connection established
Mon Jun 16 06:23:20 UTC 2025 [INFO] Server listening on port 8080
Mon Jun 16 06:23:20 UTC 2025 [INFO] Application ready to serve requests
Mon Jun 16 06:23:20 UTC 2025 [INFO] Health check passed - app-1 running normally
Mon Jun 16 06:23:20 UTC 2025 [DEBUG] Memory usage: 73MB
Mon Jun 16 06:23:20 UTC 2025 [DEBUG] Active connections: 5

Dashboard Features

Real-time Pod Status: View current application versions and status
Log Streaming: Access live application logs through the web interface
Auto-refresh: Optional 30-second auto-refresh for real-time monitoring
Manual Refresh: Instant updates with the refresh button

📊 Monitoring & Observability

Quick Start Monitoring Stack

Launch the complete monitoring solution with one command:

# Start Prometheus + Grafana
./start-monitoring.sh

# Access URLs:
# - Prometheus UI: http://localhost:9090
# - Grafana Dashboard: http://localhost:3000 (admin/admin)
# - Raw Metrics: http://localhost:8000/metrics

Prometheus Metrics

The platform exports comprehensive metrics for monitoring:

# Deployment Metrics
ota_updated_pods_total                    # Total pods updated
ota_last_run_timestamp_seconds           # Last deployment timestamp
ota_jobs_pending                         # Pending deployment jobs
ota_jobs_successful                      # Successful deployments
ota_jobs_total                          # Total deployment jobs

# Rollback Metrics
ota_rollback_pods_total                  # Total pods rolled back
ota_last_rollback_timestamp_seconds     # Last rollback timestamp

Grafana Dashboard

Pre-configured dashboard includes:

📈 Real-time Metrics: Live deployment statistics and trends
📊 Visual Charts: Deployment timeline and rollback activity
🎯 Key Performance Indicators: Success rates and system health
⏰ Historical Data: Track deployment patterns over time

Manual Monitoring Setup

# Start monitoring stack manually
cd monitoring
docker-compose -f docker-compose.monitoring.yml up -d

# Stop monitoring stack
docker-compose -f docker-compose.monitoring.yml down

# View raw metrics
curl http://localhost:8000/metrics

Custom Queries

Example Prometheus queries for advanced monitoring:

# Deployment success rate
(ota_jobs_successful / ota_jobs_total) * 100

# Average deployment frequency (per hour)
rate(ota_jobs_total[1h]) * 3600

# Time since last deployment
time() - ota_last_run_timestamp_seconds

# Rollback frequency
rate(ota_rollback_pods_total[24h])

📄 API Reference

Deployment Endpoints

Method	Endpoint	Description
`POST`	`/ota/deploy`	Create new deployment
`GET`	`/ota/jobs`	List all jobs
`POST`	`/ota/update_status`	Update job status
`POST`	`/ota/rollback`	Trigger rollback
`GET`	`/metrics`	Prometheus metrics

CLI Commands

# Deployment commands
cli.client deploy <version> [--wave <wave>]
cli.client update <version> [--wave <wave>]
cli.client rollback <version> [--wave <wave>]
cli.client list

# Management commands
cli.job_runner                    # Start job runner

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and add tests
Run the test suite: pytest
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

📝 License

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

🙏 Acknowledgments

Kubernetes community for the robust container orchestration platform
FastAPI team for the excellent Python web framework
Streamlit team for the intuitive dashboard framework
Contributors and users who make this project better

🤝 Connect & Follow

Ready to collaborate or learn more about cutting-edge tech solutions?

Let's build the future of deployment management together!

Ready to transform your deployment process? Get started now and experience professional-grade Kubernetes deployment management!

Name		Name	Last commit message	Last commit date
Latest commit History 41 Commits
.github		.github
backend		backend
cli		cli
dashboard		dashboard
k8s		k8s
monitoring		monitoring
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
Dockerfile.api		Dockerfile.api
Dockerfile.dashboard		Dockerfile.dashboard
Dockerfile.job-runner		Dockerfile.job-runner
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
metrics.txt		metrics.txt
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
start-monitoring.sh		start-monitoring.sh

License

sylvester-francis/ota-deploy-tracker

Folders and files

Latest commit

History

Repository files navigation