This is an automated email from the ASF dual-hosted git repository.
harikrishna-patnala pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/cloudstack-documentation.git
The following commit(s) were added to refs/heads/main by this push:
new a099b8fa Feature: Key Management Service (KMS) (#634)
a099b8fa is described below
commit a099b8fa3cc42cd610c4ebf3e77254f59a916f6b
Author: Vishesh <[email protected]>
AuthorDate: Tue Jun 30 10:10:58 2026 +0530
Feature: Key Management Service (KMS) (#634)
---
source/_static/images/kms-add-hsm-profile.png | Bin 0 -> 73581 bytes
source/_static/images/kms-architecture.png | Bin 0 -> 46983 bytes
source/_static/images/kms-create-key.png | Bin 0 -> 62887 bytes
source/_static/images/kms-rotate-key.png | Bin 0 -> 22476 bytes
source/adminguide/index.rst | 2 +-
source/adminguide/kms.rst | 215 ++++++++++++++++++++++++++
source/adminguide/storage.rst | 22 ++-
7 files changed, 237 insertions(+), 2 deletions(-)
diff --git a/source/_static/images/kms-add-hsm-profile.png
b/source/_static/images/kms-add-hsm-profile.png
new file mode 100644
index 00000000..dfe4dcfb
Binary files /dev/null and b/source/_static/images/kms-add-hsm-profile.png
differ
diff --git a/source/_static/images/kms-architecture.png
b/source/_static/images/kms-architecture.png
new file mode 100644
index 00000000..683adbc7
Binary files /dev/null and b/source/_static/images/kms-architecture.png differ
diff --git a/source/_static/images/kms-create-key.png
b/source/_static/images/kms-create-key.png
new file mode 100644
index 00000000..5849a098
Binary files /dev/null and b/source/_static/images/kms-create-key.png differ
diff --git a/source/_static/images/kms-rotate-key.png
b/source/_static/images/kms-rotate-key.png
new file mode 100644
index 00000000..a7bbf002
Binary files /dev/null and b/source/_static/images/kms-rotate-key.png differ
diff --git a/source/adminguide/index.rst b/source/adminguide/index.rst
index 040ad1cd..5fcb05f0 100644
--- a/source/adminguide/index.rst
+++ b/source/adminguide/index.rst
@@ -160,7 +160,7 @@ Managing the Cloud
:maxdepth: 4
management
-
+ kms
System Reliability and Availability
-----------------------------------
diff --git a/source/adminguide/kms.rst b/source/adminguide/kms.rst
new file mode 100644
index 00000000..1e0f7d61
--- /dev/null
+++ b/source/adminguide/kms.rst
@@ -0,0 +1,215 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+.. _key-management-system:
+
+Key Management System (KMS)
+============================
+
+Introduced in Apache CloudStack 4.23, the Key Management System (KMS) lets you
encrypt
+storage volumes using keys stored in a hardware security module (HSM).
+Previously, volume passphrases were encrypted with a single key stored in the
+database. If no KMS key is provided, CloudStack falls back to this legacy
behavior.
+
+.. _kms-architecture:
+
+Architecture and Design
+-----------------------
+
+KMS is built around a two-tier key hierarchy to protect data at rest:
+
+- **KEK (Key Encryption Key)** — The master key that never leaves the secure
backend. KEKs
+ are stored in and managed by the configured KMS provider.
+- **DEK (Data Encryption Key)** — The key that encrypts the actual data (e.g.,
Volumes).
+ DEKs are stored wrapped by the KEK and are only decrypted in memory when
needed.
+
+.. image:: /_static/images/kms-architecture.png
+ :align: center
+ :alt: KMS architecture diagram showing providers, KEK, DEK, and Volume Data
layers
+
+
+Pluggable Provider Framework
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The KMS architecture is designed to be extensible. CloudStack currently ships
two providers:
+
+- **Database Provider** — A built-in fallback provider that stores
+ wrapped keys in the CloudStack database. Suitable for environments without
dedicated HSM
+ hardware.
+- **PKCS#11 HSM Provider** — Integrates with dedicated Hardware
+ Security Module devices via the PKCS#11 standard allowing integration with
+ various HSM providers.
+
+HSM Profiles
+^^^^^^^^^^^^
+Each KMS Key is stored in a Hardware Security Module. The root admin registers
+**HSM Profiles** that capture the connection configuration for a specific HSM
device
+(e.g., PKCS#11 library path, slot, PIN). Sensitive fields such as
+PINs and passwords are automatically encrypted at rest and masked in responses.
+
+.. note::
+ HSM Profiles can be created only by root administrators and can be scoped to
a zone,
+ account, or can be made global (available to all zones).
+
+.. _kms-hsm-profiles:
+
+Managing HSM Profiles
+---------------------
+
+Before creating a KMS key, an administrator must register an HSM
+Profile.
+
+Adding an HSM Profile
+^^^^^^^^^^^^^^^^^^^^^
+
+#. Log in to the CloudStack UI as a root administrator.
+
+#. In the left navigation bar, click **HSM Profile** under **Key Management**.
+
+#. Click on **Add HSM Profile +**.
+
+#. Provide the following details:
+
+ - **Name** — A unique name for the profile.
+ - **Zone** — The zone this profile is scoped to. Leave blank to make it
available to all zones.
+ - **Vendor Name** — The HSM device vendor.
+ - **System** — Check this to make the profile globally available. Uncheck
to scope it to an account or zone.
+ - **Details** — Protocol-specific key-value pairs such as ``library``,
``slot``, and
+ ``pin`` for PKCS#11.
+
+ .. image:: /_static/images/kms-add-hsm-profile.png
+ :align: center
+ :alt: Add HSM Profile dialog
+
+#. Click **OK**.
+
+
+.. note::
+ If access to the HSM is lost, CloudStack will be unable to access
+ volumes encrypted with the keys managed by this HSM profile and the
+ volumes will be inaccessible.
+
+.. note::
+ Sensitive fields (PINs, passwords) are automatically masked in the UI and
API responses
+ after the profile is created.
+
+.. note::
+ The operator has to ensure that the required HSM libraries are installed on
+ all the management servers and depending on the HSM provider, there might be
+ some additional configuration required on each of the management servers.
+
+.. _kms-key-lifecycle:
+
+Managing KMS Keys
+-----------------
+
+KMS Keys (Key Encryption Keys / KEKs) are **zone-scoped**: a key created in
one zone
+cannot be used in another. Keys can be created by users and administrators.
+
+Creating a KMS Key
+^^^^^^^^^^^^^^^^^^
+
+#. Log in to the CloudStack UI.
+
+#. In the left navigation bar, click **KMS Keys** under **Key Management**.
+
+#. Click **Create KMS Key +**.
+
+#. Provide the following details:
+
+ - **Name** — A name for the key.
+ - **Description** — An optional description.
+ - **Zone** — The zone in which the key will be valid.
+ - **HSM Profile** — The HSM profile to use as the backend for this key.
+ - **Key Size** — Bits for the KEK: ``128``, ``192``, or ``256`` (default).
+
+ .. image:: /_static/images/kms-create-key.png
+ :align: center
+ :alt: Create KMS Key dialog
+
+#. Click **OK**. The key is created in the specified HSM and becomes available
for
+ encrypting volumes in the selected zone.
+
+.. _kms-key-rotation:
+
+Rotating a KMS Key
+^^^^^^^^^^^^^^^^^^
+
+Key rotation generates a new version of the KEK and automatically schedules
background
+re-encryption of all DEKs protected by the old version. This is an
asynchronous operation.
+
+
+#. In the left navigation bar, click **KMS Keys** under **Key Management**.
+
+#. Open the Details page for the key you want to rotate.
+
+#. Click the **Rotate KMS Key** button.
+
+ .. image:: /_static/images/kms-rotate-key.png
+ :align: center
+ :alt: Rotate Key option in KMS Keys list
+
+#. Confirm the rotation. A background job is created that progressively
rewraps all DEKs
+ to the new KEK version without ever exposing the plaintext DEKs.
+
+.. note::
+ The rewrapping job runs in batches. The ``kms.rewrap.batch.size`` and
+ ``kms.rewrap.interval.ms`` settings control how quickly DEKs are
re-encrypted
+ after rotation (see :ref:`kms-configuration`).
+
+.. _kms-volume-migration:
+
+Migrating Existing Volumes to KMS
+----------------------------------
+
+Existing volumes that use older passphrase-based encryption can be migrated to
KMS-managed
+envelope encryption without data loss. This is an administrator-only operation
and is
+performed using the ``migrateVolumesToKMS`` API. The migration runs as an
asynchronous
+background job.
+
+.. note::
+ Migrated volumes will be re-encrypted under the KMS envelope encryption
model, removing
+ the dependency on a static passphrase. Scope the migration by zone,
account, or domain,
+ or provide specific volume IDs for selective migration.
+
+For full API parameter details, see the
+`CloudStack API Reference <https://cloudstack.apache.org/api/>`_.
+
+.. _kms-configuration:
+
+KMS Configuration Settings
+--------------------------
+
+The following global configuration settings are available to tune KMS
behaviour. They can
+be found under **Global Settings** in the CloudStack UI.
+
+.. cssclass:: table-striped table-bordered table-hover
+
+=============================== =============
=================================================
+Configuration Default Description
+=============================== =============
=================================================
+``kms.dek.size.bits`` ``256`` Size of generated DEKs in bits.
Valid values
+ are ``128``, ``192``, and
``256``.
+``kms.retry.count`` ``3`` Number of retry attempts on
transient KMS
+ operation failures.
+``kms.retry.delay.ms`` ``1000`` Base delay in milliseconds for
exponential
+ back-off between retry attempts.
+``kms.operation.timeout.sec`` ``30`` Timeout in seconds for a single
KMS
+ cryptographic operation.
+``kms.rewrap.batch.size`` ``50`` Number of DEKs to rewrap per
background job
+ iteration during KEK rotation.
+``kms.rewrap.interval.ms`` ``300000`` Interval in milliseconds between
background
+ DEK rewrapping runs (default: 5
minutes).
+=============================== =============
=================================================
diff --git a/source/adminguide/storage.rst b/source/adminguide/storage.rst
index d1d0f2f6..186a1e04 100644
--- a/source/adminguide/storage.rst
+++ b/source/adminguide/storage.rst
@@ -602,7 +602,7 @@ can be attached to Instances, detached, re-attached, and
deleted
just as with the other types of data volume.
Local storage is ideal for scenarios where persistence of data volumes
-and HA is not required. Some of the benefits include reduced disk I/O
+and HA is not required. Some of the benefits include reduced disk I/O
latency and cost reduction from using inexpensive local disks.
In order for local volumes to be used, the feature must be enabled for
@@ -618,9 +618,25 @@ If you want to put a host into maintenance mode, you must
first stop any
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.
+
+.. warning::
+ Deleting the KMS key used to encrypt a volume will render that volume
permanently
+ unrecoverable.
+
+
To Create a New Volume
^^^^^^^^^^^^^^^^^^^^^^
+
#. Log in to the CloudStack UI as a User or admin.
#. In the left navigation bar, click Storage.
@@ -637,6 +653,10 @@ To Create a New Volume
- Disk Offering. Choose the characteristics of the storage.
+ - KMS Key. (Optional) Select a KMS key to enable envelope-based
+ encryption for the volume. Requires KMS to be configured in the zone.
+ See :ref:`key-management-system`.
+
The new volume appears in the list of volumes with the state
“Allocated.” The volume data is stored in CloudStack, but the volume
is not yet ready for use
