From 8353b899c7170aec89d9a81517d86d08e0fb7095 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=A1clav=20Rozsyp=C3=A1lek?= Date: Tue, 7 Jul 2026 14:51:53 +0200 Subject: [PATCH 1/2] storage: document RBD/Ceph (librbd LUKS2) volume encryption Rework the Volume Encryption admin-guide section to describe the offering-based enablement (an encrypted Disk/Compute Offering) as the primary mechanism, with KMS as an optional passphrase-wrapping layer rather than the only path. Add the supported primary-storage backends and the Ceph/RBD librbd LUKS2 specifics: thin provisioning, copy-on-write encrypted root clones, the libvirt >= 10.1.0 hot-plug requirement, and the KVM host requirements. --- source/adminguide/storage.rst | 64 ++++++++++++++++++++++++++++++----- 1 file changed, 56 insertions(+), 8 deletions(-) diff --git a/source/adminguide/storage.rst b/source/adminguide/storage.rst index 186a1e04eb..c761874698 100644 --- a/source/adminguide/storage.rst +++ b/source/adminguide/storage.rst @@ -621,16 +621,64 @@ Instances with local data volumes on that host. Volume Encryption ^^^^^^^^^^^^^^^^^ -CloudStack supports LUKS-based volume encryption on KVM. Encrypted volumes are managed -through the :ref:`key-management-system`, where you can create and manage the encryption -keys used to protect your data. - -To create an encrypted volume, select a **KMS Key** from the UI when creating the volume, -or supply the key ID via the API. The key must belong to the same zone as the volume. +CloudStack supports LUKS-based volume encryption on KVM. Encryption is enabled through the +storage offering: create a Disk Offering with encryption enabled (for data volumes) or a +Compute Offering with root volume encryption enabled (for root disks), and deploy on a +primary storage that supports encryption. Volumes deployed from such an offering are +encrypted automatically with a per-volume passphrase. Encryption is performed on the KVM +host, so the guest always sees a normal, decrypted disk and there is no encryption device +to manage inside the Instance. + +By default the per-volume passphrase is protected by a single key stored in the database. +Optionally, the :ref:`key-management-system` (KMS, introduced in 4.23) can instead wrap the +passphrase with a key held in an external HSM/KMS provider, in which case you select a +**KMS Key** for the volume. KMS is not required for volume encryption. + +This choice of key protection is independent of the storage backend: every +encryption-capable backend, including Ceph/RBD, works with either the database key or a KMS +key. The encryption engine on the KVM host uses the resulting per-volume passphrase and does +not depend on how that passphrase was protected, so no storage-specific configuration is +needed to use one method or the other. .. warning:: - Deleting the KMS key used to encrypt a volume will render that volume permanently - unrecoverable. + If the key material protecting a volume's passphrase is lost — for example by deleting + the KMS key used to wrap it — that volume becomes permanently unrecoverable. + +Supported primary storage +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* File-based storage (NFS, local, SharedMountPoint) and Dell PowerFlex/ScaleIO — encrypted + with the qemu-native LUKS stack. +* Ceph/RBD — encrypted with **native librbd LUKS2** + (````), for both data disks and root disks. + +The two stacks are not interchangeable: a volume is always decrypted by the same engine +that encrypted it, and they are never mixed on a single volume. + +Ceph/RBD encryption +~~~~~~~~~~~~~~~~~~~ + +For Ceph/RBD, encryption is applied natively by librbd, which preserves Ceph's thin +provisioning and copy-on-write cloning: + +* **Data disks** stay thin — only written blocks consume space (a 1 TB encrypted volume + with 400 GB written uses roughly 400 GB). +* **Root disks** deployed from a template already on the same Ceph cluster are created as + thin copy-on-write clones: each Instance stores only its own (encrypted) writes and + shares the template blocks, so deploying many encrypted Instances from one template uses + far less storage than a full per-Instance copy. When the template is not on the same + cluster (for example on first use from secondary storage), the encrypted root is created + as a full copy instead. + +.. note:: + Attaching an encrypted RBD volume to a **running** Instance (hot-plug) requires + **libvirt >= 10.1.0** on the KVM host. Older libvirt (for example 10.0.0 shipped with + Ubuntu 24.04 LTS) has a bug that breaks hot-plug of encrypted block devices; on such a + host the CloudStack agent refuses the attach with a clear error. Booting an Instance + from an encrypted RBD root disk is **not** affected and works on older libvirt. + +Requirements on the KVM host: ``ceph-common`` (the ``rbd`` CLI) and a QEMU/librbd build +that supports librbd LUKS2 encryption (Ceph Pacific / QEMU 6.1 and newer). To Create a New Volume From a4fd52f4f4e03c798670ea4046c395a84b40ba72 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=A1clav=20Rozsyp=C3=A1lek?= Date: Wed, 8 Jul 2026 13:28:49 +0200 Subject: [PATCH 2/2] storage: note ceph-common (rbd CLI) host dependency for encrypted RBD Encrypted Ceph/RBD volumes require ceph-common (the rbd CLI) on every KVM host - a dependency that non-encrypted RBD does not have, since normal RBD I/O goes through libvirt+librbd. Call this out as an operational trade-off versus the qemu-native LUKS stack, which needs no extra Ceph tooling. --- source/adminguide/storage.rst | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/source/adminguide/storage.rst b/source/adminguide/storage.rst index c761874698..d2432f2768 100644 --- a/source/adminguide/storage.rst +++ b/source/adminguide/storage.rst @@ -677,8 +677,21 @@ provisioning and copy-on-write cloning: host the CloudStack agent refuses the attach with a clear error. Booting an Instance from an encrypted RBD root disk is **not** affected and works on older libvirt. -Requirements on the KVM host: ``ceph-common`` (the ``rbd`` CLI) and a QEMU/librbd build -that supports librbd LUKS2 encryption (Ceph Pacific / QEMU 6.1 and newer). +Requirements on the KVM host: a QEMU/librbd build that supports librbd LUKS2 encryption +(Ceph Pacific / QEMU 6.1 and newer), and ``ceph-common`` (the ``rbd`` CLI). + +.. important:: + **Encrypted RBD adds a host dependency that non-encrypted RBD does not have.** Unlike + the qemu-native LUKS stack used for file-based storage and PowerFlex — which needs no + extra Ceph tooling — librbd RBD encryption requires ``ceph-common`` (the ``rbd`` CLI) to + be installed on **every** KVM host. A standard, non-encrypted KVM + Ceph/RBD deployment + does *not* need it, because normal RBD I/O goes entirely through libvirt and librbd; the + CLI is used only for the librbd LUKS2 *format* and encryption-aware *resize* steps, which + are driven through the ``rbd`` command line. Without ``ceph-common`` on the host, creating, + deploying, or resizing an encrypted RBD volume fails (existing non-encrypted volumes are + unaffected). This is an operational trade-off to weigh against the storage efficiency + librbd provides: install ``ceph-common`` from your distribution's Ceph packages, matching + the librbd version already present on the host, as part of host provisioning. To Create a New Volume