Skip to content

Commit

Permalink
Minor additions to quickstart docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@Callisto13
Callisto13 committed Oct 22, 2021
1 parent 3d09bf1 commit 07b0ca0
Show file tree
Hide file tree
Showing 2 changed files with 138 additions and 27 deletions.
163 changes: 137 additions & 26 deletions docs/quick-start.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,45 @@
# Getting started with flintlock

<!--
To update the TOC, install https://github.com/kubernetes-sigs/mdtoc
and run: mdtoc -inplace docs/quick-start.md
-->

<!-- toc -->
- [MacOS Users](#macos-users)
- [Configure network](#configure-network)
- [Create kvm network](#create-kvm-network)
- [Create and connect tap device](#create-and-connect-tap-device)
- [Containerd](#containerd)
- [Create thinpool](#create-thinpool)
- [Configuration](#configuration)
- [Start containerd](#start-containerd)
- [Set up Firecracker](#set-up-firecracker)
- [Set up and start flintlock](#set-up-and-start-flintlock)
- [Interacting with the service](#interacting-with-the-service)
- [grpc-client-cli](#grpc-client-cli)
- [Example](#example)
- [BloomRPC](#bloomrpc)
- [Import](#import)
- [Example](#example-1)
- [Troubleshooting](#troubleshooting)
- [flintlockd fails to start with <code>failed to reconcile vmid</code>](#flintlockd-fails-to-start-with-)
<!-- /toc -->

## MacOS Users

Flintlock and flintlock tests are only compatible with Linux. We recommend that
non-linux users provision a Linux VM in which to work.

You can use Vagrant:

```
vagrant up
```

It will create a new pre-configured machine ready to use.
Run the rest of the instructions on this page on that machine.

## Configure network

If you are using wired connection, you can skip this and jump straight to the
Expand All @@ -11,6 +51,15 @@ tap device" and use `default`. We recommend using a dedicated network to avoid
interference from other kvm machines or processes like IP or MAC address
conflict.

### Install packages and start `libvirtd`

```bash
sudo apt install qemu qemu-kvm libvirt-clients libvirt-daemon-system virtinst bridge-utils

sudo systemctl enable libvirtd
sudo systemctl start libvirtd
```

### Create kvm network

Create the `flintlock.xml` file (feel free to change the IP range):
Expand All @@ -23,7 +72,7 @@ Create the `flintlock.xml` file (feel free to change the IP range):
<port start='1024' end='65535'/>
</nat>
</forward>
<bridge name='rgntbr0' stp='on' delay='0'/>
<bridge name='flkbr0' stp='on' delay='0'/>
<ip address='192.168.100.1' netmask='255.255.255.0'>
<dhcp>
<range start='192.168.100.2' end='192.168.100.254'/>
Expand All @@ -35,9 +84,9 @@ Create the `flintlock.xml` file (feel free to change the IP range):
Define, start and set autostart on the `flintlock` network:

```
virsh net-define flintlock.xml
virsh net-start flintlock
virsh net-autostart flintlock
sudo virsh net-define flintlock.xml
sudo virsh net-start flintlock
sudo virsh net-autostart flintlock
```

Now you should see the network in the network list:
Expand All @@ -54,17 +103,19 @@ virsh net-list

```bash
tapName=tap0
bridge=rgntbr0
bridge=flkbr0
sudo ip tuntap add ${tapName} mode tap
sudo ip link set ${tapName} master ${bridge} up
```

Check with `ip link ls`.

You can add a function into your bashrc/zshrc:

```bash
function vir-new-tap() {
tapName=${1:=tap0}
bridge=${2:=rgntbr0}
bridge=${2:=flkbr0}

sudo ip tuntap add ${tapName} mode tap
sudo ip link set ${tapName} master ${bridge} up
Expand All @@ -74,35 +125,38 @@ function vir-new-tap() {
You can check the DHCP leases with `virsh`:

```bash
virsh net-dhcp-leases default
sudo virsh net-dhcp-leases default
```

## On MacOS

You can use Vagrant:

```
vagrant up
```
## Containerd

It will create a new pre-configured machine ready to use.
[Install ContainerD](https://github.com/containerd/containerd/releases).

## Containerd
_RunC is not required; Flintlock only uses the snapshotter._

### Create thinpool

Easy quick-start option is to run the `hack/scripts/devpool.sh` script as root.
Flintlock relies on ContainerD's devicemapper snapshotter to provide filesystem
devices for Firecracker microvms. Some configuration is required.

The easy quick-start option is to run the `hack/scripts/devpool.sh` script as root.
I know, it's not recommended in general, and I'm happy you think it's not a good
way to do things, read the comments in the script for details.

```bash
sudo apt update
sudo apt install -y dmsetup bc

sudo ./hack/scripts/devpool.sh
```

Verify with `sudo dmsetup ls`.

### Configuration

Save this config to `/etc/containerd/config-dev.toml`.

```toml
# /etc/containerd/config-dev.toml
version = 2

root = "/var/lib/containerd-dev"
Expand Down Expand Up @@ -135,6 +189,11 @@ sudo mkdir -p /run/containerd-dev/
sudo containerd --config /etc/containerd/config-dev.toml
```

containerd will log about 100 lines at boot, most will be about loading plugins, and we recommended
scrolling up to ensure that the devmapper plugin loaded successfully.

Towards the end you should see `containerd successfully booted in 0.055357s`.

To reach our new dev containerd, we have to specify the `--address` flag,
for example:

Expand Down Expand Up @@ -183,24 +242,76 @@ make build

NET_DEVICE=$(ip route show | awk '/default/ {print $5}')

./bin/flintlockd run \
sudo ./bin/flintlockd run \
--containerd-socket=/run/containerd-dev/containerd.sock \
--parent-iface="${NET_DEVICE}"
```

## BloomRPC
You should see it start successfully with similar output:
```
INFO[0000] reignited, version=undefined, built_on=undefined, commit=undefined
INFO[0000] reignited grpc api server starting
INFO[0000] starting microvm controller
INFO[0000] starting microvm controller with 1 workers controller=microvm
INFO[0000] resyncing microvm specs controller=microvm
INFO[0000] Resyncing specs action=resync controller=microvm namespace=ns
INFO[0000] starting event listener controller=microvm
INFO[0000] Starting workersnum_workers1 controller=microvm
```

## Interacting with the service

We recommend using one of the following tools to send requests to the Flintlock server.
There are both GUI and a CLI option.

### grpc-client-cli

Install the [grpc-client-cli](grpcurl).

Use the `./hack/scripts/send.sh` script.

#### Example

To created a MicroVM:

```
./hack/scripts/send.sh \
--method CreateMicroVM
```

In the terminal where you started the Reignite server, you should see in the logs that the MircoVM
has started.

### BloomRPC

[BloomRPC][bloomrpc] is a GUI tool to test gRPC endpoints.

#### Import

To import Flintlock protos into the Bloom GUI:

1. Click `Import Paths` on the left-hand menu bar and add `<absolute-repo-path>/api` to the list
1. Click the import `+` button and select `reignite/api/services/microvm/v1alpha1/microvms.proto`

All available endpoints will be visible in a nice tree view.

[BloomRPC][bloomrpc] is a good tool to test gRPC endpoint.
#### Example

### Import
To create a MircoVM, select the `CreateMicroVM` endpoint in the left-hand menu.
Replace the sample request JSON in the left editor panel with [this example](hack/scripts/payload/CreateMicroVM.json).
Click the green `>` in the centre of the screen. The response should come immediately.

Use the "Import Paths" button and add `$repo/api` to the list. All available
endpoints will be visible in a nice tree view.
In the terminal where you started the Reignite server, you should see in the logs that the MircoVM
has started.

### Example
To delete the MircoVM, select the `DeleteMicroVM` endpoint in the left-hand menu.
Replace the sample request JSON in the left editor panel with [this example](hack/scripts/payload/DeleteMicroVM.json).
Take care to ensure the values match those of the MicroVM you created earlier.
Click the green `>` in the centre of the screen. The response should come immediately.

TODO: Example CreateVM Payload
**Note: there are example payloads for other endpoints, but not all are implemented at present.**

[grpcurl]: https://github.com/vadimi/grpc-client-cli
[bloomrpc]: https://github.com/uw-labs/bloomrpc

## Troubleshooting
Expand Down
2 changes: 1 addition & 1 deletion hack/scripts/send.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ method="ListMicroVMs"
if ! which grpcurl >/dev/null 2>/dev/null; then
echo "!!! grpcurl is not installed. Please install this awesome tool." >&2
echo "" >&2
echo " go install github.com/vadimi/grpc-client-cli/cmd/[email protected]" >&2
echo " go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest" >&2

exit 1
fi
Expand Down

0 comments on commit 07b0ca0

Please sign in to comment.