RFC: Golang-based Libvirt CPI for BOSH with Multi-Runtime Support

Status

Proposed

Proposal Date

2025-06-21

Authors

ZPascal

Summary

This proposal introduces a new Cloud Provider Interface (CPI) for BOSH, implemented in Go and based on libvirt. It is intended as a modern, maintainable, and extensible alternative to the current VirtualBox CPI, and supports multiple virtualization backends, including VirtualBox, QEMU/KVM, and container runtimes (e.g., containerd).

This libvirt-based CPI will serve as a centralized and runtime-agnostic integration layer for local or development BOSH deployments. As a reference implementation and first milestone, the new CPI will replace the existing VBox CPI.

Motivation

The existing VirtualBox CPI:

Is minimally maintained and tied to a single backend (VBox).
Has limited extensibility and runtime support.
Is written in Ruby, with a legacy codebase that is harder to modernize.

Meanwhile, libvirt offers:

A standard API for interacting with various virtualization technologies.
Broad backend support, including QEMU/KVM, VirtualBox, LXC, and containerd via libvirt plugins.
Better resource isolation and VM/network emulation capabilities.
Go client libraries (e.g., libvirt/libvirt-go) that align with the direction of modern infrastructure tools.

The community benefits include:

Unified, reusable codebase for local CPI development.
Cost reduction by eliminating duplicated maintenance across multiple single-purpose CPIs.
Improved security and performance through direct integration with native virtualization layers (e.g., KVM).
Better testability and maintainability by adopting Go instead of Ruby.

Approach

We propose:

Developing a new Golang-based CPI that uses libvirt-go to interface with local hypervisors or containers via libvirt.
Supporting multiple backends (initially: VirtualBox, QEMU/KVM, containerd).
Replacing the VirtualBox CPI as the first deliverable and reference implementation.
Supporting standard BOSH CPI contract interfaces (create_vm, delete_vm, attach_disk, etc.).
Enabling configuration via BOSH runtime configs to select the appropriate backend per environment.
Publishing the CPI as an open-source component under the Cloud Foundry or BOSH community GitHub organization.

Sample Use Case

cloud_provider:
  template: libvirt
  properties:
    libvirt:
      uri: "qemu:///system"  # or vbox:///session, or lxc+ssh://...

Alternatives

Continue maintaining the VirtualBox-specific CPI: leads to duplicated effort and fragmented support.
Develop multiple runtime-specific CPIs (e.g., one for containerd, one for KVM): lacks reuse and creates more maintenance overhead.
Use cloud-native CPIs for local deployments (e.g., AWS CPI locally via localstack): adds unnecessary complexity and dependencies.

Impact

Improves maintainability through a single Go-based codebase.
Lowers community cost by replacing a legacy Ruby implementation with modern tooling.
Supports broader use cases, from VMs to container-based deployments.
Enables BOSH to be used more easily in constrained or offline environments using local runtimes.
No changes to existing CPI contract needed — only an alternative implementation.

Prior Art

Other libvirt-based CPIs exist in related projects, such as Terraform libvirt provider.
SPIFFE/SPIRE and HashiCorp Boundary use Go libvirt bindings for local virtualization orchestration.

Unresolved Questions

Should container-based runtimes (e.g., containerd) be supported in phase one, or added later?
How will networking (e.g., NAT, bridges) be handled consistently across backends?
Should the libvirt CPI be scoped only for development/local environments, or also support CI/testing pipelines?

Future Work

Extend backend support to LXC, Podman, or Firecracker.
Add advanced features like volume snapshots, dynamic IP allocation, or network isolation.
Integrate with tooling like BOSH Lite, BOSH Bootloader, or cf-deployment as a drop-in option.
Automate test harnesses for verifying CPI contract compliance across backends.

ZPascal/RFC_BOSH_libvirt_CPI.md