{"id":46676660,"url":"https://github.com/syscode-labs/imp","last_synced_at":"2026-04-01T18:56:49.472Z","repository":{"id":341315518,"uuid":"1169637612","full_name":"syscode-labs/imp","owner":"syscode-labs","description":"Kubernetes operator and node agent for running Firecracker microVM workloads as first-class Kubernetes resources.","archived":false,"fork":false,"pushed_at":"2026-03-19T22:59:23.000Z","size":3155,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-20T13:47:11.759Z","etag":null,"topics":["cilium","firecracker","kubernetes","microvm","operator","virtualization"],"latest_commit_sha":null,"homepage":"https://imp.dev","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/syscode-labs.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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-01T01:17:12.000Z","updated_at":"2026-03-19T22:59:19.000Z","dependencies_parsed_at":"2026-03-12T03:02:22.515Z","dependency_job_id":null,"html_url":"https://github.com/syscode-labs/imp","commit_stats":null,"previous_names":["syscode-labs/imp"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/syscode-labs/imp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syscode-labs%2Fimp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syscode-labs%2Fimp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syscode-labs%2Fimp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syscode-labs%2Fimp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/syscode-labs","download_url":"https://codeload.github.com/syscode-labs/imp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syscode-labs%2Fimp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290981,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","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":["cilium","firecracker","kubernetes","microvm","operator","virtualization"],"created_at":"2026-03-08T23:02:35.036Z","updated_at":"2026-04-01T18:56:49.463Z","avatar_url":"https://github.com/syscode-labs.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Imp\n\n```text\n  )\\  /(\n (  \\/  )    ╦╔╦╗╔═╗\n ( ●  ● )~~✦ ║║║║╠═╝\n  \\ ‿  /     ╩╩ ╩╚\n  (    )~,\n  /\\  /\\     v0.1.0 · imp.dev\n```\n\n[![CI](https://github.com/syscode-labs/imp/actions/workflows/ci.yml/badge.svg)](https://github.com/syscode-labs/imp/actions/workflows/ci.yml)\n[![Lint](https://github.com/syscode-labs/imp/actions/workflows/lint.yml/badge.svg)](https://github.com/syscode-labs/imp/actions/workflows/lint.yml)\n[![CodeQL](https://github.com/syscode-labs/imp/actions/workflows/codeql.yml/badge.svg)](https://github.com/syscode-labs/imp/actions/workflows/codeql.yml)\n[![Go Version](https://img.shields.io/badge/go-1.25.6-00ADD8?logo=go)](https://go.dev/doc/devel/release)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n\n\u003cp\u003e\n  \u003cimg align=\"left\" src=\".github/assets/impvm-dev-mascot-trans-cropped.png\" alt=\"IMP mascot icon\" width=\"288\" /\u003e\n\u003c/p\u003e\n\n**Imp is a Kubernetes operator and node agent for running Firecracker microVM workloads as first-class Kubernetes resources.**\n\nIn plain terms: it gives you lightweight mini-VMs that behave like disposable app sandboxes, so you can run risky or isolated workloads without giving them access to your whole host.\n\nA microVM is a very small virtual machine with stronger isolation than a container, and Firecracker is the open-source microVM runtime Imp uses to start those sandboxes quickly.\n\n\u003cbr clear=\"left\" /\u003e\n\nIt provides CRDs for VM lifecycle, VM networking, snapshots, migrations, warm pools, and runner pools, with Cilium-first networking support, VXLAN fallback for non-Cilium CNIs, and built-in metrics for VM state, latency, and health.\n\n## What Imp Manages\n\n- `ImpVM`: microVM lifecycle and scheduling\n- `ImpNetwork`: VM network, NAT, DNS, and optional Cilium integration\n- `ImpVMSnapshot`: VM state snapshot lifecycle\n- `ImpVMMigration`: migration orchestration\n- `ImpWarmPool`: prewarmed VMs from snapshots\n- `ImpVMRunnerPool`: VM pools for CI-style runner workloads\n- `ImpVMClass`, `ImpVMTemplate`, `ClusterImpConfig`, `ClusterImpNodeProfile`\n\n## Architecture\n\n![Imp architecture (Excalidraw)](docs/diagrams/imp-architecture.svg)\n\nExcalidraw source: `docs/diagrams/imp-architecture.excalidraw`\n\n## Limitations\n\n- GPU passthrough is **not supported**.\n  Firecracker in this project is used for CPU/memory/storage-isolated microVM workloads only.\n\n## Quickstart\n\n### Prerequisites\n\n- Go `1.25.6+`\n- Docker or compatible container runtime\n- `kubectl`\n- A Kubernetes cluster (Kind is supported for e2e)\n- `helm` (recommended install path)\n\n### Install with Helm (Recommended)\n\n```sh\nhelm upgrade --install imp ./charts/imp -n imp-system --create-namespace\nkubectl -n imp-system get pods\n```\n\n### Install with Kustomize/Make\n\n```sh\nmake install\nmake deploy IMG=\u003cregistry\u003e/imp-operator:\u003ctag\u003e\n```\n\n### Uninstall\n\n```sh\nhelm uninstall imp -n imp-system\n# or (kustomize path)\nmake undeploy\nmake uninstall\n```\n\n## First VM in 5 Minutes\n\nApply a minimal network and VM in `default` namespace:\n\n```sh\nkubectl apply -f - \u003c\u003c'EOF'\napiVersion: imp.dev/v1alpha1\nkind: ImpNetwork\nmetadata:\n  name: quick-net\n  namespace: default\nspec:\n  subnet: 192.168.100.0/24\n  nat:\n    enabled: true\n---\napiVersion: imp.dev/v1alpha1\nkind: ImpVM\nmetadata:\n  name: quick-vm\n  namespace: default\nspec:\n  image: docker.io/library/nginx:1.27-alpine\n  networkRef:\n    name: quick-net\nEOF\n```\n\nCheck status:\n\n```sh\nkubectl get impvm -n default\nkubectl describe impvm quick-vm -n default\nkubectl get impnetwork quick-net -n default -o yaml\n```\n\n## VM Expiration (`expireAfter`)\n\nImp can automatically delete a microVM after a fixed runtime window.\n\n- `0` or unset means disabled\n- minimum enabled value is `60s`\n- expiration is anchored to first `status.runningAt`\n- on expiry, the controller issues normal `Delete` (graceful stop path first)\n\nResolution precedence:\n\n1. `ImpVM.spec.expireAfter`\n2. creator pool (`ImpVMRunnerPool.spec.expireAfter` / `ImpWarmPool.spec.expireAfter`)\n3. `ImpVMTemplate.spec.expireAfter`\n4. disabled\n\nQuick example:\n\n```yaml\napiVersion: imp.dev/v1alpha1\nkind: ImpVMTemplate\nmetadata:\n  name: ci-runner-template\n  namespace: default\nspec:\n  classRef:\n    name: ci-small\n  image: ghcr.io/syscode-labs/test:latest\n  expireAfter: 2h\n---\napiVersion: imp.dev/v1alpha1\nkind: ImpVMRunnerPool\nmetadata:\n  name: ci-runner-pool\n  namespace: default\nspec:\n  templateName: ci-runner-template\n  expireAfter: 45m\n  platform:\n    type: github-actions\n    scope:\n      repo: your-org/your-repo\n    credentialsSecret: gh-runner-token\n```\n\nSee [examples/runner-pool-expiration](examples/runner-pool-expiration/README.md) for a complete runnable teaser.\n\n## GitHub Runner Capacity Signaling\n\nWhen using `ImpVMRunnerPool` with GitHub Actions, GitHub does not read pool objects directly.\nIt only sees registered self-hosted runner instances.\n\nRead: [github-capacity-signaling.md](https://github.com/syscode-labs/syscode-ai-internal-plans/blob/main/projects/imp/docs/runner-pool/github-capacity-signaling.md)\n\n## Runner Scaling Mode (GitHub-First)\n\n`ImpVMRunnerPool` supports explicit mode-driven scaling through `spec.scaling` for GitHub Actions (`platform.type=github-actions`).\n\nRequired explicit fields:\n\n- `mode` (`webhook`, `polling`, `hybrid`)\n- `minIdle`\n- `maxConcurrent`\n- `scaleUpStep`\n- `cooldownSeconds`\n\nThis avoids hidden capacity assumptions and makes scaling intent explicit.\n\nExample:\n- [examples/github-scaling-explicit](examples/github-scaling-explicit/README.md)\n- [scaling.md](https://github.com/syscode-labs/syscode-ai-internal-plans/blob/main/projects/imp/docs/runner-pool/scaling.md)\n\n## Development\n\n```sh\nmake test\nmake lint\nmake build\n```\n\nRun operator locally:\n\n```sh\nmake run\n```\n\nRun e2e tests (isolated Kind cluster):\n\n```sh\nmake test-e2e\n```\n\n## OCI Golden Image + Firecracker E2E\n\nThe repository includes IaC scripts under `hack/`:\n\n- `hack/oci-build-golden-image.sh`\n- `hack/packer-build-golden-image.sh` (default build driver: native Packer OCI builder with script preflight/sanitization)\n- `hack/oci-firecracker-e2e.sh`\n\n`hack/oci-build-golden-image.sh` is idempotent for missing OCI inputs:\n\n- auto-detects compartment and AD for `VM.Standard.E2.1.Micro`\n- reuses existing public subnet or creates a minimal public VCN/subnet stack\n- prunes oldest `imp-fc-golden-*` images when custom-image quota is full\n\n`hack/packer-build-golden-image.sh` (recommended) now also performs post-build retention cleanup of old prefixed custom images:\n\n- `OCI_POST_BUILD_PRUNE_OLD_IMAGES` (default `true`)\n- `OCI_POST_BUILD_KEEP_IMAGES` (default `1`)\n\nBuild a minimal golden image:\n\n```sh\nIMP_OCI_PROFILE=syscode-api \\\nIMP_OCI_COMPARTMENT_NAME=homelab \\\nIMP_OCI_DOMAIN_NAME=homelab \\\nOCI_SSH_PUBLIC_KEY_FILE=\"$HOME/.ssh/builder.pub\" \\\nOCI_SSH_PRIVATE_KEY_FILE=\"$HOME/.ssh/builder\" \\\nOCI_OUTPUT_ENV_FILE=\"$HOME/.config/imp/oci-golden.env\" \\\nhack/oci-build-golden-image.sh\n```\n\nBuild via native Packer OCI builder:\n\n```sh\nIMP_OCI_PROFILE=syscode-api \\\nIMP_OCI_COMPARTMENT_NAME=homelab \\\nIMP_OCI_DOMAIN_NAME=homelab \\\nOCI_OUTPUT_ENV_FILE=\"$HOME/.config/imp/oci-golden.env\" \\\nhack/packer-build-golden-image.sh\n```\n\nRun e2e using a generated image:\n\n```sh\nsource \"$HOME/.config/imp/oci-golden.env\"\nIMP_OCI_PROFILE=syscode-api \\\nIMP_OCI_COMPARTMENT_NAME=homelab \\\nIMP_OCI_DOMAIN_NAME=homelab \\\nOCI_GOLDEN_BUILD_DRIVER=packer \\\nOCI_SSH_PUBLIC_KEY_FILE=\"$HOME/.ssh/builder.pub\" \\\nOCI_SSH_PRIVATE_KEY_FILE=\"$HOME/.ssh/builder\" \\\nOCI_IMAGE_OCID=\"$OCI_IMAGE_OCID\" \\\nhack/oci-firecracker-e2e.sh\n```\n\nNotes:\n\n- OCI boot volume minimum is `50` GB.\n- Golden image max size is controlled by `OCI_GOLDEN_MAX_GB` (default `50` GiB).\n- Optional `OCI_GOLDEN_ZERO_FILL=true` can reduce sparse image footprint but is slower.\n- For automation, use an unencrypted SSH key or load passphrase keys in `ssh-agent`.\n- e2e auto-build defaults to `OCI_GOLDEN_BUILD_DRIVER=packer`; set `native-oci` only if needed.\n\n## Networking Support\n\nImp provides first-class integration with **Cilium**. When Cilium is detected:\n\n- VMs are enrolled as `CiliumExternalWorkload` resources\n- Kubernetes `NetworkPolicy` applies to VMs\n- VM traffic is visible in Hubble\n- VMs can reach `ClusterIP` services via kube-dns\n\nFor non-Cilium CNIs (Flannel/Calico/Weave/etc.), Imp uses a VXLAN fallback for cross-node VM connectivity.\n\nCilium IPAM runbook: `docs/networking/cilium-ipam.md`\n\n## Metrics \u0026 Observability\n\nImp exposes operator and agent metrics so you can monitor VM lifecycle and platform health:\n\n- VM state and phase metrics\n- Scheduling/boot latency metrics\n- Guest resource metrics (CPU, memory, disk)\n- Prometheus-compatible scraping and dashboards\n\n## Reconcile Sequence\n\n```mermaid\nsequenceDiagram\n  participant U as User\n  participant APIS as K8s API\n  participant OP as Imp Operator\n  participant AG as Imp Agent (Node)\n  participant FC as Firecracker\n\n  U-\u003e\u003eAPIS: Create ImpVM + ImpNetwork\n  APIS-\u003e\u003eOP: Watch event\n  OP-\u003e\u003eOP: Resolve class/template + schedule node\n  OP-\u003e\u003eAG: Desired VM runtime spec\n  AG-\u003e\u003eFC: Create machine + start microVM\n  FC--\u003e\u003eAG: Runtime state, PID, network info\n  AG--\u003e\u003eAPIS: Status updates\n  OP--\u003e\u003eAPIS: Conditions / phase transitions\n```\n\n## Troubleshooting\n\n- `ImpVM stuck in Pending`: check scheduler events and node capacity.\n  `kubectl describe impvm \u003cname\u003e -n \u003cns\u003e`\n- No VM IP / networking issues: inspect `ImpNetwork` status and agent logs.\n  `kubectl -n imp-system logs ds/imp-agent`\n- Cilium features not active: verify Cilium CRDs exist and cni detection events.\n  `kubectl get crd | grep cilium`\n- Cilium IPAM/pool issues: verify `CiliumPodIPPool` exists and `ImpNetwork.spec.ipam.cilium.poolRef` matches.\n  `kubectl get ciliumpodippool`\n- Webhook admission failures: check cert-manager/webhook pods and certificates.\n  `kubectl -n imp-system get pods,certificates,issuers`\n- Snapshot or migration stalls: inspect related CR conditions.\n  `kubectl describe impvmsnapshot \u003cname\u003e -n \u003cns\u003e`\n  `kubectl describe impvmmigration \u003cname\u003e -n \u003cns\u003e`\n- OCI image/e2e script failures: validate profile/session and compartment/env file values.\n  `oci session validate --profile syscode-api`\n  `source ~/.config/imp/oci-golden.env`\n\n## Security Model\n\n- Control plane:\n  - Operator runs with Kubernetes RBAC scoped to Imp CRDs and required core resources.\n  - Admission webhooks validate critical resources (`ImpVM`, `ImpVMClass`, `ImpVMTemplate`).\n- Node plane:\n  - Agent is privileged to manage Firecracker, networking, and host paths.\n  - Limit agent deployment to trusted nodes via taints/selectors if required.\n- OCI automation:\n  - Use dedicated API user/group (`homelab-api`) with least-privilege policy.\n  - Current policy is scoped to `syscode-labs:homelab` for compute/network/volume families.\n  - Avoid tenancy-wide `manage all-resources`; use temporary broad grants only for debugging.\n- Supply chain:\n  - Pin operator/agent image tags in Helm values for reproducible deployments.\n  - Prefer private registries and signed images where possible.\n- Secrets:\n  - Keep OCI keys out of repo and use local profile files or external secret stores.\n  - Use short-lived session tokens for admin profiles where practical.\n\n## Distribution\n\nCreate a single install bundle:\n\n```sh\nmake build-installer IMG=\u003cregistry\u003e/imp-operator:\u003ctag\u003e\n```\n\nThis generates `dist/install.yaml`.\n\n## Contributing\n\nContributions are welcome. Before opening a PR:\n\n```sh\nmake manifests generate\nmake lint-fix\nmake test\n```\n\n## License\n\nCopyright 2026.\n\nLicensed under the Apache License, Version 2.0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyscode-labs%2Fimp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsyscode-labs%2Fimp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyscode-labs%2Fimp/lists"}