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
   • Prerequisites
   • Installation
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)