Skip to content

Windhoek is a small API written in Golang that exposes an invoke route we can call to run a function within a Firecracker VM.

Notifications You must be signed in to change notification settings

runvelocity/windhoek

Repository files navigation

Build and Lint Windhoek

Windhoek

Windhoek is a small API written in Golang that exposes routes to create Firecracker VMs to run velocity functions.
Explore the docs »

Table of Contents
  1. About
  2. Getting Started
  3. Usage
  4. Roadmap
  5. Contact

About

Windhoek is an API used as part of the velocity stack to manage the creation of Firecracker MicroVMs and running Velocity functions within them

(back to top)

Getting Started

This section outlines how to run the Windhoek API within your Virtual machine.

Prerequisites

This API creates Firecracker MicroVMs and these VMs can only be created on Virtual machines that support nested virtualization, such as, Digitalocean droplets, AWS .metal instances and bare-metal servers.

Installation

A convinience installation script has been provided and you can quicly run the API by using the following command

curl https://gist.githubusercontent.com/utibeabasi6/6cdf2c52262ef8eeffba2e4d6970d36c/raw/388413f24c06cd79017d948a4f6e049cf556d6f7/windhoek-setup.sh | bash

Otherwise, you can install the individual components by following the steps below.

Install Golang
 pushd /tmp
 wget https://go.dev/dl/go1.21.5.linux-amd64.tar.gz
 rm -rf /usr/local/go && tar -C /usr/local -xzf go1.21.5.linux-amd64.tar.gz
 echo "export PATH=$PATH:/usr/local/go/bin" >> ~/.bashrc
 popd
Install Firecracker
pushd /tmp
ARCH="$(uname -m)"
release_url="https://github.com/firecracker-microvm/firecracker/releases"
latest=$(basename $(curl -fsSLI -o /dev/null -w  %{url_effective} ${release_url}/latest))
curl -L ${release_url}/download/${latest}/firecracker-${latest}-${ARCH}.tgz \
| tar -xz

# Rename the binary to "firecracker"
mv release-${latest}-$(uname -m)/firecracker-${latest}-${ARCH} /usr/local/bin/firecracker
popd
Install CNI plugins
apt-get install make
git clone https://github.com/containernetworking/plugins.git /tmp/cni-plugins

# Move to the plugins directory
pushd /tmp/cni-plugins

# Build the CNI tools
./build_linux.sh

mv bin/* /opt/cni/bin

git clone https://github.com/awslabs/tc-redirect-tap
pushd tc-redirect-tap/
make install
mv tc-redirect-tap /opt/cni/bin
popd
popd
Create required directories
mkdir /root/fckernels /root/fcsockets /root/fcruntimes
Download Kernel and Runtime root filesystem
cd /root/fcruntimes && wget https://terraform-20231223074656017300000001.s3.amazonaws.com/runtimes/nodejs-runtime.ext4
cd /root/fckernels && wget https://terraform-20231223074656017300000001.s3.amazonaws.com/kernels/vmlinux
Setup systemd

Create the systemd service

cat <<EOF > /etc/systemd/system/windhoek.service
[Unit]
Description=Windhoek
After=network.target

[Service]
ExecStart=/root/windhoek
Restart=always

[Install]
WantedBy=default.target
EOF

Reload the systemd service

systemctl daemon-reload

Enable and start the service

systemctl enable windhoek.service
systemctl start windhoek.service

(back to top)

Usage

Invoking the API

The Windhoek API is started on port 8000. To run a function, send a POST request to http://<your-ip>:8000/invoke with the following payload

{
    "args": {}, // Arguments to the function
    "codeLocation": "", // S3 URL where the function code is stored
    "handler": "" // The function's entrypoint (filename without extension)
}

For more examples, please refer to the Documentation

Roadmap

  • Add Function invocations
  • Add endpoints to delete MicroVms
  • Keep execution environments warm

(back to top)

Contact

Utibeabasi Umanah - @utibeumanah_ - [email protected]

Project Link: https://github.com/runvelocity

(back to top)

About

Windhoek is a small API written in Golang that exposes an invoke route we can call to run a function within a Firecracker VM.

Topics

Resources

Stars

Watchers

Forks

Packages

No packages published