diff --git a/docs/component-info/cli.md b/docs/component-info/cli.md new file mode 100644 index 0000000..e6712ad --- /dev/null +++ b/docs/component-info/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. +``` diff --git a/docs/component-info/providers.md b/docs/component-info/providers.md new file mode 100644 index 0000000..165b6b9 --- /dev/null +++ b/docs/component-info/providers.md @@ -0,0 +1,122 @@ +--- +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: +firecracker-bin: +``` + +:::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 one-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" +... +``` + +:::info + +This CAPMVM field is optional. Omit if you are happy using the default as +configured by your operator. + +::: + +[fc]: https://firecracker-microvm.github.io/ +[ch]: https://www.cloudhypervisor.org/ diff --git a/sidebars.js b/sidebars.js index a45b6e2..cecfb57 100644 --- a/sidebars.js +++ b/sidebars.js @@ -92,7 +92,18 @@ const sidebars = { }, 'component-info/hardware', 'component-info/networking', - 'component-info/flintlock', + { + type: 'category', + label: 'Flintlock', + link: { + type: 'doc', + id: 'component-info/flintlock', + }, + items: [ + 'component-info/cli', + ] + }, + 'component-info/providers', 'component-info/images', 'component-info/cluster-api', 'component-info/capmvm',