{"id":29140854,"url":"https://github.com/gthulhu/gthulhu","last_synced_at":"2026-05-23T09:01:19.056Z","repository":{"id":295555527,"uuid":"990385817","full_name":"Gthulhu/Gthulhu","owner":"Gthulhu","description":"eBPF-based workload orchestration platform, built for Cloud Native ecosystem.","archived":false,"fork":false,"pushed_at":"2026-05-21T10:57:32.000Z","size":10389,"stargazers_count":384,"open_issues_count":3,"forks_count":23,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-05-21T19:00:31.792Z","etag":null,"topics":["cloud-native","cncf","ebpf","scheduler","scx"],"latest_commit_sha":null,"homepage":"https://gthulhu.org","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Gthulhu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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-05-26T03:26:00.000Z","updated_at":"2026-05-15T11:41:43.000Z","dependencies_parsed_at":"2025-06-30T14:32:58.424Z","dependency_job_id":"adcf3974-6246-4773-a45d-0ad6d4e42c8d","html_url":"https://github.com/Gthulhu/Gthulhu","commit_stats":null,"previous_names":["gthulhu/gthulhu"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/Gthulhu/Gthulhu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gthulhu%2FGthulhu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gthulhu%2FGthulhu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gthulhu%2FGthulhu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gthulhu%2FGthulhu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Gthulhu","download_url":"https://codeload.github.com/Gthulhu/Gthulhu/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gthulhu%2FGthulhu/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33389229,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T04:15:53.637Z","status":"ssl_error","status_checked_at":"2026-05-23T04:15:53.242Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["cloud-native","cncf","ebpf","scheduler","scx"],"created_at":"2025-06-30T18:01:06.534Z","updated_at":"2026-05-23T09:01:19.049Z","avatar_url":"https://github.com/Gthulhu.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gthulhu: Cloud-Native Workload Orchestration with eBPF and Custom Scheduling\n\n\u003ca href=\"https://landscape.cncf.io/?item=provisioning--automation-configuration--gthulhu\" target=\"_blank\"\u003e\u003cimg src=\"https://img.shields.io/badge/CNCF%20Landscape-5699C6?style=for-the-badge\u0026logo=cncf\u0026label=cncf\" alt=\"cncf landscape\" /\u003e\u003c/a\u003e\n\n\u003ca href=\"https://ebpf.io/applications/\" target=\"_blank\"\u003e\u003cimg src=\"https://img.shields.io/badge/eBPF%20Application%20Landscape-5699C6?style=for-the-badge\u0026logo=ebpf\u0026label=ebpf\" alt=\"ebpf landscape\" /\u003e\u003c/a\u003e\n\n[![LFX Contributors](https://insights.linuxfoundation.org/api/badge/contributors?project=gthulhu)](https://insights.linuxfoundation.org/project/gthulhu)\n[![Go](https://github.com/Gthulhu/Gthulhu/actions/workflows/go.yaml/badge.svg)](https://github.com/Gthulhu/Gthulhu/actions/workflows/go.yaml)\n[![Portability](https://github.com/Gthulhu/Gthulhu/actions/workflows/portability.yaml/badge.svg)](https://github.com/Gthulhu/Gthulhu/actions/workflows/portability.yaml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/Gthulhu/Gthulhu)](https://goreportcard.com/report/github.com/Gthulhu/Gthulhu)\n\n\u003cimg src=\"./assets/logo.svg\" alt=\"logo\" width=\"300\"/\u003e\n\n## Overview\n\nGthulhu is a cloud-native workload orchestration platform that provides granular, pod-level scheduling observability and automated scaling for Kubernetes workloads. Through an intuitive web GUI, users can select workloads running on Kubernetes, monitor fine-grained scheduling metrics collected via eBPF, and configure automatic scaling policies powered by KEDA — all without modifying the kernel or application code. For clusters running Linux 6.12+ with `sched_ext`, Gthulhu further supports defining scheduling strategies and distributing scheduling intents to each node, enabling kernel-level custom CPU scheduling across the cluster.\n\n![](./assets/demo.gif)\n\n\u003e Please visit https://youtu.be/Cyjrh9cW1a8 for a demo video showcasing Gthulhu's capabilities.\n\n### Key Capabilities\n\n- **Pod-Level Scheduling Metrics** — Gthulhu uses eBPF to hook into kernel scheduling events (`fentry`/`fexit`), collecting per-process metrics such as voluntary/involuntary context switches, CPU time, wait time, run count, and CPU migrations. These metrics are aggregated at the pod level and exposed via REST APIs.\n- **Declarative Configuration** — Users define which workloads to monitor using Kubernetes label selectors and namespaces, either through the web GUI or the `PodSchedulingMetrics` CRD.\n- **KEDA Auto-Scaling Integration** — Gthulhu provides out-of-the-box integration with [KEDA](https://keda.sh/), enabling auto-scaling decisions driven by real scheduling behavior rather than generic resource utilization.\n- **Advanced: Scheduling Strategies \u0026 Intents** *(requires Linux 6.12+ with `sched_ext`)* — Users can define scheduling strategies (priority, time-slice, CPU affinity) for specific workloads via the web GUI or REST API. The Manager converts strategies into scheduling intents and distributes them to Decision Makers on each node, enabling cross-node coordinated scheduling policy enforcement.\n- **Advanced: Custom CPU Scheduling** *(requires Linux 6.12+ with `sched_ext`)* — On nodes running a supported kernel, Gthulhu attaches a custom eBPF-based CPU scheduler through the `sched_ext` mechanism, applying the scheduling intents at the kernel level — including priority-based dispatching, dynamic time-slice tuning, and preemption control — without modifying the kernel itself.\n\n### Why Gthulhu?\n\nThe default Linux kernel scheduler emphasizes fairness and cannot be optimized for the specific needs of individual applications. Cloud-native workloads — trading systems, big data analytics, ML training — all have different scheduling requirements. Gthulhu bridges this gap by:\n\n1. **Making scheduling visible** — exposing kernel-level scheduling behavior as actionable metrics\n2. **Making scaling smarter** — driving auto-scaling from actual scheduling pressure, not just CPU/memory averages\n3. **Making scheduling tunable** (advanced) — allowing per-workload CPU scheduling policies on supported kernels\n\n### Architecture\n\n```\n┌──────────────────────────────────────────────────────────────────────────────────┐\n│                             Gthulhu Architecture                                 │\n├──────────────────────────────────────────────────────────────────────────────────┤\n│                                                                                  │\n│   ┌──────────────┐        ┌──────────────────────┐        ┌─────────────────┐    │\n│   │    User      │──────▶ │      Manager         │──────▶ │    MongoDB      │    │\n│   │  (Web GUI)   │        │ (Central Management) │        │  (Persistence)  │    │\n│   └──────────────┘        └──────────┬───────────┘        └─────────────────┘    │\n│                                      │                                           │\n│                      ┌───────────────┼───────────────┐                           │\n│                      │               │               │                           │\n│                      ▼               ▼               ▼                           │\n│           ┌──────────────┐ ┌──────────────┐ ┌──────────────┐                     │\n│           │Decision Maker│ │Decision Maker│ │Decision Maker│  (DaemonSet)        │\n│           │   (Node 1)   │ │   (Node 2)   │ │   (Node N)   │                     │\n│           └──────┬───────┘ └──────┬───────┘ └──────┬───────┘                     │\n│                  │                │                │                              │\n│          ┌───────┴───────┐ ┌──────┴───────┐ ┌─────┴────────┐                     │\n│          ▼               ▼ ▼              ▼ ▼              ▼                      │\n│   ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐                    │\n│   │eBPF Metrics│ │ sched_ext  │ │eBPF Metrics│ │ sched_ext  │                    │\n│   │ Collector  │ │ Scheduler* │ │ Collector  │ │ Scheduler* │                    │\n│   └──────┬─────┘ └────────────┘ └──────┬─────┘ └────────────┘                    │\n│          │                              │                                        │\n│          ▼                              ▼               ┌─────────────────┐       │\n│   ┌────────────────────────────────────────────┐        │      KEDA       │       │\n│   │       Prometheus / Grafana Dashboards      │───────▶│  (Auto-Scaler)  │       │\n│   └────────────────────────────────────────────┘        └─────────────────┘       │\n│                                                                                  │\n│   * sched_ext scheduler requires Linux 6.12+ (advanced feature)                  │\n└──────────────────────────────────────────────────────────────────────────────────┘\n```\n\n**How it works:**\n\n1. Users select Kubernetes workloads through the **Web GUI** (or `PodSchedulingMetrics` CRD) and define monitoring/scheduling policies.\n2. The **Manager** persists configurations, queries pods via the Kubernetes API (Informer), and distributes intents to Decision Makers.\n3. Each **Decision Maker** (deployed as a DaemonSet) runs on every node and attaches eBPF programs to kernel scheduling hooks to collect per-process metrics in real time.\n4. Metrics are aggregated at the pod level and exported to **Prometheus**, enabling Grafana dashboards and **KEDA**-driven auto-scaling.\n5. On nodes with Linux 6.12+ and `sched_ext` support, the advanced **custom scheduler** can be activated for priority-based dispatching and time-slice tuning.\n\n**Key links:**\n- Core scheduling framework: [qumun](https://github.com/Gthulhu/qumun) — build custom Linux schedulers in Go using eBPF/sched_ext, without modifying the kernel\n- Deployment: [Helm chart](https://github.com/Gthulhu/chart/tree/main/gthulhu) for Kubernetes clusters\n- Real-world use case: [Improving Network Performance with Custom eBPF-based Schedulers](https://free5gc.org/blog/20250726/index.en/)\n\n\n### Meaning of the Name\n\nThe name Gthulhu is inspired by Cthulhu, a mythical creature known for its many tentacles. Just as tentacles can grasp and steer, Gthulhu symbolizes the ability to take the helm and navigate the complex world of modern distributed systems — much like how Kubernetes uses a ship’s wheel as its emblem.\n\nThe prefix “G” comes from Golang, the language at the core of this project, highlighting both its technical foundation and its developer-friendly design.\n\nUnderneath, Gthulhu runs on the qumun framework (qumun means “heart” in the Bunun language, an Indigenous people of Taiwan), reflecting the role of a scheduler as the beating heart of the operating system. This not only emphasizes its central importance in orchestrating workloads but also shares a piece of Taiwan’s Indigenous culture with the global open-source community.\n\n## Prerequisites\n\nTo build and run Gthulhu, ensure you have the following prerequisites installed on your system:\n\n**Core (Metrics Collection \u0026 Monitoring):**\n- Go 1.22+\n- LLVM/Clang 17+\n- libbpf\n- Linux kernel with eBPF support (5.x+)\n\n**Advanced (Custom CPU Scheduling):**\n- Linux kernel 6.12+ with `sched_ext` support (`CONFIG_SCHED_CLASS_EXT`)\n\n\u003e **Note:** The eBPF metrics collection feature works on a wide range of kernels and does not require `sched_ext`. The custom CPU scheduling feature requires Linux 6.12+ which may not be available on all managed Kubernetes platforms (e.g., GKE currently does not support it).\n\nSee [Installation guide](https://gthulhu.org/installation/) for detailed installation instructions.\n\n## Usage\n\n### Setting Up Dependencies\n\nFirst, clone the required dependencies:\n\n```bash\nmake dep\ngit submodule init\ngit submodule sync\ngit submodule update\ncd scx\ncargo build --release -p scx_rustland\n```\n\nThis will clone libbpf and the custom libbpfgo fork needed for the project.\n\n### Linting the Code\nTo ensure code quality, run the linter:\n\n```bash\nmake lint\n```\n\n### Building the Scheduler\n\nBuild the scheduler with:\n\n```bash\nmake build\n```\n\nThis compiles the BPF program, builds libbpf, generates the skeleton, and builds the Go application.\n\nCross-compilation for arm64 is supported by setting the `ARCH` variable:\n\n```bash\nmake build ARCH=arm64\n```\n\n### Testing the Scheduler\n\nTo test the scheduler in a virtual environment using kernel v6.12:\n\n```bash\nmake test\n```\n\nThis uses `vng` (virtual kernel playground) to run the scheduler with the appropriate kernel version.\n\nYou can also test with a specific kernel version:\n\n```bash\nmake test KERNEL_VERSION=6.12\n```\n\n#### Portability Testing\n\nGthulhu is automatically tested for portability across multiple Linux kernel versions (6.12+) through a daily scheduled GitHub Actions workflow. This ensures that the released packages remain compatible with newer kernel versions. The portability tests run against kernel versions 6.12, 6.13, 6.14, 6.15, 6.16, and 6.17.\n\n### Launching Gthulhu by using schedkit\n\nFirst, install `schedctl` from [schedkit](https://github.com/schedkit/schedctl) (created by @dottorblaster):\n```sh\n$ git clone https://github.com/schedkit/schedctl.git\n$ cd schedctl\n$ make install\n```\n\nThen, you can launch Gthulhu with:\n\n```sh\n$ sudo ./schedctl run gthulhu\nTrying to pull ghcr.io/schedkit/gthulhu:latest...\nGetting image source signatures\nCopying blob sha256:a517a5a43837a7785dad62f579950a8abe4d1bd2ae5a096bda78150a1cc70c64\nCopying blob sha256:2d35ebdb57d9971fea0cac1582aa78935adf8058b2cc32db163c98822e5dfa1b\nCopying config sha256:85fb26cbfed25f79e321ef4e0a3e4e6fc7f01a957dbcee6aed815bdb93458136\nWriting manifest to image destination\nStoring signatures\nContainer ghcr.io/schedkit/gthulhu:latest started successfully\n$ sudo podman ps -a\nCONTAINER ID  IMAGE                            COMMAND     CREATED        STATUS            PORTS       NAMES\n015d1b5fbe96  ghcr.io/schedkit/gthulhu:latest  /main       6 seconds ago  Up 6 seconds ago              gthulhu\n```\n\n### Running with Docker\nTo run the scheduler in a Docker container, you can either build locally or use the pre-built image from GitHub Container Registry:\n\n**Using the pre-built image from GitHub Packages:**\n```bash\ndocker run --privileged=true --pid host --rm ghcr.io/gthulhu/gthulhu:latest /gthulhu/main\n```\n\n**Building locally:**\n```bash\nmake image\ndocker run --privileged=true --pid host --rm  127.0.0.1:25000/gthulhu:latest /gthulhu/main\n```\n\n### Debugging\n\nIf you need to inspect the BPF components, you can use:\n\n```bash\nsudo bpftool prog list            # List loaded BPF programs\nsudo bpftool map list             # List BPF maps\nsudo cat /sys/kernel/debug/tracing/trace_pipe # View BPF trace output\n```\n\n### Stress Testing by using `stress-ng`\n\n```\nstress-ng -c 20 --timeout 20s --metrics-brief\n```\n\n## Troubleshooting\n\nSee [Installation guide](https://gthulhu.org/installation/#troubleshooting).\n\n## License\n\nThis software is distributed under the terms of the Apache License 2.0.\n\n## Contributing\n\nSee [Contributing guide](https://gthulhu.org/contributing/).\n\n## Community Resources\n\n- [NotebookLM](https://notebooklm.google.com/notebook/89a6a260-3d54-4760-93a2-dcc06c6d8043): includes all of materials used in the project, including the pptx, design documents, and more.\n- [GitHub Discussion](https://github.com/Gthulhu/Gthulhu/discussions): a place for community discussions, questions, and feature requests.\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=Gthulhu/Gthulhu\u0026type=Date)](https://www.star-history.com/#Gthulhu/Gthulhu\u0026Date)\n\n## Special Thanks\n\n- [scx](https://github.com/sched-ext/scx)\n- [libbpfgo](https://github.com/aquasecurity/libbpfgo)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgthulhu%2Fgthulhu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgthulhu%2Fgthulhu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgthulhu%2Fgthulhu/lists"}