{"id":49457102,"url":"https://github.com/hyperlight-dev/hyperlight-on-kubernetes","last_synced_at":"2026-04-30T07:04:21.935Z","repository":{"id":347139796,"uuid":"1129244166","full_name":"hyperlight-dev/hyperlight-on-kubernetes","owner":"hyperlight-dev","description":"Shows how to run hyperlight in low trust containers on Kubernetes","archived":false,"fork":false,"pushed_at":"2026-03-26T19:52:18.000Z","size":119,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-27T08:18:35.610Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","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/hyperlight-dev.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":"2026-01-06T20:17:00.000Z","updated_at":"2026-03-26T19:27:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hyperlight-dev/hyperlight-on-kubernetes","commit_stats":null,"previous_names":["hyperlight-dev/hyperlight-on-kubernetes"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/hyperlight-dev/hyperlight-on-kubernetes","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperlight-dev%2Fhyperlight-on-kubernetes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperlight-dev%2Fhyperlight-on-kubernetes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperlight-dev%2Fhyperlight-on-kubernetes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperlight-dev%2Fhyperlight-on-kubernetes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperlight-dev","download_url":"https://codeload.github.com/hyperlight-dev/hyperlight-on-kubernetes/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperlight-dev%2Fhyperlight-on-kubernetes/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32457110,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T22:27:22.272Z","status":"online","status_checked_at":"2026-04-30T02:00:05.929Z","response_time":57,"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":[],"created_at":"2026-04-30T07:04:19.848Z","updated_at":"2026-04-30T07:04:21.917Z","avatar_url":"https://github.com/hyperlight-dev.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hyperlight on Kubernetes\n\nRun [Hyperlight](https://github.com/hyperlight-dev/hyperlight) sandboxes in Kubernetes **without privileged containers**.\n\n## Quick Start\n\n| Target | Commands |\n|--------|----------|\n| **Local (KIND)** | `just local-up \u0026\u0026 just plugin-build \u0026\u0026 just plugin-local-push \u0026\u0026 just plugin-local-deploy` |\n| **Azure (AKS)** | `just azure-up \u0026\u0026 just get-aks-credentials \u0026\u0026 just plugin-build \u0026\u0026 just plugin-acr-push \u0026\u0026 just plugin-azure-deploy` |\n\n```bash\n# Check status\njust status\n\n# View logs\njust logs\n```\n\n## Verify Device Injection\n\nDeploy a test pod to verify the hypervisor device is properly injected:\n\n```bash\n# Deploy test pod (after device plugin is running)\nkubectl apply -f deploy/manifests/examples/test-pod-kvm.yaml\n\n# Check it's running\nkubectl get pod hyperlight-test-kvm\n\n# View logs - should show /dev/kvm exists\nkubectl logs hyperlight-test-kvm\n\n# Cleanup\nkubectl delete pod hyperlight-test-kvm\n```\n\nExpected output:\n```\n=== Hyperlight KVM Test Pod ===\nChecking for /dev/kvm...\n✓ /dev/kvm exists\ncrw-rw---- 1 nobody nobody 10, 232 Jan  6 12:00 /dev/kvm\n\nEnvironment variables:\nHYPERLIGHT_HYPERVISOR=kvm\nHYPERLIGHT_DEVICE_PATH=/dev/kvm\n\n=== Test Complete ===\n```\n\n## How It Works\n\nA Kubernetes Device Plugin exposes hypervisor devices (`/dev/kvm` or `/dev/mshv`) to pods using the [Container Device Interface (CDI)](https://github.com/cncf-tags/container-device-interface). Pods request `hyperlight.dev/hypervisor` and get the device injected securely.\n\n```mermaid\nflowchart LR\n    subgraph Node[\"Kubernetes Node\"]\n        DP[\"Device Plugin\u003cbr/\u003e(DaemonSet)\"]\n        K[Kubelet]\n        C[containerd]\n        P[\"Pod\"]\n        CDI[\"/var/run/cdi/\u003cbr/\u003ehyperlight.json\"]\n        \n        DP --\u003e|\"1. Registers\u003cbr/\u003ehyperlight.dev/hypervisor\"| K\n        DP --\u003e|\"2. Writes CDI spec\"| CDI\n        K --\u003e|\"3. Schedules pod\"| C\n        C --\u003e|\"4. Reads CDI spec\"| CDI\n        C --\u003e|\"5. Injects /dev/kvm or /dev/mshv device\"| P\n    end\n```\n\n## Using Hyperlight in Your Pods\n\nRequest the `hyperlight.dev/hypervisor` resource and apply security best practices:\n\n```yaml\napiVersion: v1\nkind: Pod\nmetadata:\n  name: my-hyperlight-app\nspec:\n  nodeSelector:\n    hyperlight.dev/hypervisor: kvm  # or mshv\n  automountServiceAccountToken: false\n  securityContext:\n    runAsNonRoot: true\n    runAsUser: 65534\n    seccompProfile:\n      type: RuntimeDefault\n  containers:\n    - name: app\n      image: your-hyperlight-app:latest\n      resources:\n        limits:\n          hyperlight.dev/hypervisor: \"1\"\n      securityContext:\n        allowPrivilegeEscalation: false\n        readOnlyRootFilesystem: true\n        capabilities:\n          drop: [\"ALL\"]\n```\n\nSee [deploy/manifests/examples/](deploy/manifests/examples/) for complete examples.\n\n## Example Hyperlight Application\n\nThe `hyperlight-app/` directory contains an example demonstrating best practices:\n\n| Feature | Implementation |\n|---------|----------------|\n| **Minimal Image** | `scratch` base - just the binaries (~2.7MB) |\n| **Static Binary** | musl libc, no runtime dependencies |\n| **Non-root** | Runs as UID 65534 (nobody), no privilege escalation |\n| **Read-only FS** | `readOnlyRootFilesystem: true` |\n| **Seccomp** | `RuntimeDefault` profile |\n| **No Capabilities** | All capabilities dropped |\n| **No K8s API** | `automountServiceAccountToken: false` |\n| **No Host Access** | hostNetwork/hostPID/hostIPC disabled |\n| **Masked /proc** | `procMount: Default` |\n\n```bash\n# Build and deploy to AKS\njust app-build \u0026\u0026 just app-acr-push \u0026\u0026 just app-azure-deploy\n\n# View logs\nkubectl logs -l app=hyperlight-hello -f\n```\n\n## Documentation\n\n| Guide | Description |\n|-------|-------------|\n| [Command Reference](docs/commands.md) | All `just` commands explained |\n| [Local Development](docs/local-development.md) | Test with KIND + local registry |\n| [Azure Deployment](docs/azure-deployment.md) | Production on AKS + ACR |\n| [GHCR Publishing](docs/ghcr-publishing.md) | Publish images to GitHub |\n| [Architecture](docs/architecture.md) | How the device plugin works |\n\n## Project Structure\n\n```\n.\n├── device-plugin/           # Device plugin source code\n│   ├── main.go              # Plugin implementation\n│   └── Dockerfile\n├── hyperlight-app/          # Example Hyperlight application\n│   ├── host/                # Host binary (runs in container)\n│   ├── guest/               # Guest binary (runs in VM)\n│   ├── k8s/                 # App deployment manifests\n│   └── Dockerfile           # Multi-stage build (scratch)\n├── deploy/\n│   ├── manifests/           # Production Kubernetes manifests\n│   │   ├── device-plugin.yaml\n│   │   └── examples/        # Test pods and deployments\n│   ├── local/               # KIND-specific manifests and setup\n│   │   ├── setup.sh\n│   │   ├── teardown.sh\n│   │   └── device-plugin.yaml\n│   └── azure/               # Azure deployment\n│       ├── setup.sh\n│       ├── teardown.sh\n│       └── config.env\n├── docs/                    # Documentation\n├── scripts/                 # Build and test scripts\n└── justfile                 # Build/deploy commands\n```\n\n## Available Commands\n\n```bash\njust --list                  # Show all commands\n\n# Device Plugin\njust plugin-build            # Build binary + image\njust plugin-local-push       # Push to local registry\njust plugin-local-deploy     # Deploy to KIND\njust plugin-acr-push         # Push to Azure Container Registry\njust plugin-azure-deploy     # Deploy to AKS\njust plugin-ghcr-push        # Push to ghcr.io/hyperlight-dev\n\n# Example Hyperlight App\njust app-build               # Build app (scratch image)\njust app-local-deploy        # Deploy to KIND\njust app-azure-deploy        # Deploy to AKS\n\n# Cluster Management\njust local-up                # Create KIND cluster + registry\njust local-down              # Tear down KIND\njust azure-up                # Create Azure infrastructure\njust azure-stop              # Stop AKS cluster \njust azure-start             # Start AKS cluster\njust azure-down              # Delete all Azure resources\n\n# Utilities\njust status                  # Show device plugin status\njust logs                    # View device plugin logs\njust check                   # Verify prerequisites\n```\n\n## Requirements\n\n### Platform\n\n| OS | Support | Notes |\n|----|---------|-------|\n| **Linux** | ✅ Full | Native support |\n| **Windows** | ✅ Via WSL2 | Run everything inside WSL2 (Ubuntu recommended) |\n\n\u003e **Windows users:** Install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) first, then work entirely inside WSL2. Docker Desktop should be configured to use WSL2 backend.\n\u003e\n\u003e ```powershell\n\u003e # PowerShell (as admin)\n\u003e wsl --install -d Ubuntu\n\u003e ```\n\u003e\n\u003e Then open Ubuntu and continue from there.\n\n### All targets\n\n| Tool | Purpose | Install |\n|------|---------|---------|\n| [just](https://github.com/casey/just) | Command runner | `cargo install just` or [binaries](https://github.com/casey/just/releases) |\n| [Docker](https://docs.docker.com/get-docker/) | Build images | See Docker docs (use WSL2 backend on Windows) |\n| [kubectl](https://kubernetes.io/docs/tasks/tools/) | Kubernetes CLI | `curl -LO \"https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl\"` |\n| [Go](https://go.dev/dl/) 1.21+ | Device plugin | `apt install golang` or download |\n| [envsubst](https://www.gnu.org/software/gettext/) | Template substitution | `apt install gettext-base` (usually pre-installed) |\n\n### Local development (KIND)\n\n| Tool | Purpose | Install |\n|------|---------|---------|\n| [KIND](https://kind.sigs.k8s.io/) 0.20+ | Local K8s | `go install sigs.k8s.io/kind@latest` |\n| `/dev/kvm` | Hypervisor | See below |\n\n\u003e **Minimum versions:** Kubernetes 1.26+, KIND 0.20+. Older versions may have container runtime issues.\n\n### Azure deployment\n\n| Tool | Purpose | Install |\n|------|---------|---------|\n| [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) | Azure management | `curl -sL https://aka.ms/InstallAzureCLIDeb \\| sudo bash` |\n\n### Building Hyperlight apps (optional)\n\n| Tool | Purpose | Install |\n|------|---------|---------|\n| [Rust](https://rustup.rs/) | Hyperlight apps | `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \\| sh` |\n| cargo-hyperlight | Guest binaries | `cargo install --locked cargo-hyperlight` |\n\n\u003e **Note:** Rust is only needed if you're building Hyperlight applications locally. The example app builds inside Docker, so Rust isn't required on your host machine.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperlight-dev%2Fhyperlight-on-kubernetes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperlight-dev%2Fhyperlight-on-kubernetes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperlight-dev%2Fhyperlight-on-kubernetes/lists"}