Skip to content

README.md: Update libvirt examples #151

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cgwalters merged 1 commit into from
Nov 18, 2025
Merged

README.md: Update libvirt examples #151

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 29 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,31 +46,37 @@ with the `containers.bootc=1` label: `bcvk images list`

The libvirt commands provide comprehensive integration with libvirt infrastructure for managing bootc containers as persistent VMs.

#### Running a bootc container as a libvirt VM
#### Starting a bootc container as a libvirt VM

```bash
# Basic libvirt VM creation with default settings (2GB RAM, 2 CPUs, 20GB disk)
bcvk libvirt run quay.io/fedora/fedora-bootc:42
bcvk libvirt run quay.io/centos-bootc/centos-bootc:stream10

# Note requirement for --filesystem with the generic Fedora bootc base images
bcvk libvirt run --filesystem btrfs quay.io/fedora/fedora-bootc:43

# Custom VM with specific resources and name
bcvk libvirt run --name my-fedora-vm --memory 4096 --cpus 4 --disk-size 50G quay.io/fedora/fedora-bootc:42
bcvk libvirt run --name example-vm --memory 4096 --cpus 4 --disk-size 50G quay.io/centos-bootc/centos-bootc:stream10

# Run VM with port forwarding and volume mounts
bcvk libvirt run --name web-server --port 8080:80 --volume /host/data:/mnt/data quay.io/centos-bootc/centos-bootc:stream10
# This example forwards a port and bind mounts content from the host
Copy link

@gemini-code-assist gemini-code-assist bot Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The comment mentions "bind mounts", which could be confusing as there is a separate --bind flag for automatic mounting. This example uses --volume, which creates a virtiofs share that requires manual mounting in the guest. To avoid confusion, it would be clearer to refer to this as a "volume mount". The previous comment was more accurate and less ambiguous.

Suggested change
# This example forwards a port and bind mounts content from the host
# Run VM with port forwarding and volume mounts

bcvk libvirt run --name web-server --port 8080:80 --volume /host/data:/mnt/data localhost/myimage

# Run VM in background and automatically SSH into it
bcvk libvirt run --detach --ssh --name test-vm quay.io/fedora/fedora-bootc:42
# Bind mount the host container storage for faster updates
bcvk libvirt run --update-from-host --name devvm localhost/myimage
```

#### Managing libvirt VMs
#### Using and managing libvirt VMs

After initializing a VM a common next step is `bcvk lbivirt ssh <vm name>`.
bcvk defaults to injecting SSH keys via [systemd credentials](https://systemd.io/CREDENTIALS/).
The private key is specific to the VM and is stored in the domain metadata.

Other operations:

```bash
# List all bootc-related libvirt domains
bcvk libvirt list

# SSH into a running VM
bcvk libvirt ssh my-fedora-vm

# Stop a running VM
bcvk libvirt stop my-fedora-vm

Expand All @@ -81,20 +87,24 @@ bcvk libvirt start my-fedora-vm
bcvk libvirt inspect my-fedora-vm

# Remove a VM and its resources
bcvk libvirt rm my-fedora-vm
bcvk libvirt rm -f my-fedora-vm
```

#### Advanced libvirt workflows
## Other operations

```bash
# Upload a pre-built disk image to libvirt storage
bcvk to-disk quay.io/fedora/fedora-bootc:42 /tmp/fedora.img
bcvk libvirt upload /tmp/fedora.img --name fedora-base
The `bcvk libvirt run` command wraps `bcvk to-disk` which in
turns wraps `bootc install to-disk` in an ephemeral VM. In
some cases, you may want to create a disk image directly.

# Run with custom filesystem and network settings
bcvk libvirt run --filesystem xfs --network bridge quay.io/centos-bootc/centos-bootc:stream10
```bash
# Generate a disk image in qcow2 format.
bcvk to-disk --format=qcow2 localhost/my-container-image output-disk.qcow2
```

Note that at the current time, this project is not scoped to
output other virtualization formats. The [bootc image builder](https://github.com/osbuild/bootc-image-builder)
is one project that offers those.

## Goals

This project aims to implement part of
Expand Down