Libvirt-provider - usage documentation¶

Overview¶

libvirt-provider enables interaction with libvirt for managing virtual machine instances, integrating with multiple plugins for networking, storage, and more. It provides a flexible architecture to handle resources like VMs, volumes, and networking interfaces, with built-in support for garbage collection, volume size resyncing, and health monitoring. This guide provides a comprehensive usage flow, including configuration, flags, and practical examples, to get your libvirt-provider instance running.

Prerequisites¶

Before you begin, make sure you have the prerequisites described here.

Building from source¶

To build libvirt-provider from the source:

Clone the repository

To bring up and start locally the libvirt-provider project, you first need to clone the repository.
```
git clone git@github.com:ironcore-dev/libvirt-provider.git
cd libvirt-provider
```
Build the libvirt-provider
```
make build
```

Configuration¶

libvirt-provider is configured via command-line flags. To see the full list of configuration options, run:

libvirt-provider -h

Required flags¶

The following flags are required for the application to run properly:

--supported-machine-classes (Path to the supported machine classes file). Sample machine-classes.json can be found here.

Running libvirt-provider¶

Below is an example of configuring and running libvirt-provider with various flags:

go run cmd/libvirt-provider/main.go \
  --address /var/run/iri-machinebroker.sock \
  --streaming-address ":20251" \
  --base-url "http://localhost:20251" \
  --libvirt-socket /var/run/libvirt/libvirt-sock \
  --libvirt-address "unix:///var/run/libvirt/libvirt-sock" \
  --libvirt-uri "qemu:///system" \
  --enable-hugepages \
  --qcow2-type "qcow2" \
  --volume-cache-policy "writeback" \
  --servers-metrics-address ":9090" \
  --servers-health-check-address ":8080" \
  --gc-vm-graceful-shutdown-timeout 5m \
  --gc-resync-interval 1m \
  --supported-machine-classes "/home/libvirt-provider/machine-classes.json"

Once the libvirt-provider is started, which will handle various tasks like connecting to libvirt, managing VMs, and exposing various HTTP and gRPC endpoints for metrics, health checks, and more.

Server endpoints¶

gRPC endpoint: Exposes various gRPC services to manage virtual machines. Default address: unix:///var/run/iri-machinebroker.sock
Metrics server: Provides Prometheus-compatible metrics for monitoring. Default address: "" (if configured)
Health check server: Provides a simple liveness check endpoint. Default address: :8181 (if configured)
Streaming server: Streams VM status and events. Default address: :20251 (if configured)

You can access these services by connecting to their respective addresses.

Logs and debugging¶

The service logs are critical for troubleshooting issues. By default, the service uses the zap logging framework, which supports structured logging and multiple log levels.

To change the logging level:

go run cmd/libvirt-provider/main.go --zap-log-level debug

For more advanced troubleshooting, you can enable additional logging at different points in the execution flow.

Troubleshooting¶

Here are some common issues you might encounter:

Libvirt connection errors¶

If the libvirt socket or URI is incorrectly configured, the service will fail to connect to the hypervisor. Ensure that:

The libvirt socket path is correct.
The libvirt URI is accessible (e.g., qemu:///system or unix:///var/run/libvirt/libvirt-sock).

VM launch failures¶

If VMs fail to launch, check the logs for specific errors related to machine classes or network plugins. You may need to adjust the supported machine classes or verify your network plugin configuration.