{"id":27428088,"url":"https://github.com/persys-dev/persys-cloud","last_synced_at":"2026-04-08T13:31:52.870Z","repository":{"id":164472753,"uuid":"639902207","full_name":"persys-dev/persys-cloud","owner":"persys-dev","description":"Community Driven Cloud Automation :)","archived":false,"fork":false,"pushed_at":"2026-02-18T15:44:03.000Z","size":1691,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-18T18:39:57.266Z","etag":null,"topics":["automation","cloud","cluster","golang","kubernetes","pipelines","platform","sre"],"latest_commit_sha":null,"homepage":"https://persys.cloud","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/persys-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"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":"2023-05-12T13:39:30.000Z","updated_at":"2026-02-18T15:47:43.000Z","dependencies_parsed_at":"2023-12-01T23:33:37.448Z","dependency_job_id":"88356fff-0256-43b3-8839-269d887b304d","html_url":"https://github.com/persys-dev/persys-cloud","commit_stats":null,"previous_names":["persys-dev/persys-cloud","persys-dev/persys-devops"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/persys-dev/persys-cloud","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/persys-dev%2Fpersys-cloud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/persys-dev%2Fpersys-cloud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/persys-dev%2Fpersys-cloud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/persys-dev%2Fpersys-cloud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/persys-dev","download_url":"https://codeload.github.com/persys-dev/persys-cloud/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/persys-dev%2Fpersys-cloud/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31558380,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T10:21:54.569Z","status":"ssl_error","status_checked_at":"2026-04-08T10:21:38.171Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["automation","cloud","cluster","golang","kubernetes","pipelines","platform","sre"],"created_at":"2025-04-14T13:17:32.905Z","updated_at":"2026-04-08T13:31:52.854Z","avatar_url":"https://github.com/persys-dev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Persys Compute\n\n![License](https://img.shields.io/badge/license-MIT-blue.svg)\n![Language](https://img.shields.io/badge/language-Go-00ADD8)\n![Architecture](https://img.shields.io/badge/architecture-control--plane-orange)\n![Transport](https://img.shields.io/badge/transport-gRPC%20%2B%20mTLS-green)\n\nPersys Compute is a scheduler-driven distributed compute control plane\ndesigned to orchestrate containers, Docker Compose applications, and\nvirtual machines across heterogeneous infrastructure.\n\nIt is built with a clear architectural philosophy:\n\n- Centralized scheduler (authoritative desired state)\n- Dumb but reliable agents (local execution only)\n- Strongly typed gRPC contracts\n- mTLS everywhere\n- etcd-backed persistent cluster state\n- Explicit reconciliation loops\n- Resource-aware placement\n- Lease-based node liveness model\n\nThis repository currently lives under `persys-cloud`, but the product\nname is **Persys Compute**.\n\n------------------------------------------------------------------------\n\n## Vision\n\nPersys Compute is not just a container orchestrator.\n\nIt is a programmable compute control plane designed to:\n\n- Run Docker containers\n- Run Docker Compose stacks (from Git or inline spec)\n- Provision and manage virtual machines\n- Enforce CPU, memory, disk limits\n- Reconcile drift automatically\n- Scale from a single bare-metal server to multi-node clusters\n- Support hybrid and federated deployments\n\nThe long-term goal is hyperscaler-style infrastructure for private and\nhybrid environments --- without unnecessary abstraction or\noverengineering.\n\n------------------------------------------------------------------------\n\n## Core Architecture\n\nPersys Compute follows a strict control-plane model.\n\n### Northbound (User → Control Plane)\n\nUser → Gateway (HTTP + mTLS) → Scheduler\n\n- REST APIs for platform access\n- Authentication \u0026 service identity\n- Workload submission\n- Administrative operations\n\n### Southbound (Control Plane → Nodes)\n\nScheduler ⇄ Agent (gRPC + mTLS)\n\n- Node registration\n- Heartbeat \u0026 lease model\n- Workload lifecycle execution\n- Status reporting\n\nAgents never schedule themselves. Scheduler owns all placement\ndecisions.\n\n------------------------------------------------------------------------\n\n## Control Plane Components\n\n### persys-scheduler\n\nAuthoritative cluster brain.\n\nResponsibilities:\n\n- Node registration \u0026 lease management\n- Workload scheduling\n- Resource-aware placement\n- Desired-state reconciliation\n- Retry \u0026 backoff policies\n- etcd state persistence\n- Event emission\n- Health \u0026 metrics endpoints\n\n### persys-gateway\n\nPlatform entrypoint.\n\nResponsibilities:\n\n- REST APIs\n- mTLS authentication\n- Request routing to scheduler\n- Webhook ingestion (future use)\n- Platform-level authorization\n\n### vault\n\nCertificate authority bootstrap.\n\n- Service identity issuance\n- mTLS trust chain\n- Agent certificate provisioning\n\n### persys-federation\n\nFuture hybrid/multi-cloud integration layer.\n\n- Connect to AWS/GCP/other providers\n- Offload workloads\n- Aggregate compute resources\n\n### persys-agent (runtime node agent)\n\nResponsibilities:\n\n- Register with scheduler\n- Maintain heartbeat\n- Enforce resource limits\n- Execute containers / compose / VMs\n- Report workload status\n- Perform local garbage collection\n- Expose Prometheus metrics\n\nAgent is intentionally simple and execution-focused.\n\n------------------------------------------------------------------------\n\n## Scheduling Model\n\n1. Agent boots\n2. Agent registers with scheduler via gRPC\n3. Scheduler stores node in etcd and issues lease\n4. Agent sends periodic heartbeat\n5. Scheduler tracks node liveness\n6. User submits workload\n7. Scheduler selects node based on:\n    - CPU availability\n    - Memory availability\n    - Disk pools\n    - Labels\n    - Capability matching\n8. Scheduler sends ApplyWorkload\n9. Agent executes and reports status\n10. Reconciler enforces desired state\n\n------------------------------------------------------------------------\n\n## Supported Workload Types\n\n### Containers\n\n- Image-based\n- Resource limits\n- Env variables\n- Volumes\n- Ports\n- Restart policies\n- Privileged mode (optional)\n\n### Docker Compose\n\n- Git-based deployments\n- Inline YAML support\n- Environment injection\n- Secret injection (future: Vault integration)\n- Mixed public/private images\n\n### Virtual Machines\n\n- vCPU \u0026 memory specification\n- Disk provisioning via storage pools\n- Cloud-init injection\n- Network configuration\n- Login credential provisioning\n- Future: IP reporting back to scheduler\n\n------------------------------------------------------------------------\n\n### Cluster State Model (etcd)\n\nScheduler persists:\n\n- /nodes/`\u003cnode-id\u003e`{=html}\n- /nodes/`\u003cnode-id\u003e`{=html}/lease\n- /workloads/`\u003cworkload-id\u003e`{=html}\n- /assignments/`\u003cworkload-id\u003e`{=html}\n- /events/`\u003ctimestamp\u003e`{=html}\n- /retries/`\u003cworkload-id\u003e`{=html}\n\nThis enables:\n\n- Auditability\n- Recovery after scheduler restart\n- Drift detection\n- Retry tracking\n- Failure history\n\n------------------------------------------------------------------------\n\n## Resource Enforcement\n\nAgent enforces:\n\n- CPU limits\n- Memory limits\n- Disk allocation\n- System threshold rejection (default 80% utilization)\n- Orphan resource cleanup\n- Zombie workload detection\n\nWorkloads are rejected early if capacity is insufficient.\n\n------------------------------------------------------------------------\n\n## Reliability Model\n\nPersys Compute uses:\n\n- Lease-based node liveness\n- Heartbeat TTL enforcement\n- Idempotent workload operations\n- Explicit failure reasons (enum-based)\n- Garbage collection loops\n- Structured error propagation\n- Metrics-first observability\n\nNo ghost workloads. No silent failures. No hidden retries.\n\n------------------------------------------------------------------------\n\n## Observability\n\nEach component exposes:\n\n- /metrics (Prometheus)\n- /health\n- Structured logs\n\nMetrics include:\n\n- Workload counts\n- Failure reasons\n- Apply duration\n- Resource utilization\n- Runtime health status\n- GC statistics\n\n------------------------------------------------------------------------\n\n## Local Development\n\n### 1. Start full stack\n\n```bash\ncd infra/docker\ndocker compose up -d --build\n```\n\n### 2. Build CLI\n\n```bash\ncd persysctl\ngo build -o ./bin/persysctl\n```\n\n### 3. Quick smoke commands\n\n```bash\n# Cluster view from gateway\n./bin/persysctl --transport http cluster list\n\n# List nodes/workloads routed through gateway\n./bin/persysctl --transport http node list\n./bin/persysctl --transport http workload list\n```\n\n------------------------------------------------------------------------\n\n## Project Philosophy\n\nPersys Compute is built around:\n\n- Explicit contracts (protobuf-first design)\n- Control-plane correctness\n- Minimal but powerful abstraction\n- Hyperscaler-inspired architecture\n- Avoiding unnecessary AI buzz\n- Strong separation of concerns\n- Scalability from day one\n\nThis is infrastructure designed to scale --- without rewriting the\nsystem when adding more nodes.\n\n------------------------------------------------------------------------\n\n## Roadmap Highlights\n\n- Storage pool full implementation\n- VM network introspection \u0026 IP reporting\n- Retry engine with exponential backoff\n- Federation workload offloading\n- Secrets integration (Vault)\n- Stream-based control channel\n- Multi-cluster support\n\n------------------------------------------------------------------------\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpersys-dev%2Fpersys-cloud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpersys-dev%2Fpersys-cloud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpersys-dev%2Fpersys-cloud/lists"}