Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions machine/hyperlight/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
## Hyperlight Machine Driver

A kraftkit machine driver that runs Unikraft unikernels on
[Hyperlight](https://github.com/hyperlight-dev/hyperlight) micro-VMs. Each
machine created through this driver is a detached `hyperlight-unikraft` child
process, so `kraft ps`, `kraft stop`, `kraft rm`, and `kraft logs` all work
across separate kraft invocations via standard PID tracking.

### Requirements

- Linux host with `/dev/kvm` read/write access, or Windows host with the
Windows Hypervisor Platform (WHP) enabled.
- The `hyperlight-unikraft` binary (from
[danbugs/hyperlight-unikraft](https://github.com/danbugs/hyperlight-unikraft))
installed on `$PATH`:

```bash
cargo install --git https://github.com/danbugs/hyperlight-unikraft \
--branch main hyperlight-unikraft-host --bin hyperlight-unikraft
```

- Unikraft kernels built for the `hyperlight` platform target.

No cgo, no linker flags, no shared libraries — kraftkit just needs to find
`hyperlight-unikraft` on `$PATH` at runtime. A future iteration may link the
Hyperlight host library in-process via cgo for tighter lifecycle control and
lower per-call overhead; the subprocess model is a deliberate first step.

### Platform selection

The driver registers two names:

- `hyperlight` (canonical)
- `hl` (shorthand)

Either can be used with `--plat`:

```bash
kraft build --plat hyperlight --arch x86_64
kraft run --plat hl ...
```

### Defaults

- `DefaultMemory`: `16Mi`. Override with `--memory` for heavier guests.
- `DefaultStack`: `8Mi`. Not yet exposed through the CLI or Kraftfile.

### Limitations

- `kraft pause` is not supported; Hyperlight has no pause semantics.
- The child process is terminated on `kraft stop` via SIGTERM; there is no
in-VM quiesce step.
68 changes: 68 additions & 0 deletions machine/hyperlight/config.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
// SPDX-License-Identifier: BSD-3-Clause
// Copyright (c) 2026, Unikraft GmbH and The KraftKit Authors.
// Licensed under the BSD-3-Clause License (the "License").
// You may not use this file except in compliance with the License.
package hyperlight

// HyperlightConfig represents configuration for a Hyperlight micro-VM.
type HyperlightConfig struct {
// KernelPath is the path to the unikernel binary.
KernelPath string `json:"kernelPath,omitempty"`

// Memory is the amount of memory allocated to the VM (e.g. "512Mi").
Memory string `json:"memory,omitempty"`

// Stack is the stack size (e.g. "8Mi").
Stack string `json:"stack,omitempty"`

// InitRd is the path to the initramfs/rootfs CPIO archive.
InitRd string `json:"initrd,omitempty"`

// LogPath is the path to the log file.
LogPath string `json:"logPath,omitempty"`
}

type HyperlightOption func(*HyperlightConfig) error

func NewHyperlightConfig(opts ...HyperlightOption) (*HyperlightConfig, error) {
cfg := &HyperlightConfig{
Memory: "16Mi",
Stack: "8Mi",
}

for _, o := range opts {
if err := o(cfg); err != nil {
return nil, err
}
}

return cfg, nil
}

func WithKernel(kernel string) HyperlightOption {
return func(c *HyperlightConfig) error {
c.KernelPath = kernel
return nil
}
}

func WithMemory(memory string) HyperlightOption {
return func(c *HyperlightConfig) error {
c.Memory = memory
return nil
}
}

func WithInitRd(initrd string) HyperlightOption {
return func(c *HyperlightConfig) error {
c.InitRd = initrd
return nil
}
}

func WithStack(stack string) HyperlightOption {
return func(c *HyperlightConfig) error {
c.Stack = stack
return nil
}
}
11 changes: 11 additions & 0 deletions machine/hyperlight/init.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
// SPDX-License-Identifier: BSD-3-Clause
// Copyright (c) 2026, Unikraft GmbH and The KraftKit Authors.
// Licensed under the BSD-3-Clause License (the "License").
// You may not use this file except in compliance with the License.
package hyperlight

import "encoding/gob"

func init() {
gob.Register(HyperlightConfig{})
}
10 changes: 10 additions & 0 deletions machine/hyperlight/options.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
// SPDX-License-Identifier: BSD-3-Clause
// Copyright (c) 2026, Unikraft GmbH and The KraftKit Authors.
// Licensed under the BSD-3-Clause License (the "License").
// You may not use this file except in compliance with the License.

package hyperlight

// MachineServiceV1alpha1Option is a functional option for configuring the
// Hyperlight machine service.
type MachineServiceV1alpha1Option func(*machineV1alpha1Service) error
Loading