Skip to content

Example: Run a KVM guest

It is possible to launch a Virtual Machine (VM) within a GitHub Action. Support for virtualization is not enabled by default for Actuated. The Agent has to be configured to use a custom kernel.

There are some prerequisites to enable KVM support:

  • aarch64 runners are not supported at the moment.
  • A bare-metal host for the Agent is required.

Configure the Agent

  1. Make sure nested virtualization is enabled on the Agent host.

  2. Modify the start.sh file for your Actuated Agent and add the kvm suffix to the kernel-ref tag:

    sudo -E agent up \
    --image-ref=ghcr.io/openfaasltd/actuated-ubuntu20.04:x86-64-latest \
-   --kernel-ref=ghcr.io/openfaasltd/actuated-kernel-5.10.77:x86-64-latest \
+   --kernel-ref=ghcr.io/openfaasltd/actuated-kernel-5.10.77:x86-64-latest-kvm \
    --listen-addr 127.0.0.1:

  3. Restart the Agent to use the new kernel.

    sudo systemctl restart actuated

  4. Run a test build to verify KVM support is enabled in the runner. The specs script from the test build will report whether /dev/kvm is available.

Run a Firecracker microVM

This example is an adaptation of the Firecracker quickstart guide that we run from within a GitHub Actions workflow.

The workflow instals Firecracker, configures and boots a guest VM and then waits 20 seconds before shutting down the VM and exiting the workflow.

  1. Create a new repository and add a workflow file.

    The workflow file: ./.github/workflows/vm-run.yaml:

    name: vm-run

on: push
jobs:
vm-run:
    runs-on: actuated
    steps:
    - uses: actions/checkout@master
        with:
        fetch-depth: 1
    - name: Install arkade
        uses: alexellis/setup-arkade@v2
    - name: Install firecracker
        run: sudo arkade system install firecracker
    - name: Run microVM
        run: sudo ./run-vm.sh

  2. Add the run-vm.sh script to the root of the repository.

    Running the script will:

    • Get the kernel and rootfs for the microVM
    • Start fireckracker and configure the guest kernel and rootfs
    • Start the guest machine
    • Wait for 20 seconds and kill the firecracker process so workflow finishes.

    The run-vm.sh script:

    #!/bin/bash

# Clone the example repo
git clone https://github.com/skatolo/nested-firecracker.git

# Run the VM script
./nested-firecracker/run-vm.sh

  3. Hit commit and check the run logs of the workflow. You should find the login prompt of the running microVM in the logs.

The full example is available on GitHub

For more examples and use-cases see: