Minor additions to quickstart docs

docs/quick-start.md

@@ -1,5 +1,32 @@
 # Getting started with flintlock
 
+<!--
+To update the TOC, install https://github.com/kubernetes-sigs/mdtoc
+and run: mdtoc -inplace docs/quick-start.md
+-->
+
+<!-- toc -->
+- [Configure network](#configure-network)
+  - [Create kvm network](#create-kvm-network)
+  - [Create and connect tap device](#create-and-connect-tap-device)
+- [On MacOS](#on-macos)
+- [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 -->
+
+
 ## Configure network
 
 If you are using wired connection, you can skip this and jump straight to the
@@ -79,13 +106,17 @@ virsh net-dhcp-leases default
 
 ## On MacOS
 
+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 reset of the instructions on this page on that machine.
 
 ## Containerd
 
@@ -135,6 +166,9 @@ sudo mkdir -p /run/containerd-dev/
 sudo containerd --config /etc/containerd/config-dev.toml
 ```
 
+ContainerD will about 100 lines at boot, most will be about loading plugins.
+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:
 
@@ -183,24 +217,77 @@ 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 bothe 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 \
+  < hack/scripts/payload/CreateMicroVM.json
+```
+
+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 good tool to test gRPC endpoint.
 
-### Import
+#### Import
+
+To import reignite 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.
+
+#### Example
+
+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