feat: Add provider instructions

Cloud-Hypervisor vs Firecracker

docs/guides/cli.md

@@ -0,0 +1,40 @@
+---
+title: flintlockd CLI ref
+---
+
+```console
+flintlockd run -h
+Start running the flintlock API
+
+Usage:
+  flintlockd run [flags]
+
+Flags:
+      --basic-auth-token string          The token to use for very basic token based authentication.
+      --bridge-name string               The name of the Linux bridge to attach tap devices to by default
+      --cloudhypervisor-bin string       The path to the cloud hypervisor binary to use. (default "cloud-hypervisor-static")
+      --cloudhypervisor-detach           If true the child cloud hypervisor processes will be detached from the parent flintlock process. (default true)
+      --containerd-kernel-ss string      The name of the snapshotter to use with containerd for kernel/initrd images. (default "native")
+      --containerd-ns string             The name of the containerd namespace to use. (default "flintlock")
+      --containerd-socket string         The path to the containerd socket. (default "/run/containerd/containerd.sock")
+      --debug-endpoint string            The endpoint for the debug web server to listen on. It must include a port (e.g. localhost:10500).  An empty string means disable the debug endpoint.
+      --default-provider string          The name of the microvm provider to use by default if not supplied in the create request. (default "firecracker")
+      --deleteMicroVM-timeout duration   The timeout for deleting a microvm. (default 10s)
+      --firecracker-bin string           The path to the firecracker binary to use. (default "firecracker")
+      --firecracker-detach               If true the child firecracker processes will be detached from the parent flintlock process. (default true)
+      --grpc-endpoint string             The endpoint for the gRPC server to listen on. (default "localhost:9090")
+      -h, --help                         Help for run
+      --insecure                         Run the gRPC server insecurely (i.e. without TLS). Not recommended.
+      --parent-iface string              The parent iface for the network interfaces. Note it could also be a bond
+      --resync-period duration           Reconcile the specs to resynchronise them based on this period. (default 10m0s)
+      --state-dir string                 The directory to use for the as the root for runtime state. (default "/var/lib/flintlock")
+      --tls-cert string                  Path to the certificate to use for TLS.
+      --tls-client-ca string             Path to the certificate to use when validating client certificates.
+      --tls-client-validate              Validate the certificates of clients calling the gRPC server.
+      --tls-key string                   Path to the key to use for TLS.
+
+Global Flags:
+      --log-format string   The format of the logging output. Can be 'text' or 'json'. (default "text")
+      --log-output string   The output for logging. Supply a file path or one of the special values of 'stdout' and 'stderr'. (default "stderr")
+  -v, --verbosity int       The verbosity level of the logging. A level of 2 and above is debug logging. A level of 9 and above is tracing.
+```

docs/guides/providers.md

@@ -0,0 +1,115 @@
+---
+title: MicroVM Providers
+---
+
+Flintlock MicroVMs can be provided by either [`firecracker`][fc] or
+[`cloudhypervisor`][ch].
+
+## Setting a default provider
+
+If `flintlockd` is started with zero explicit instruction, the default provider
+will be set to `firecracker`.
+
+To change this to `cloudhypervisor`, start the service with the
+`--default-provider` flag set:
+
+```bash
+flintlockd run --default-provider cloudhypervisor [other flags]
+```
+
+If managing the service via the `systemd` service file, add the following to
+`/etc/opt/flintlockd/config.yaml`:
+
+```yaml
+default-provider: cloudhypervisor
+```
+
+:::tip
+
+Note that the service will only recognise the values `firecracker` and
+`cloudhypervisor`. Any variation of those will cause the service to fail at
+start.
+
+:::
+
+## Setting the provider binary paths
+
+Unless explicitly instructed, `flintlockd` will expect the Firecracker binary
+to be somewhere on the `$PATH` under the name `firecracker`, for example
+`/usr/local/bin/firecracker`.
+
+Similarly, `flintlockd` will expect the Cloud-Hypervisor binary to be on the
+`$PATH` under the name `cloud-hypervisor-static`.
+
+To configure either of these start the service with the following flags:
+
+```console
+--firecracker-bin
+--cloudhypervisor-bin
+```
+
+Or set the values in `/etc/opt/flintlockd/config.yaml`:
+
+```yaml
+cloudhypervisor-bin: <path>
+firecracker-bin: <path>
+```
+
+:::danger Important
+
+`flintlockd` will not install either provider binaries on the host device for
+you. Operators must ensure that this is done before using the service.
+
+:::
+
+## Overriding the default provider for single MicroVMs
+
+If both providers are "loaded" (ie, both provider binaries have been set and/or
+discovered by `flintlockd` at boot), you can choose which to use on a per-mvm
+basis.
+
+### With a `flintlock` client
+
+To set a one-off provider with a generic flintlock client, add the key to the spec:
+
+```json
+{
+    "id": "mvm0",
+    "namespace": "ns0",
+    "provider": "firecracker",
+    // ...
+}
+```
+
+### With CAPMVM
+
+To set a on-off provider when using CAPMVM, set the field(s) in the manifest:
+
+```yaml
+...
+---
+apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
+kind: MicrovmMachineTemplate
+metadata:
+  name: test-control-plane
+  namespace: default
+spec:
+  template:
+    spec:
+      provider: "firecracker"
+...
+---
+apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
+kind: MicrovmMachineTemplate
+metadata:
+  name: test-md-0
+  namespace: default
+spec:
+  template:
+    spec:
+      provider: "cloudhypervisor"
+...
+```
+
+[fc]: https://firecracker-microvm.github.io/
+[ch]: https://www.cloudhypervisor.org/

sidebars.js

@@ -99,7 +99,18 @@ const sidebars = {
       items: [
         'guides/hardware',
         'guides/networking',
-        'guides/flintlock',
+        {
+          type: 'category',
+          label: 'Flintlock',
+          link: {
+            type: 'doc',
+            id: 'guides/flintlock',
+          },
+          items: [
+            'guides/cli',
+          ]
+        },
+        'guides/providers',
         'guides/images',
         'guides/cluster-api',
         'guides/capmvm',