{"id":33235903,"url":"https://github.com/hyb8nate/hyb8nate","last_synced_at":"2025-11-16T18:02:59.399Z","repository":{"id":322216562,"uuid":"1088158282","full_name":"hyb8nate/hyb8nate","owner":"hyb8nate","description":null,"archived":false,"fork":false,"pushed_at":"2025-11-10T15:35:07.000Z","size":2065,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-10T17:26:39.470Z","etag":null,"topics":["devops","finops","hibernation","k8s","kubernetes","python","react","scheduler"],"latest_commit_sha":null,"homepage":"https://hyb8nate.xyz","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyb8nate.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-02T12:38:06.000Z","updated_at":"2025-11-08T17:36:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hyb8nate/hyb8nate","commit_stats":null,"previous_names":["hyb8nate/hyb8nate"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/hyb8nate/hyb8nate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyb8nate%2Fhyb8nate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyb8nate%2Fhyb8nate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyb8nate%2Fhyb8nate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyb8nate%2Fhyb8nate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyb8nate","download_url":"https://codeload.github.com/hyb8nate/hyb8nate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyb8nate%2Fhyb8nate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":284750955,"owners_count":27057456,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-16T02:00:05.974Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["devops","finops","hibernation","k8s","kubernetes","python","react","scheduler"],"created_at":"2025-11-16T18:01:47.517Z","updated_at":"2025-11-16T18:02:59.391Z","avatar_url":"https://github.com/hyb8nate.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv\u003e\n    \u003cdiv style=\"float: left\"\u003e\n        \u003cimg src=\"frontend/public/logos/logo-64.png\" /\u003e\n    \u003c/div\u003e\n    \u003cdiv\u003e\n        \u003ch1\u003e\n          hyb8nate\n        \u003c/h1\u003e\n    \u003c/div\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n![hyb8nate dashboard](doc/screen_dashboard.png)\n\n**Intelligent Kubernetes deployment hibernation scheduler**\n\n[![Build and Push Docker Images](https://github.com/hyb8nate/hyb8nate/actions/workflows/docker-publish.yml/badge.svg)](https://github.com/hyb8nate/hyb8nate/actions/workflows/docker-publish.yml)\n[![Docker Pulls](https://img.shields.io/docker/pulls/hyb8nate/hyb8nate)](https://hub.docker.com/r/hyb8nate/hyb8nate)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)](https://www.typescriptlang.org/)\n\nAll-in-one service to automatically hibernate (scale to 0) your Kubernetes deployments based on time schedules.\n\n[Features](#-features) • [Quick Start](#-quick-start) • [Installation](#-installation) • [Documentation](#-usage)\n\n\u003c/div\u003e\n\n---\n\n\n## 🎯 Overview\n\n**hyb8nate** (pronounced \"hibernate\") is a Kubernetes-native application that automatically scales down your deployments during off-hours and scales them back up when needed. Save resources, reduce costs, and optimize your cluster utilization without manual intervention.\n\nPerfect for:\n\n- 🌙 **Development/staging environments** during night hours\n- 🏖️ **Non-production workloads** during weekends\n- 💰 **Cost optimization** on cloud providers\n- 🔋 **Energy-efficient** cluster management\n\n## ✨ Features\n\n### 🕐 Flexible Scheduling\n\n- **Time-based scaling**: Define custom scale-down and scale-up times (HH:MM format)\n- **Timezone support**: Configure schedules in your local timezone (e.g., `Europe/Paris`, `US/Central`)\n- **Preset templates**: Quick setup with common patterns (night, lunch break, evening)\n- **Minute-precise execution**: Schedules execute at exactly HH:MM:00\n\n### 🔒 Security \u0026 Control\n\n- **Namespace labeling**: Only namespaces with `hyb8nate.xyz/enabled=true` label can be scheduled\n- **Per-deployment control**: Enable/disable schedules individually\n- **Conflict detection**: Prevents duplicate schedules for the same deployment\n- **State restoration**: Automatically restores original replica count\n- **Smart enable/disable**: Scales deployments intelligently when toggling schedules\n\n### 🎨 Modern UI\n\n- **Real-time dashboard**: Monitor all schedules at a glance\n- **Easy management**: Create, edit, and delete schedules with a clean interface\n- **Status tracking**: See which deployments are currently hibernated\n- **Responsive design**: Works on desktop, tablet, and mobile\n\n### 🚀 Production Ready\n\n- **All-in-one deployment**: Single Docker image with backend + frontend\n- **In-cluster execution**: Runs directly in your Kubernetes cluster\n- **SQLite backend**: Simple, reliable, no external database needed\n- **Persistent storage**: Survives pod restarts with PersistentVolume\n- **Health checks**: Built-in liveness and readiness probes\n- **Minimal permissions**: RBAC with least privilege principle\n- **Multi-architecture**: Supports AMD64 and ARM64\n\n### 💤 Automatic snooze labels\n\n- **FluxCD \u0026 ArgoCD**: sync snooze labels added automatically if needed\n\n## 🏗️ Architecture\n\n```\n┌────────────────────────────────────────────────────────┐\n│                    Kubernetes Cluster                  │\n│                                                        │\n│  ┌────────────────────────────────────────────────┐    │\n│  │              hyb8nate Pod                      │    │\n│  │                                                │    │\n│  │  ┌──────────────┐        ┌─────────────────┐   │    │\n│  │  │   FastAPI    │◄──────►│   React SPA     │   │    │\n│  │  │   Backend    │        │   Frontend      │   │    │\n│  │  └──────┬───────┘        └─────────────────┘   │    │\n│  │         │                                      │    │\n│  │         ├─────────► SQLite Database            │    │\n│  │         │            (PersistentVolume)        │    │\n│  │         │                                      │    │\n│  │  ┌──────▼────────┐                             │    │\n│  │  │  Scheduler    │                             │    │\n│  │  │  (APScheduler)│                             │    │\n│  │  └──────┬────────┘                             │    │\n│  └─────────┼──────────────────────────────────────┘    │\n│            │                                           │\n│            ▼                                           │\n│  ┌─────────────────────────────────────────────┐       │\n│  │        Kubernetes API Server                │       │\n│  │  (Scale Deployments via Apps/v1 API)        │       │\n│  └─────────────────────────────────────────────┘       │\n│                                                        │\n└────────────────────────────────────────────────────────┘\n```\n\n**Technology Stack**:\n\n- **Backend**: Python 3.13 + FastAPI + APScheduler\n- **Frontend**: React + TypeScript + Tailwind CSS\n- **Database**: SQLite (embedded, no external DB needed)\n- **Kubernetes Client**: Official Python kubernetes client\n- **Container**: All-in-one Docker image (backend serves static frontend)\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Kubernetes cluster (v1.21+)\n- `kubectl` configured to access your cluster\n- Cluster-admin permissions (for initial RBAC setup)\n\n### 1. Label your namespaces\n\nOnly namespaces with the label `hyb8nate.xyz/enabled=true` can create schedules:\n\n```bash\nkubectl label namespace my-dev-namespace hyb8nate.xyz/enabled=true\nkubectl label namespace my-staging-namespace hyb8nate.xyz/enabled=true\n```\n\n### 2. Deploy hyb8nate\n\n```bash\nkubectl apply -f https://raw.githubusercontent.com/hyb8nate/hyb8nate/main/k8s/all-in-one.yaml\n```\n\n### 3. Access the UI\n\n```bash\n# Port forward to access locally\nkubectl port-forward -n hyb8nate svc/hyb8nate 8000:8000\n```\n\nOpen your browser at: **http://localhost:8000**\n\nDefault login password: `admin` (⚠️ change it via `ADMIN_PASSWORD` environment variable)\n\n### 4. Create your first schedule\n\n1. Select a namespace and deployment\n2. Set scale-down and scale-up times\n3. Click \"Create Schedule\"\n4. Done! Your deployment will automatically hibernate at the scheduled time\n\n## 📦 Installation\n\n### Option 1: All-in-One Manifest (Recommended)\n\nDeploy everything with a single command:\n\n```bash\nkubectl apply -f https://raw.githubusercontent.com/hyb8nate/hyb8nate/main/k8s/all-in-one.yaml\n```\n\nThis creates:\n- `hyb8nate` namespace\n- ServiceAccount with RBAC permissions\n- PersistentVolumeClaim (1Gi for SQLite database)\n- Deployment (all-in-one image)\n- ClusterIP Service\n- (Optional) Ingress\n\n### Option 3: Helm Chart (Coming Soon)\n\n```bash\nhelm repo add hyb8nate https://hyb8nate.github.io/charts\nhelm install hyb8nate hyb8nate/hyb8nate \\\n  --set admin.password=your-secure-password \\\n  --set timezone=Europe/Paris\n```\n\n## ⚙️ Configuration\n\n### Environment Variables\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `ADMIN_PASSWORD` | Admin login password | `admin` | ❌ |\n| `JWT_SECRET_KEY` | Secret key for JWT tokens | Auto-generated | ❌ |\n| `ACCESS_TOKEN_EXPIRE_MINUTES` | JWT token expiration (minutes) | `30` | ❌ |\n| `TIMEZONE` | Timezone for schedules | `Europe/Paris` | ❌ |\n| `LOG_LEVEL` | Logging level (DEBUG, INFO, WARNING, ERROR) | `INFO` | ❌ |\n| `FLUXCD_OPTION` | Snooze label to avoid FluxCD sync | `false` | ❌ |\n| `ARGOCD_OPTION` | Snooze label to avoid ArgoCD sync | `false` | ❌ |\n\n### Example Configuration\n\n```yaml\napiVersion: v1\nkind: Secret\nmetadata:\n  name: hyb8nate-secret\n  namespace: hyb8nate\ntype: Opaque\nstringData:\n  admin-password: \"your-secure-password\"\n---\napiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: hyb8nate-config\n  namespace: hyb8nate\ndata:\n  TIMEZONE: \"America/New_York\"\n  LOG_LEVEL: \"INFO\"\n  NAMESPACE_LABEL_KEY: \"hyb8nate.xyz/enabled\"\n  NAMESPACE_LABEL_VALUE: \"true\"\n```\n\n### Kubernetes Resources\n\n**Minimum requirements**:\n\n- **CPU**: 100m (requests), 300m (limits)\n- **Memory**: 128Mi (requests), 256Mi (limits)\n- **Storage**: 100M PersistentVolume for SQLite database\n\n**RBAC Permissions** (read-only except for deployments):\n\n```yaml\nrules:\n  - apiGroups: [\"\"]\n    resources: [\"namespaces\"]\n    verbs: [\"get\", \"list\"]\n  - apiGroups: [\"apps\"]\n    resources: [\"deployments\"]\n    verbs: [\"get\", \"list\", \"patch\"]\n```\n\n## 📘 Usage\n\n### 1. Enable Scheduling for a Namespace\n\nLabel the namespace to allow hyb8nate to manage its deployments:\n\n```bash\nkubectl label namespace my-app hyb8nate.xyz/enabled=true\n```\n\nYou can also customize the label key/value via environment variables.\n\n### 2. Create a Schedule\n\n**Via the UI**:\n\n1. Open hyb8nate in your browser\n2. Click **\"New Schedule\"** button\n3. Select namespace from dropdown (only labeled namespaces appear)\n4. Select deployment from dropdown\n5. Set scale-down time (e.g., `22:00` for 10 PM)\n6. Set scale-up time (e.g., `08:00` for 8 AM)\n7. Click **\"Create Schedule\"**\n\n**Via API**:\n\n```bash\n# 1. Login to get token\ncurl -X POST http://localhost:8000/api/auth/login \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"password\": \"admin\"}'\n\n# 2. Create schedule (use the token from step 1)\ncurl -X POST http://localhost:8000/api/schedules \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"namespace\": \"my-app\",\n    \"deployment_name\": \"my-deployment\",\n    \"scale_down_time\": \"22:00\",\n    \"scale_up_time\": \"08:00\"\n  }'\n```\n\n### 3. Monitor Schedules\n\n**Dashboard View**:\n\n- Green badge: Schedule is enabled\n- Red badge: Schedule is disabled\n- \"Currently scaled down\" indicator: Deployment is hibernated\n\n**Via API**:\n\n```bash\ncurl http://localhost:8000/api/schedules \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n```\n\n### 4. Edit a Schedule\n\n- **Via UI**: Click the edit icon (✏️) next to the schedule\n- **Via API**: Send a PATCH request to `/api/schedules/{id}`\n\n**Smart behavior**:\n\n- If you **disable** a schedule that's currently hibernated, it scales back up immediately\n- If you **enable** a schedule during hibernation period, it scales down immediately\n\n### 5. Delete a Schedule\n\nWhen you delete a schedule, hyb8nate automatically scales the deployment back to its original replica count if it's currently hibernated.\n\n## 🔍 How It Works\n\n1. **Schedule Creation**: When you create a schedule, hyb8nate saves the current replica count\n2. **Periodic Check**: APScheduler checks every minute if any schedule should trigger\n3. **Scale Down**: At scale-down time, deployment is scaled to 0 replicas\n4. **Scale Up**: At scale-up time, deployment is restored to original replica count\n5. **State Persistence**: All state is saved in SQLite database (survives restarts)\n6. **Timezone Aware**: All times are interpreted in the configured timezone\n\n### Example Timeline\n\n**Schedule**: Scale down at 22:00, Scale up at 08:00 (timezone: Europe/Paris)\n\n```\n07:00 ────► ✅ Deployment running (3 replicas)\n22:00 ────► 🌙 Scaled down to 0 replicas (hibernation starts)\n23:30 ────► 💤 Still hibernated (0 replicas)\n08:00 ────► ☀️ Scaled up to 3 replicas (back to normal)\n10:00 ────► ✅ Running normally (3 replicas)\n```\n\n## 🔧 Development\n\n### Local Development\n\n**Prerequisites**:\n\n- Python 3.13+\n- Node.js 22+\n- uv (Python package manager)\n- Access to a Kubernetes cluster (for testing)\n\n**Backend**:\n\n```bash\ncd backend\nuv sync\nuv run python main.py\n# API available at http://localhost:8000\n# Swagger docs at http://localhost:8000/api/docs\n```\n\n**Frontend**:\n\n```bash\ncd frontend\nnpm install\nnpm run dev\n# UI available at http://localhost:5173\n```\n\n**Build Docker image**:\n\n```bash\ndocker build -t hyb8nate:dev .\n```\n\n## 🛠️ Troubleshooting\n\n### Schedule not triggering\n\n**Check scheduler is running**:\n\n```bash\nkubectl logs -n hyb8nate -l app=hyb8nate -f | grep \"Scheduler started\"\n```\n\n**Check schedule exists and is enabled**:\n\n```bash\ncurl http://localhost:8000/api/schedules \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n```\n\n**Check timezone configuration**:\n\n```bash\nkubectl get deployment -n hyb8nate hyb8nate -o jsonpath='{.spec.template.spec.containers[0].env[?(@.name==\"TIMEZONE\")].value}'\n```\n\n### Permission denied errors\n\n**Check RBAC permissions**:\n\n```bash\nkubectl auth can-i get deployments --as=system:serviceaccount:hyb8nate:hyb8nate -n my-namespace\nkubectl auth can-i patch deployments --as=system:serviceaccount:hyb8nate:hyb8nate -n my-namespace\n```\n\n### Namespace not appearing in dropdown\n\n**Check namespace has required label**:\n\n```bash\nkubectl get namespace my-namespace -o jsonpath='{.metadata.labels.hyb8nate\\.xyz/enabled}'\n# Should output: true\n```\n\n**Add label if missing**:\n\n```bash\nkubectl label namespace my-namespace hyb8nate.xyz/enabled=true\n```\n\n### Database corrupted\n\n**Reset database** (⚠️ this deletes all schedules):\n\n```bash\nkubectl delete pvc -n hyb8nate hyb8nate-data\nkubectl delete pod -n hyb8nate -l app=hyb8nate\n```\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Clone the repository\n2. Create your feature branch (`git checkout -b dev-feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'feat: some amazing feature'`)\n4. Push to the branch (`git push origin dev-feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Built with [FastAPI](https://fastapi.tiangolo.com/) and [React](https://react.dev/)\n- Kubernetes client library by [Kubernetes](https://github.com/kubernetes-client/python)\n- Scheduling powered by [APScheduler](https://apscheduler.readthedocs.io/)\n- UI components inspired by [Tailwind UI](https://tailwindui.com/)\n\n## 📞 Support\n\n- 📖 [Documentation](https://github.com/hyb8nate/hyb8nate/wiki)\n- 🐛 [Issue Tracker](https://github.com/hyb8nate/hyb8nate/issues)\n- 💬 [Discussions](https://github.com/hyb8nate/hyb8nate/discussions)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\nMade with ❤️ for the Kubernetes community\n\n⭐ Star us on GitHub if you find this project useful!\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyb8nate%2Fhyb8nate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyb8nate%2Fhyb8nate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyb8nate%2Fhyb8nate/lists"}