Skip to content
VirtConsole Docs

Ceph RBD storage

Ceph RBD (RADOS Block Device) provides distributed, replicated block storage. Connecting a Ceph pool to VirtConsole gives you shared storage that supports live migration between hypervisors and thin provisioning.

Before you begin

Section titled “Before you begin”
  • An operational Ceph cluster with either replication or erasure coding.
  • At least one hypervisor with the agent installed.

Create Ceph credentials

Section titled “Create Ceph credentials”

On the Ceph cluster, create a client key with access to your pool:

Terminal window
ceph auth get-or-create client.virtconsole mon 'profile rbd' osd 'profile rbd pool=<POOL_NAME>'

Expected output:

[client.virtconsole]
        key = AQAJmABpozPUFxAAMSjKlPuGYA6C3svHvJyFNQ==

Save the key. You need it twice below.

Prepare each hypervisor

Section titled “Prepare each hypervisor”

Run these steps as root.

  1. Install the required packages on every hypervisor:

    Terminal window
    apt install -y qemu-block-extra ceph-common   # Debian / Ubuntu
    dnf install -y qemu-kvm-block-rbd ceph-common # RHEL

  2. On the first hypervisor, create a libvirt secret:

    Terminal window
    cat > secret.xml <<EOF
    <secret ephemeral='no' private='no'>
       <usage type='ceph'>
        <name>client.virtconsole secret</name>
       </usage>
    </secret>
    EOF
    virsh secret-define --file secret.xml

    Expected output: Secret 88ced2a0-8b9c-44bd-9efb-1979cac33f24 created. Save the UUID.

  3. Set the secret value to the Ceph key from above:

    Terminal window
    virsh secret-set-value --secret <UUID> <USER_KEY>

    Expected output: Secret value set.

  4. Edit /etc/ceph/ceph.conf with your monitors and the client key:

    /etc/ceph/ceph.conf
    [global]
    mon_host = <MON_HOST_1> <MON_HOST_2> <MON_HOST_3>
    

    [client.virtconsole]
            key = AQAJmABpozPUFxAAMSjKlPuGYA6C3svHvJyFNQ==

  5. Verify connectivity:

    Terminal window
    ceph version --id virtconsole

    The command prints the Ceph version when authentication works.

  6. Copy /etc/libvirt/secrets from the first hypervisor to every other hypervisor, then restart libvirt on each:

    Terminal window
    systemctl restart libvirtd

Add the storage in the panel

Section titled “Add the storage in the panel”

In the admin panel go to Infrastructure > Storage and click Add storage. The 5-step wizard opens (Backend, Variant, Configure, Probe, Confirm); pick Ceph RBD on the Backend step, then on Configure fill in:

Field What to enter
Username (client.) virtconsole (the client name you created above, without the client. prefix).
Libvirt Secret UUID The UUID virsh secret-define printed in step 2.
Pool Name Your Ceph pool name.
Max size (GB, 0 = unlimited) The oversubscription limit for this pool, or 0 for unlimited.
Cache Leave at the default (Default (None)).
Storage class Any, NVMe, SSD or HDD, so plans can target the tier.

Ceph RBD supports thin provisioning (like QCOW2), so you can allocate more virtual storage than physical capacity. Monitor pool utilization to keep oversubscription safe.

Common problems

Section titled “Common problems”
  • Instances fail to start on the pool. The libvirt secret is missing on that hypervisor, or has a different UUID. Re-copy /etc/libvirt/secrets and restart libvirtd.
  • Authentication errors in the agent log. The key in ceph.conf does not match the secret value. Re-run ceph auth get client.virtconsole and compare.
Section titled “Related”